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.

100 KB
Raw Blame
import Arcade, { APIError } from "@arcadeai/arcadejs";
import {
  type ArcadeActions,
  type ArcadeFailure,
  ArcadeFailureError,
  authorizationRequirementOf,
  classify,
  requiredScopesOf,
  shapeOf,
  vendorStatusOf,
} from "./arcade";
import {
  type BrokerApp,
  type BrokerConnection,
  BrokerRefusalError,
  type ConnectedAppBroker,
  flagOf,
  type GrantState,
} from "./broker";

/**
 * THE VENDOR'S ONLY DOOR INTO THE SERVER. This is the one file under `server/src` that imports
 * `@arcadeai/arcadejs`, so a version bump has exactly this file to be read against, the same
 * convention `createComposioClient` states for its SDK. It imports the transport (`./arcade`) for
 * the `ArcadeFailure` shape; the transport never imports it, because that direction is a cycle and
 * `broker.ts` records why.
 */

/** Deeper than any real wrapping; a bound, so a cyclic `cause` cannot loop. */
const MAX_CAUSE_DEPTH = 16;

/**
 * THE TEXT A VENDOR FIELD CARRIES, OR NOTHING — AND A STRING WITH NO TEXT IN IT IS NOTHING.
 *
 * `""` is absence wearing a value's clothes, and answering it as a value is what breaks every
 * caller that then writes `textOf(a) ?? textOf(b)`: `??` falls through on null and undefined ONLY,
 * so an empty `provider_user_info.name` SHADOWED a perfectly good `login` and the Connected-accounts
 * screen drew a blank name on a connection that is genuinely connected. The emptiness belongs here,
 * in the function that claims to answer "is this text", and not in a `||` at each call site — one
 * of which would be forgotten. Whitespace-only is the same fact: a name of three spaces draws the
 * same blank.
 *
 * The value is returned UNTOUCHED when it has text; this answers whether there is any, it does not
 * reformat what the vendor sent. `authorize` below already spells this rule inline for `url` and
 * the authorization id (`typeof x !== "string" || x === ""`), which is the same judgement made one
 * field at a time.
 */
const textOf = (value: unknown): string | undefined =>
  typeof value === "string" && value.trim() !== "" ? value : undefined;

/**
 * Walk the `cause` chain to the FIRST `APIError` and read its `status` and the response body's
 * `error.name` / `error.message`. The SDK's own fields are `status`, `headers` and `error` (the
 * parsed body); nothing on it names the tool, so nothing here looks for one. No `APIError` anywhere
 * in the chain answers `null`.
 *
 * `status` is undefined for `APIConnectionError` and `APIUserAbortError`, which extend `APIError`:
 * no response was ever read, so the outcome is uncertain, not refused.
 */
export function normalizeArcadeError(error: unknown): ArcadeFailure | null {
  const seen = new Set<unknown>();
  let current: unknown = error;
  for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth += 1) {
    if (current === null || typeof current !== "object" || seen.has(current))
      return null;
    seen.add(current);
    /*
     * A REFUSAL THIS FILE ALREADY NORMALIZED ANSWERS ITSELF, and it is read on the same chain walk
     * rather than only at the top, because {@link vendorCall}'s answer is carried as a `cause` by
     * the one place that wraps it again (`revoke`, which fails over several connections at once).
     *
     * THIS IS WHAT KEEPS THE MEDIATION FROM COSTING ANYTHING. Every reader of a failure out of this
     * adapter — the authorize route's definite-or-uncertain decision, keyed on `status`; `callTool`'s
     * authorize prompt and `confirmReturn`'s `user_mismatch`, both keyed on the body's `error.name`
     * — asks through this function, so stopping the vendor's own `APIError` at the adapter boundary
     * takes nothing away from any of them. The vendor's PROSE is the only thing that does not come
     * back out; see {@link ArcadeFailureError}, which drops it.
     */
    if (current instanceof ArcadeFailureError) return current.failure;
    if (current instanceof APIError) {
      const body = current.error;
      const record =
        body !== null && typeof body === "object"
          ? (body as Record<string, unknown>)
          : {};
      return {
        status: typeof current.status === "number" ? current.status : undefined,
        name: textOf(record.name),
        message: textOf(record.message),
      };
    }
    current = (current as { cause?: unknown }).cause;
  }
  return null;
}

/**
 * THIS DEPLOYMENT'S ONE SENTENCE FOR "ARCADE ANSWERED, AND THE ANSWER HAD NO BODY IN IT".
 *
 * ONE SENTENCE AND NOT SEVERAL, because the fact is one fact wherever it lands: the socket carried
 * a status and no readable value under it — an empty 204, or a body whose whole JSON is `null`.
 * It is written in the uncertainty register {@link vendorCall}'s `APIConnectionError` sentence uses
 * ("is not known here") rather than the refusal register ("Arcade refused …"), because an empty
 * answer is not the vendor declining: whether the call took effect is genuinely unknown, and every
 * caller that spends a DELETE off this reading must treat it as unknown.
 *
 * NOT A SHAPE QUOTED BACK. The body is the thing this file exists to keep off an admin page; see
 * {@link vendorCall}. "No body" says all there is to say without quoting one.
 */
const unreadableBody = (step: string): string =>
  `Arcade answered ${step} with no body this deployment could read — an empty response, or one whose JSON is the literal null — so what it says is not known here.`;

/**
 * THE ANSWER'S BODY, OR THIS DEPLOYMENT'S REFUSAL — never a dereference of `null`.
 *
 * FOR THE CALLS THAT ARE NOT PAGED LISTINGS. A page goes through `OffsetPage`'s constructor, which
 * raises on a null body and is caught in {@link vendorCall}; `tools.authorize`, `auth.status` and
 * `auth.confirmUser` go through no constructor at all, so the SDK hands a literal `null` straight
 * back WEARING ITS DECLARED RESPONSE TYPE. The generated types are a description of what Arcade
 * sends today and are validated by nothing — the same reading `confirmReturn`'s `auth_id` check
 * already states one field down — so reading `answer.status` off one of those is the identical
 * unguarded dereference, raising the identical bare `TypeError` from inside this file instead.
 *
 * THE FIELD-LEVEL GUARDS BELOW STAY EXACTLY AS THEY ARE: this establishes only that there is an
 * object to read fields off, and says nothing about what is in it.
 */
function requireBody<T>(step: string, answer: T): T & object {
  if (answer === null || typeof answer !== "object") {
    throw new Error(unreadableBody(step));
  }
  return answer as T & object;
}

/**
 * ONE CALL TO THE VENDOR, WITH ITS REFUSAL TURNED INTO THIS DEPLOYMENT'S OWN SENTENCE.
 *
 * EVERY `client.*` CALL IN THIS FILE GOES THROUGH HERE, and that uniformity is the point rather
 * than a tidiness: the thing being confined is the SDK's `APIError`, whose `message` is
 * `${status} ${the response body}` (`core/error.js: makeMessage`), and one unwrapped call is one
 * path on which a vendor body reaches a log line, the Plugins page's `lastError`, a model's context
 * or an audit row. On this vendor a body is not inert — the auth paths answer with a bearer `url`
 * and a live `context.token` — and the claim this adapter is held to is that neither ever reaches
 * any of those. `step` is written HERE, at the call site, for the reason `callTool`'s refusal names
 * the action from the call site: nothing in an `APIError` says what was being asked.
 *
 * WHAT IS NOT AN SDK ERROR IS RETHROWN UNTOUCHED, which is deliberate: it leaves this file's own
 * refusals — the malformed-listing sentences, the mint with no url — exactly as they were.
 *
 * WITH ONE EXCEPTION, AND IT IS THE BODY THE SDK COULD NOT READ. A 204 with `content-length: 0`,
 * and a body whose JSON is the literal `null`, both reach `OffsetPage`'s constructor as `body ===
 * null` and raise a bare `TypeError: null is not an object (evaluating 'body.items')` from inside
 * `@arcadeai/arcadejs`, before one line of this file has looked at anything. Left to escape as
 * itself, that `TypeError` is the WRONG ANSWER TWICE: an operator reading the Plugins page gets a
 * vendor stack trace instead of this deployment's sentence, indistinguishable in the logs from a
 * programmer error here; and the only reason the revoke invariant holds on those two shapes is
 * that a crash is technically "not answering" — one tidy-up of the cast that raises it (a `?? []`,
 * say) turns both into `revoke` answering `false` with no DELETE spent, which is the live defect
 * `broker.ts:712-717` forbids. So the body this deployment could not read gets a REFUSAL, the same
 * one {@link requireBody} writes for the non-paged calls, and never a fallback to an empty list.
 *
 * THE ORDER IS WHAT MAKES THAT SAFE, and it is the whole of the old warning against catching "by
 * shape": `normalizeArcadeError` IS ASKED FIRST and every `APIError` answers it, so nothing
 * reaching the `TypeError` branch carries a vendor response at all. The `run()` closures here are
 * one `client.*` call each and nothing else, so a `TypeError` with no `APIError` anywhere in its
 * chain is the SDK failing to read an answer, which is exactly what the sentence says.
 *
 * A REFUSAL THAT IS ALREADY MEDIATED PASSES STRAIGHT THROUGH, so a nested call cannot dress one
 * sentence up in another.
 */
async function vendorCall<T>(step: string, run: () => Promise<T>): Promise<T> {
  try {
    return await run();
  } catch (error) {
    if (error instanceof ArcadeFailureError) throw error;
    const failure = normalizeArcadeError(error);
    if (!failure) {
      if (error instanceof TypeError) throw new Error(unreadableBody(step));
      throw error;
    }
    throw new ArcadeFailureError(
      failure.status === undefined
        ? // `status` is undefined for `APIConnectionError` and `APIUserAbortError`: no response was
          // ever read, so the outcome is uncertain rather than refused, and the sentence says so —
          // the authorize route keys exactly that distinction off `status`.
          `Arcade did not answer ${step}, so whether it ran is not known here.`
        : `Arcade refused ${step} with HTTP ${failure.status}.`,
      failure,
    );
  }
}

/**
 * Page size for the PER-TOOLKIT action listings, `grantsFor` and `authProvidersNamedBy`. A short
 * page ends it, never `total_count`. The whole-directory listing behind `listApps` does NOT use
 * this: see {@link DIRECTORY_PAGE_SIZE}.
 *
 * THE MEASURED WORST CASE, so the next person does not re-scan the API: across Arcade's directory
 * (8,320 tools, 129 toolkits) the largest toolkit is **`GithubApi`, 818 actions** — then
 * `PosthogApi` 766, `DatadogApi` 588, `ZohoBooksApi` 511, `HubspotCrmApi` 453. At 100 a page
 * costs ~1.19 s, so `GithubApi` read SEQUENTIALLY was 9 pages, ~10.7 s, past the 10 s
 * `VENDOR_CALL_TIMEOUT_MS` that wraps the grants screen and Disconnect alike: neither could load.
 * Under {@link CATALOGUE_CONCURRENCY} it is page one, then the other 8 in one wave, ~2.4 s.
 *
 * KEPT AT 100 RATHER THAN RAISED TO THE DIRECTORY'S 1000, deliberately. Latency, not size,
 * dominates (~1.19 s at 100, ~1.8 s at 1000), so two waves of 100 cost about what one page of
 * 1000 does. At 1000 every toolkit Arcade publishes would be ONE page, and the paths that make a
 * per-toolkit read trustworthy — a short page ending it, `seen < total` judged across pages, a
 * provider disagreeing with itself past page one — would stop being exercised by any real toolkit
 * while still being the only defence when one grows. At 100, every toolkit over 100 actions
 * crosses page boundaries on every read, so the completeness check stays a live check.
 */
const CATALOGUE_PAGE_SIZE = 100;

/**
 * How many per-toolkit action pages are in flight at once after page one has said how many there
 * are, through the same opt-in {@link Listing.concurrency} the directory uses.
 *
 * EIGHT, because it covers `GithubApi` (818 actions → 8 pages after the first) in ONE wave while
 * still bounding what a lying `total_count` can fire. The deadline arithmetic is
 * `~1.19 s × (1 + ⌈remaining / 8⌉)`: under 10 s up to 56 remaining pages, a toolkit of ~5,700
 * actions, for the grants screen. Disconnect spends ~3 more sequential calls after this listing
 * (auth providers, connections, the DELETE; ~1.2 s each, not measured separately), which leaves
 * room for 32 remaining pages, a toolkit of ~3,300 actions — four times `GithubApi`. Past that is
 * the number to revisit.
 */
const CATALOGUE_CONCURRENCY = 8;
/** A runaway guard, not a bound. */
const CATALOGUE_MAX_PAGES = 1000;

/**
 * Page size for the WHOLE-DIRECTORY listing `listApps` reads, which is the "Browse Arcade" screen.
 *
 * THE ARITHMETIC, MEASURED BY HAND ON 2026-10-14 against a live Arcade project, through this
 * deployment's own directory screen, so the next person changing this does not re-probe. Nothing in
 * CI re-checks it, and the directory's size will drift:
 * - Arcade's directory reported `total_count` **8,320** tools.
 * - `limit=1000` is accepted (1,000 items in ~1.77 s); `limit=5000` is REJECTED (empty answer in
 *   ~0.17 s), so **1000 is at or near the vendor's ceiling** — do not raise this past it.
 * - A page costs **~1.8 s** at limit 1000 (~1.2 s at 100, ~1.8 s at 250): latency, not size,
 *   dominates, so fewer larger pages are nearly free.
 *
 * At the old page size of 100 that was 84 SEQUENTIAL pages, ~100 s, against a 10 s
 * `VENDOR_CALL_TIMEOUT_MS` that wraps the WHOLE `listApps` — so the directory could never load. At
 * 1000 it is 9 pages: one, then the remaining 8 at once under {@link DIRECTORY_CONCURRENCY}, ~3.6 s.
 */
const DIRECTORY_PAGE_SIZE = 1000;

/**
 * How many directory pages are in flight at once after page one has said how many there are.
 *
 * EIGHT, because it covers today's directory in ONE wave (8,320 tools → 8 pages after the first)
 * while still being a bound: a `total_count` of a million fires eight requests at a time, never a
 * thousand. The deadline arithmetic is `~1.8 s × (1 + ⌈remaining / 8⌉)`, which stays under the 10 s
 * `VENDOR_CALL_TIMEOUT_MS` up to 32 remaining pages — a directory of roughly 33,000 tools, four times
 * today's. Past that the listing will time out again, and that is the number to revisit.
 */
const DIRECTORY_CONCURRENCY = 8;

/**
 * WHAT ARCADE ITSELF SENT: the parsed response body, and never the SDK's page object.
 *
 * `OffsetPage`'s constructor MANUFACTURES DEFAULTS for the two fields every listing here reads —
 * `this.items = body.items || []` and `this.total_count = body.total_count || 0` — so a field the
 * vendor never sent presents on the page as a well-formed empty answer. Read off the page, "Arcade
 * sent no items" is INDISTINGUISHABLE FROM "Arcade sent an empty list" and "Arcade sent no total"
 * is INDISTINGUISHABLE FROM "Arcade said zero": the `Array.isArray` guards below can never fire,
 * every `typeof reported === "number"` test passes on an absent field, and a malformed or truncated
 * listing commits as a complete one.
 *
 * `AbstractPage` keeps the parsed body untouched beside it, so the honest values are read from
 * there. The answer's own properties are the fallback for an answer that has NO `body` at all,
 * which is what `admin.authProviders.list` (a plain `APIPromise`, not a page) and every hand-built
 * stub return — those were never passed through a page constructor, so nothing was manufactured.
 *
 * AND THE PRESENCE OF `body` IS WHAT DECIDES WHICH OF THE TWO THIS IS — never whether the body
 * happens to be readable. `AbstractPage`'s constructor always assigns `body`, so the property
 * existing is the answer saying "I went through a page constructor, and my own `items` and
 * `total_count` are that constructor's inventions". From there the body is the ONLY honest
 * reading, and a body that is not a record means THE ANSWER COULD NOT BE READ — it does not mean
 * the answer was empty.
 *
 * MEASURED, because this is the hole the fallback left and it is the live defect again: a 200
 * carrying `content-type: text/html` — a proxy's courtesy page — parses to a STRING
 * (`internal/parse.js` returns `response.text()` for anything that is not JSON), so no record
 * exists anywhere and a `?? page` fallback hands back the page's manufactured `items: []`.
 * `listApps` then answered `[]`, `isConnected` answered false, and `revoke` answered `false` WITH
 * NO DELETE SPENT while the caller deleted the local row — `broker.ts:712-717`'s forbidden
 * outcome, reached by a route neither contributing guard could see, because both were written
 * against MALFORMED JSON and this is the branch where the JSON was never parsed at all.
 *
 * ANSWERING `null` IS THE REFUSAL, and deliberately not a throw from here: every caller already
 * has this deployment's own sentence for an unreadable listing — {@link pagedItems}' per-listing
 * `malformed`, and the transport's own `Array.isArray` guard for `listTools` — and routing through
 * them is what keeps one vocabulary on this seam instead of a second error shape invented here.
 */
function sentBody(answer: unknown): Record<string, unknown> | null {
  const page = record(answer);
  if (!page) return null;
  if ("body" in page) return record(page.body);
  return page;
}

/** A count's decimal spelling and nothing else: no sign, no exponent, no separator, no point. */
const COUNT_TEXT = /^[0-9]+$/;

/**
 * A COUNT ARCADE SENT, READ AS THREE OUTCOMES AND NEVER TWO: the number, `undefined` for a field
 * the vendor did not send, and `"unreadable"` for one it DID send in a shape this cannot read.
 *
 * THE THIRD OUTCOME IS THE WHOLE POINT. The previous reading was `typeof raw === "number" ? raw :
 * undefined`, which folded "the vendor did not say" together with "the vendor said something this
 * deployment cannot read" — and every caller treats the first as "there is nothing to cross-check
 * against". Measured: a vendor that serves 100 of 250 connections and spells the claim
 * `"total_count": "250"` had its truncation cross-check silently switched off, and `revoke`
 * DELETED 100, ANSWERED `true`, AND LEFT 150 GRANTS LIVE with no signal anywhere that the
 * withdrawal was partial. That is strictly worse than the `false`-with-no-DELETE defect this file
 * is full of warnings about: that one is at least visibly wrong.
 *
 * A NUMERIC STRING IS A LEGITIMATE SPELLING AND IS COERCED. `"250"` is the vendor saying 250 — it
 * is unambiguous, it is what a serializer that renders integers as text sends, and refusing it
 * would take Disconnect permanently offline for a deployment whose vendor always spells it so,
 * trading a silent partial for a hard failure with no way through. Coercing instead makes the
 * cross-check FIRE, which is what actually protects the invariant: the 250-of-100 listing above
 * now throws the `incomplete` sentence, no DELETE is spent, and the local row survives.
 *
 * EVERYTHING ELSE PRESENT REFUSES, and the strictness is deliberate, because a lenient parse is
 * how this defect comes back. `"many"`, `null`, an object, `true`, `NaN`, `Infinity`, a negative,
 * a fraction and `"1e3"` are all unreadable: anything that is not a plain non-negative decimal
 * integer is a value whose meaning this deployment would be guessing at. `NaN` in particular was
 * already slipping through the old `typeof` test and disabling the cross-check the same way a
 * string did — `seen < NaN` is false — so the number branch checks the VALUE and not just the type.
 *
 * ABSENT STAYS ABSENT. `total_count` is optional on the wire and the listings here end on a short
 * page, never on a total; a missing field must go on meaning "the vendor did not say" or every
 * engine that omits it would refuse.
 */
function countOf(raw: unknown): number | "unreadable" | undefined {
  if (raw === undefined) return undefined;
  if (typeof raw === "string") {
    const text = raw.trim();
    if (!COUNT_TEXT.test(text)) return "unreadable";
    const parsed = Number(text);
    return Number.isSafeInteger(parsed) ? parsed : "unreadable";
  }
  if (typeof raw !== "number") return "unreadable";
  return Number.isSafeInteger(raw) && raw >= 0 ? raw : "unreadable";
}

/** What the vendor sent, written into a refusal without pasting an object into a sentence. */
function shownValue(value: unknown): string {
  if (typeof value === "string") return JSON.stringify(value);
  if (value !== null && typeof value === "object") return "an object";
  return String(value);
}

/**
 * The `total_count` Arcade itself sent, or nothing. Read through {@link sentBody}, for its reason,
 * and through {@link countOf}, for ITS reason: a total the vendor sent in a shape this cannot read
 * THROWS the caller's own sentence rather than answering `undefined` and disabling the only
 * cross-check that can tell a truncated listing from a whole one.
 */
function reportedTotalOf(
  answer: unknown,
  unreadable: (shown: string) => string,
): number | undefined {
  const raw = sentBody(answer)?.total_count;
  const count = countOf(raw);
  if (count === "unreadable") throw new Error(unreadable(shownValue(raw)));
  return count;
}

/**
 * The `items` Arcade itself sent, UNCHECKED — the caller's own guard is what decides whether this
 * is a list. Read through {@link sentBody}, for its reason: off the page object, a listing that
 * sent no `items` at all reads as an empty one and no guard anywhere can tell them apart.
 */
function sentItemsOf(answer: unknown): unknown {
  return sentBody(answer)?.items;
}

/**
 * The HIGHEST total any page reported, never the LAST one.
 *
 * Keeping the last page's value loses the same way `reportedTotalOf` describes, one step later: an
 * engine that truncates at 250 of 300 and drops `total_count` on its short page would otherwise
 * erase the 300 that page one reported, and the cross-check would have nothing to compare against.
 */
const highestTotal = (
  total: number | undefined,
  reported: number | undefined,
): number | undefined =>
  reported === undefined
    ? total
    : total === undefined
      ? reported
      : Math.max(total, reported);

/** One listing's page size, runaway guard, page call and the three sentences a failure carries. */
type Listing = {
  pageSize: number;
  maxPages: number;
  page: (offset: number) => Promise<unknown>;
  malformed: string;
  unending: string;
  incomplete: (seen: number, total: number) => string;
  /**
   * What this deployment says when the vendor sent a `total_count` it cannot read. A sentence of
   * its own rather than a reuse of `malformed`: the list itself was fine and the CLAIM ABOUT ITS
   * LENGTH was not, and a reader sent looking for a broken list would find a well-formed one.
   */
  unreadableTotal: (shown: string) => string;
  /**
   * How many pages may be in flight at once AFTER PAGE ONE. Absent or 1 is the strictly sequential
   * read the connection and auth-provider listings use. `listApps` and the per-toolkit action
   * listings (`grantsFor`, `authProvidersNamedBy`) turn it on. Above 1, page one's `total_count` decides which further
   * offsets are fetched ahead, at most this many at a time; see {@link pagedItems}.
   */
  concurrency?: number;
};

/**
 * `run`, at most `limit` at a time, and NOT AT ALL once `abandoned()` says the reader has stopped.
 *
 * The second half is what keeps a lying `total_count` from costing anything: a listing that claims
 * a million rows and then ends on page two must not go on firing the 998 requests queued behind it.
 */
function bounded(
  limit: number,
  abandoned: () => boolean,
): <T>(run: () => Promise<T>) => Promise<T | undefined> {
  let active = 0;
  const waiting: (() => void)[] = [];
  return <T>(run: () => Promise<T>) =>
    new Promise<T | undefined>((resolve, reject) => {
      const start = () => {
        if (abandoned()) {
          resolve(undefined);
          waiting.shift()?.();
          return;
        }
        active += 1;
        // Through an executor, so a call that throws synchronously is a rejection like any other.
        new Promise<T>((answered) => answered(run()))
          .then(resolve, reject)
          .finally(() => {
            active -= 1;
            waiting.shift()?.();
          });
      };
      if (active < limit) start();
      else waiting.push(start);
    });
}

/**
 * ONE LISTING READ TO ITS END, as a stream of items.
 *
 * PAGINATION ENDS ON A SHORT PAGE, never on `total_count`, which is optional on the wire; the
 * reported total is a CROSS-CHECK and is taken through {@link reportedTotalOf} and
 * {@link highestTotal} so that "the vendor did not say" can never read as "the vendor said zero"
 * — nor, through {@link countOf}, as "the vendor said something unreadable". A cross-check with no
 * input is not a cross-check, and the listing it would have caught is the truncated one.
 *
 * THE SDK'S OWN AUTO-PAGINATION IS NOT USED by anything that goes through here, and that is the
 * point: `OffsetPage.nextPageRequestOptions` returns `null` the moment `total_count` is falsy, so
 * `for await (… of client.x.list(…))` silently stops after page one against any engine that omits
 * the field — and the caller cannot tell a complete answer from a first page of it.
 *
 * THE INCOMPLETENESS THROW IS THE LAST THING THIS YIELDS, after every item, so a caller that folds
 * items as they arrive still never sees a short listing finish as a whole one.
 *
 * FETCHING AHEAD ({@link Listing.concurrency}) CHANGES WHEN A PAGE IS ASKED FOR, NEVER HOW IT IS
 * READ. Page one is asked for alone; its `total_count` names the offsets that should exist, and
 * those are requested at once under the bound. The answers are then consumed IN OFFSET ORDER by
 * exactly the loop below, so every rule above still holds page by page: a short page still ends the
 * listing (the pages fetched past it are discarded unread and the queued ones never fire), a total
 * that UNDER-reports still reads on sequentially from where the prefetch ran out, and `seen < total`
 * still throws. A page ahead that FAILED fails the listing when the loop reaches it, and not before.
 * Without a readable total on page one there is nothing to fetch ahead of, and it reads sequentially.
 */
async function* pagedItems(listing: Listing): AsyncGenerator<unknown> {
  let seen = 0;
  let total: number | undefined;
  let ended = false;
  let stopped = false;
  const ahead = new Map<number, Promise<unknown>>();
  try {
    for (let index = 0; index < listing.maxPages; index += 1) {
      const fetched = ahead.get(seen);
      ahead.delete(seen);
      const answer = await (fetched ?? listing.page(seen));
      const items = sentItemsOf(answer);
      if (!Array.isArray(items)) throw new Error(listing.malformed);
      yield* items;
      seen += items.length;
      total = highestTotal(
        total,
        reportedTotalOf(answer, listing.unreadableTotal),
      );
      if (items.length < listing.pageSize) {
        ended = true;
        break;
      }
      if (
        index === 0 &&
        total !== undefined &&
        (listing.concurrency ?? 1) > 1
      ) {
        const slot = bounded(listing.concurrency ?? 1, () => stopped);
        // `floor`, not `ceil - 1`: a total that is an exact multiple of the page size still needs
        // the EMPTY page after it, because a short page — never the total — is what ends a listing.
        const last = Math.min(
          Math.floor(total / listing.pageSize),
          listing.maxPages - 1,
        );
        for (let page = 1; page <= last; page += 1) {
          const offset = page * listing.pageSize;
          const pending = slot(() => listing.page(offset));
          // Observed here so a page fetched past the end — or past a failure the loop throws on
          // first — never surfaces as an unhandled rejection. The loop still awaits the original.
          pending.catch(() => undefined);
          ahead.set(offset, pending);
        }
      }
    }
  } finally {
    stopped = true;
  }
  if (!ended) throw new Error(listing.unending);
  if (total !== undefined && seen < total) {
    throw new Error(listing.incomplete(seen, total));
  }
}

/** The verdict `classify` falls back to when it could not read a behaviour. See {@link isClassified}. */
const CLOSED_VERDICT = { effect: "write", destructive: true } as const;

/**
 * Whether ARCADE classified this action, as against this deployment falling back for it.
 *
 * `classify` from `./arcade` is the one reading of `metadata.behavior` anywhere here, and it is
 * deliberately TOTAL: anything it cannot read answers the closed `{ write, destructive }` verdict,
 * so an unannotated action is approved like a deletion. That fallback is exactly what must not be
 * counted — counted, `AirtableApi`'s `metadata: null` actions would report as classified, and the
 * coverage warning that exists to name them would never fire.
 *
 * AN EMPTY `behavior` IS NOT A CLASSIFICATION EITHER, and `classify` is where that is decided: a
 * block stating neither flag answers the closed verdict, so it arrives here as the fallback it is
 * and the `flagOf(behavior.destructive, false)` below — the collision-breaker, not a second reading
 * of the wire — answers `false` for it. Were `{}` read as a plain write, every such action would
 * report as classified and the coverage warning would miss exactly the actions it exists to name,
 * the same way `AirtableApi`'s `metadata: null` actions would.
 *
 * THE CLOSED VERDICT IS ALSO A REAL ANSWER, which is the only subtlety here: `Attio.RemoveFromList`
 * genuinely publishes `destructive: true` and lands on the same pair. So the verdict is read first,
 * and only that one collision is broken — by asking whether Arcade actually sent a `behavior` whose
 * `destructive` flag reads true, through `flagOf`, the same function `classify` reads it with and
 * never a second parse of the wire.
 *
 * NEVER THE `Api` SUFFIX (spec D8). `AirtableApi` and `GithubApi` are unannotated today and
 * `Apollo` is annotated, so the suffix correlates beautifully — and it is Arcade's naming
 * convention rather than a contract. A rule reading it is a guess wearing a measurement's clothes,
 * right until Arcade curates `DatadogApi`.
 */
function isClassified(metadata: unknown): boolean {
  const verdict = classify(metadata);
  if (
    verdict.effect !== CLOSED_VERDICT.effect ||
    verdict.destructive !== CLOSED_VERDICT.destructive
  ) {
    return true;
  }
  const behavior = record(record(metadata)?.behavior);
  return behavior !== null && flagOf(behavior.destructive, false) === true;
}

/**
 * The oauth2 scopes one listed action asks for, for the catalogue's counts — read through
 * {@link requiredScopesOf}, the one reading `grantStateOf` and the transport's listing share.
 *
 * AN UNREADABLE SCOPES BLOCK REFUSES, as {@link requiresAuthorization} refuses an unreadable
 * authorization block, and for its reason: `[]` here files the action as unscoped — "the connection
 * itself is the grant" — so a block this deployment could not read would be counted as the vendor
 * saying no separate permission exists. The SHAPE (`authorizationRequirementOf`, `shapeOf`) lives in
 * `./arcade` because the transport's own listing reads the same block for the scopes the gate checks.
 */
function scopesOf(item: unknown, toolkit: string): string[] {
  const read = requiredScopesOf(item);
  if (read.kind === "read") return read.scopes;
  throw new BrokerRefusalError(
    `Arcade sent ${read.shape} where the ${read.field === "requirements" || read.field === "authorization" ? read.field : `oauth2 ${read.field}`} of one of ${toolkit}'s actions belongs, and that is what says which permissions connecting ${toolkit} asks for. A shape this deployment cannot read is not "no separate permission", so the catalogue stops here rather than count it as one. That is a change in what Arcade answers rather than a setting an operator can correct, so upgrading this deployment's @arcadeai/arcadejs is what fixes it.`,
  );
}

/**
 * Whether ARCADE SAYS this action needs a person to authorize it — read, never assumed.
 *
 * THIS REPLACES A HARDCODED `{ kind: "consent" }` THAT WAS A CLAIM ABOUT THE VENDOR MADE WITHOUT
 * READING THE VENDOR. Every toolkit in the catalogue was announced to the rest of this deployment
 * as an app somebody connects by clicking through a consent screen, and the live listing says
 * otherwise about real apps: `Apollo` publishes NO `requirements.authorization` and one
 * deployment-wide secret (`APOLLO_API_KEY`) instead — verbatim in `fixtures/arcade-catalogue.json`
 * — so Connect sent somebody to a consent flow for a connection consent cannot complete, and
 * `tools.authorize` was minted for an action that requires no authorization at all.
 *
 * AN AUTHORIZATION BLOCK IS THE WHOLE OF THE QUESTION, AND SECRETS ARE NOT PART OF IT. The two are
 * different people's work and {@link grantStateOf} already keeps them apart for the same reason:
 * a secret is set ONCE FOR EVERYBODY by an operator in the Arcade dashboard — {@link FIELDS_REFUSAL}
 * is this deployment's standing sentence about that — so it is not something the person connecting
 * can supply, and an app that asks only for one asks THEM for nothing. It is therefore `no-auth`
 * here and `needs-operator` on the grants screen, which is the channel that already names the keys.
 * Calling it `fields` would draw a form collecting one person's answer and share it with everyone;
 * calling it `unsupported` would hide the app from the picker for good, including after the
 * operator sets the secret and the app works perfectly.
 *
 * ANY ONE ACTION'S AUTHORIZATION MAKES THE TOOLKIT A CONSENT APP, because the question this answers
 * is "how would somebody connect this app", and a toolkit with one authorized action has a consent
 * flow that is how they reach it. Arcade grants per action, so the grants screen is where an action
 * that needs nothing is told apart from one that does.
 *
 * AND A SHAPE THIS DEPLOYMENT CANNOT READ REFUSES RATHER THAN ANSWERING EITHER WAY. Both wrong
 * answers are silent: a guessed `consent` is the defect above, and a guessed `no-auth` records an
 * app as needing no connection, which hides the Connect button on an app that does. `routes.ts`
 * holds the catalogue for the picker and the enable path both, so one refusal an operator can act
 * on is worth more than several hundred rows, one of which is a guess — `connectionOf` in
 * `composio-adapter.ts` gives that reasoning in full. `null` and an absent field are NOT unreadable
 * shapes: they are the vendor saying this action requires nothing, which `AirtableApi`'s
 * `metadata: null` shows Arcade does say.
 */
function requiresAuthorization(item: unknown, toolkit: string): boolean {
  const read = authorizationRequirementOf(item);
  if (read.kind === "unreadable" && read.field === "requirements") {
    throw new BrokerRefusalError(
      `Arcade sent ${read.shape} where ${toolkit}'s requirements belong, and that field is what says whether somebody has to authorize this app at all. A shape this deployment cannot read is not the vendor saying "nothing to authorize", so it is not read as one — the catalogue stops here rather than offer ${toolkit} under a flow nobody established it has. That is a change in what Arcade answers rather than a setting an operator can correct, so upgrading this deployment's @arcadeai/arcadejs is what fixes it.`,
    );
  }
  if (read.kind === "unreadable") {
    throw new BrokerRefusalError(
      `Arcade sent ${read.shape} where ${toolkit}'s authorization requirement belongs, and this deployment reads that object to decide whether connecting ${toolkit} means sending somebody to a consent screen. A shape this deployment cannot read decides neither way, so the catalogue stops here rather than guess. That is a change in what Arcade answers rather than a setting an operator can correct, so upgrading this deployment's @arcadeai/arcadejs is what fixes it.`,
    );
  }
  return read.kind === "required";
}

/**
 * The flow an app gets, from the one fact {@link requiresAuthorization} measured over its actions.
 *
 * TWO OF THE FIVE KINDS AND NOT THE OTHER THREE, deliberately. `fields` and `self-registering` are
 * Composio's shapes: Arcade has no per-person field entry ({@link FIELDS_REFUSAL}) and registers no
 * client at consent time. `unsupported` is a verdict about an app this deployment cannot drive, and
 * both answers here are apps it drives — the unreadable case REFUSES rather than landing here.
 */
function connectionOf(authorizes: boolean): BrokerConnection {
  return authorizes ? { kind: "consent" } : { kind: "no-auth" };
}

/**
 * Every toolkit Arcade publishes, with `actionCount` taken from the FULL PAGED tool listing.
 *
 * COUNTED, NEVER READ OFF PAGE ONE: `GithubApi` publishes hundreds of actions where `Github`
 * publishes 43, so a first page of 100 would be a wrong answer in the picker. Pagination ends on a
 * short page; `total_count` is optional on the wire and is used only as a cross-check.
 *
 * THE OTHER THREE FACTS ARE COUNTED IN THIS SAME FOLD, BEFORE THE TOOLS ARE DISCARDED, and that is
 * the whole of why they are free: the listing is already paged to the end for `actionCount`, so no
 * second listing and NO EXTRA VENDOR CALL is made for them.
 *
 * `permissionCount` is the number of DISTINCT NON-EMPTY scope sets, held per toolkit as sorted,
 * joined strings — SORTED BEFORE JOINED, so `[a,b]` and `[b,a]` are one permission asked for twice.
 * An action with NO scopes joins no group: Github's 43 actions all carry an `oauth2` block with no
 * scopes and one read consent flipped 43 of 43 to `met: true`, so "no scopes" means "the connection
 * itself is the grant", not "needs nothing" — such an action is not separately approvable.
 * `scopedActionCount` is what keeps that from reading as one permission covering everything.
 */
async function listApps(client: Arcade): Promise<BrokerApp[]> {
  /**
   * The fold's own tally, with PLAIN NUMBERS. `BrokerApp`'s three counts are nullable because
   * another provider may not measure them; this provider does, on every action it folds, so a
   * nullable accumulator here would only be a null nothing can produce, narrowed at every `+= 1`.
   * `permissions` holds the sorted-and-joined scope sets; empty sets never enter it.
   */
  type Tally = Omit<
    BrokerApp,
    "classifiedCount" | "connection" | "permissionCount" | "scopedActionCount"
  > & {
    classifiedCount: number;
    scopedActionCount: number;
    permissions: Set<string>;
    /**
     * Whether any action folded so far carries an authorization requirement — the ONE fact
     * {@link connectionOf} turns into this app's flow, and a fold rather than a literal because the
     * listing is per ACTION and the flow is per TOOLKIT.
     */
    authorizes: boolean;
  };
  const counts = new Map<string, Tally>();
  for await (const item of pagedItems({
    pageSize: DIRECTORY_PAGE_SIZE,
    maxPages: CATALOGUE_MAX_PAGES,
    concurrency: DIRECTORY_CONCURRENCY,
    page: (offset) =>
      vendorCall("the app catalogue listing", () =>
        client.tools.list({ limit: DIRECTORY_PAGE_SIZE, offset }),
      ),
    malformed:
      "Arcade did not answer with a tool list, so its app catalogue could not be read.",
    unending: `Arcade's catalogue never ended after ${CATALOGUE_MAX_PAGES} pages, so it is not trusted.`,
    incomplete: (seen, total) =>
      `Arcade listed ${seen} of ${total} actions, so its app catalogue is incomplete.`,
    unreadableTotal: (shown) =>
      `Arcade reported its app catalogue's total_count as ${shown}, which is not a count, so whether the catalogue was listed in full could not be checked.`,
  })) {
    const toolkit = (
      item as { toolkit?: { name?: unknown; description?: unknown } } | null
    )?.toolkit;
    // AN EMPTY NAME IS NO NAME, the same judgement {@link textOf} makes: the name is this app's
    // SLUG as well as its label, so an action whose toolkit is named `""` would otherwise raise a
    // blank, unconnectable row in the picker rather than being skipped as unreadable.
    const name = textOf(toolkit?.name);
    if (!name) continue;
    const classified = isClassified(record(item)?.metadata);
    // READ OFF THIS ACTION, never written down for the catalogue; see {@link requiresAuthorization}.
    // Asked AFTER the name, so a refusal can say which app it is about, and BEFORE the scopes, so an
    // unreadable authorization block is refused in that function's words rather than the scopes'.
    const authorizes = requiresAuthorization(item, name);
    const scopes = scopesOf(item, name);
    const standing =
      counts.get(name) ??
      ({
        slug: name,
        name,
        // An absent description IS an empty one here: the field is a label with a blank default,
        // not an identity, so nothing is shadowed by the two reading alike.
        description: textOf(toolkit?.description) ?? "",
        // NEITHER IS A STAND-IN FOR SOMETHING UNREAD: a tool's `toolkit` object carries `name`,
        // `description` and `version` and nothing else — the SDK's `ToolDefinition.Toolkit` says
        // so and the live listing agrees — so these two are Arcade publishing no logo and no
        // category, which is what `BrokerApp.logo` is nullable for. A logo, where one exists, is
        // filled in afterwards by `backfillBrokeredLogos` from outside the vendor's listing.
        logo: null,
        categories: [],
        actionCount: 0,
        classifiedCount: 0,
        scopedActionCount: 0,
        permissions: new Set<string>(),
        authorizes: false,
      } satisfies Tally);
    standing.actionCount += 1;
    if (classified) standing.classifiedCount += 1;
    if (authorizes) standing.authorizes = true;
    if (scopes.length > 0) {
      standing.scopedActionCount += 1;
      // SORTED, THEN JOINED. The other order makes one permission into two the first time the
      // vendor lists the same scopes in a different sequence.
      standing.permissions.add([...scopes].sort().join(" "));
    }
    counts.set(name, standing);
  }
  // `permissionCount` IS READ OFF THE FINISHED SET, never kept per page: a size taken mid-listing
  // is a count of the sets seen so far, which is a different number on every page but the last.
  // `connection` IS READ OFF THE FINISHED FOLD for `permissionCount`'s reason: a kind decided
  // mid-listing is a verdict about the actions seen so far, and the action that carries the
  // authorization may be on the last page.
  return [...counts.values()].map(({ permissions, authorizes, ...app }) => ({
    ...app,
    permissionCount: permissions.size,
    connection: connectionOf(authorizes),
  }));
}

const FIELDS_REFUSAL =
  "Arcade has no per-person field entry: what it asks for is a deployment-wide secret (admin.secrets, e.g. GITHUB_SERVER_URL) that an operator sets once for everybody, so a form asking a person to type one would collect a value that is not theirs and share it with everyone. Set it in the Arcade dashboard instead.";

type ConnectionRow = Arcade.Admin.UserConnectionResponse;

/** Page size for the auth-provider configuration listing. A short page ends it, as `listApps`. */
const AUTH_PROVIDER_PAGE_SIZE = 100;
/** A runaway guard, not a bound. */
const AUTH_PROVIDER_MAX_PAGES = 100;

/** Page size for the user-connection listing. A short page ends it, as `listApps`. */
const CONNECTION_PAGE_SIZE = 100;
/** A runaway guard, not a bound. */
const CONNECTION_MAX_PAGES = 100;

/**
 * The INSTANCE ids of every auth provider this project has configured of one TYPE.
 *
 * THERE ARE THREE THINGS AND THEY NEED THREE WORDS. `provider` in this codebase is the BROKER
 * (`arcade`); `authProvider` is the vendor's OAuth provider TYPE (`google`); and this is the third,
 * the provider INSTANCE — an operator's configuration OF a type, which Arcade keys by its own id
 * (`google-openbot`, `arcade-google`, `cpk-poc`). On an auth-provider config `id` is the INSTANCE
 * and `provider_id` is the TYPE. Verbatim from the live project:
 *
 * ```
 * {"id":"cpk-poc",        "provider_id":"github", "type":"oauth2", "status":"active"}
 * {"id":"google-openbot", "provider_id":"google", "type":"oauth2", "status":"active"}
 * {"id":"arcade-google",  "provider_id":"google", "type":"oauth2", "status":"active"}
 * ```
 *
 * A SET AND NEVER ONE ID: `arcade-google` and `google-openbot` are both of type `google`, and a
 * person may hold a connection under either. Reducing to one would drop real connections.
 *
 * PAGED, AND A MALFORMED LISTING THROWS, on `listApps`' argument and with its guards: a truncated
 * config list would silently answer "not connected" for whoever is held under an instance that fell
 * off the end. Folded to lower case on the way in, so the comparison is Amendment 16's.
 */
async function authProviderInstances(
  client: Arcade,
  authProvider: string,
): Promise<Set<string>> {
  const wanted = authProvider.toLowerCase();
  const instances = new Set<string>();
  for await (const item of pagedItems({
    pageSize: AUTH_PROVIDER_PAGE_SIZE,
    maxPages: AUTH_PROVIDER_MAX_PAGES,
    page: (offset) =>
      vendorCall(
        `the auth-provider configuration listing for ${authProvider}`,
        () =>
          client.admin.authProviders.list({
            query: { limit: AUTH_PROVIDER_PAGE_SIZE, offset },
          }),
      ),
    malformed: `Arcade did not answer with an auth-provider list, so the configurations of ${authProvider} its connections are held under could not be read.`,
    unending: `Arcade's auth-provider list never ended after ${AUTH_PROVIDER_MAX_PAGES} pages, so it is not trusted.`,
    incomplete: (seen, total) =>
      `Arcade listed ${seen} of ${total} auth providers, so its configuration list is incomplete.`,
    unreadableTotal: (shown) =>
      `Arcade reported its auth-provider list's total_count as ${shown}, which is not a count, so whether the configurations of ${authProvider} were listed in full could not be checked.`,
  })) {
    const config = record(item);
    const instance = textOf(config?.id);
    if (instance && textOf(config?.provider_id)?.toLowerCase() === wanted) {
      instances.add(instance.toLowerCase());
    }
  }
  return instances;
}

/**
 * The connections an account holds under a toolkit's AUTH PROVIDER.
 *
 * FILTERED ON THE PROVIDER, NOT THE TOOLKIT NAME — AND NOT ON THE PROVIDER TYPE EITHER. Both halves
 * of that are measured, and the second is why this reads a third listing rather than comparing two
 * strings.
 *
 * THE TOOLKIT NAME IS THE WRONG SPELLING because a provider equals the toolkit only when an
 * operator happened to name it so (`Github`, `Asana`, `Attio`); one Google connection serves
 * `Gmail` and `GoogleCalendar` both. So the toolkit is resolved through `authProviderOf`, which is
 * where that mapping lives.
 *
 * AND `authProviderOf`'S ANSWER IS ALSO THE WRONG SPELLING FOR A CONNECTION ROW, because
 * `provider_id` MEANS TWO DIFFERENT THINGS ON THE TWO OBJECTS. Measured once, in the 2026-10-13 run
 * of `tests/arcade-live.test.ts` against a live Arcade project; nothing in CI re-checks it (see
 * `docs/plugins/arcade.md`):
 *
 * - on a tool listing, `requirements.authorization.provider_id` — what `authProviderOf` reads — is
 *   the provider TYPE: `"google"`;
 * - on a user-connection row, `provider_id` is the provider INSTANCE id, the operator's
 *   configuration: `"google-openbot"`, `"arcade-google"`, `"cpk-poc"`.
 *
 * A connection row's full key set, verbatim, carries NO vendor-type field at all: `id`,
 * `provider_type`, `connection_id`, `connection_status`, `scopes`, `user_id`, `provider_id`,
 * `provider_description`, `provider_user_info` — and `provider_type` is `"oauth2"`, the auth SCHEME
 * rather than the vendor. The instance id is the ONLY link to the vendor. So `"google"` never
 * equals `"google-openbot"`, a direct comparison matches nothing on any real deployment — with
 * Arcade's own default providers too, which are `arcade-google` and `arcade-github` and never the
 * bare type — and `isConnected` reads false, `accountName` null, and `revoke` false WITHOUT
 * SPENDING A DELETE, so nothing is ever revoked at the vendor. Do not "simplify" this back: every
 * fixture that spells the two sides alike hides it.
 *
 * The bridge is {@link authProviderInstances}: the type `authProviderOf` answered is expanded, once
 * per call, into the SET of configured instance ids of that type, and a row matches when its
 * `provider_id` is in that set (case-insensitively — Amendment 16's client-side fold stands). Both
 * the provider and the configuration list are read ONCE per call, never per row.
 *
 * PAGED THROUGH {@link pagedItems}, NEVER THROUGH THE SDK'S `for await (… of … .list(…))`. That
 * iterator asks `OffsetPage.nextPageRequestOptions`, which returns `null` the moment `total_count`
 * is falsy — and the constructor coerces an ABSENT `total_count` to `0`. So against any engine that
 * omits the field, the SDK's own auto-pagination stops after page one: measured at 30 connections
 * served 10 to a page, ONE request went out, `isConnected` answered `true`, `accountName` read a
 * name off page one, and `revoke` DELETED TEN AND ANSWERED `true` while twenty connections stayed
 * live at the vendor. That is the outcome `revoke`'s own comment forbids — a partial ask reading as
 * a clean success. Reading to a SHORT PAGE instead ends on evidence the engine cannot omit, and an
 * unverifiable listing THROWS rather than answering short, so no caller here can mistake a first
 * page for the whole of what somebody holds.
 *
 * A ROW UNDER AN INSTANCE THE CONFIG LIST DOES NOT NAME DOES NOT MATCH — a provider configuration
 * deleted while a connection outlives it. That is fail-closed: the row is left alone rather than
 * deleted on a guess about which vendor it belongs to.
 *
 * EVERY ATTRIBUTABLE ROW IS RETURNED, DEAD ONES INCLUDED, AND LIVENESS IS THE CALLER'S QUESTION.
 * A row carries its own `connection_status`, and {@link connectionIsLive} reads it — but here,
 * because the two kinds of caller need opposite things from a row the vendor reports as finished:
 * `isConnected` and `accountName` must not count it, and `revoke` must still delete it. Filtering it
 * out at this level would answer both at once, and the one it answered wrongly would be the
 * destructive one.
 *
 * AN UNRESOLVED TOOLKIT REFUSES, AND DOES NOT FALL BACK TO THE TOOLKIT NAME. The fallback is
 * refused for the reason it always was — it would silently restore the instance/type defect under
 * a different spelling, invisibly against every fixture in the tree. But ANSWERING NO ROWS IS NOT
 * THE OTHER OPTION, and that is this function's own measured defect. A toolkit whose actions name
 * ZERO provider ids, or TWO OR MORE of them, is not a toolkit with no connections: it is a listing
 * this deployment could not read an attribution out of. Answering `[]` for it made `isConnected`
 * false and `accountName` null for somebody genuinely connected — so Connect minted a SECOND
 * authorization beside the live one — and made `revoke` answer `false` ("there was nothing to
 * withdraw") WITHOUT SPENDING A SINGLE DELETE, while `store.ts`'s disconnect path deletes the
 * local `brokered_connections` row on that answer regardless. The outcome is the one
 * `broker.ts`'s `revoke` contract forbids outright: a LIVE grant at the vendor that no row this
 * deployment holds any longer names, and no way back but guessing which app it belonged to.
 *
 * So an unattributable toolkit throws a {@link BrokerRefusalError} naming what the listing said,
 * exactly as a malformed one does — `authProviderOf` and {@link authProviderInstances} THROW on a
 * listing that is malformed, truncated against its own reported total, or never-ending, and this
 * joins them. All three lifecycle members refuse together, which is the point: the refusal reaches
 * the Disconnect path BEFORE any local row is deleted, so the row is still standing on the second
 * press, and the Connect screen says why rather than offering a second grant.
 *
 * THE SEAM'S `authProviderOf` STILL ANSWERS `null`, and that is not the same decision. Its caller
 * is the sibling resolver in `store.ts`, which counts an unresolved app as `unanswered` and ends
 * NOTHING for it — fail-closed on a question that spends no delete. Here the question is the
 * destructive one.
 */
async function connectionsFor(
  client: Arcade,
  vendorUserId: string,
  toolkit: string,
): Promise<ConnectionRow[]> {
  const { named, unreadable } = await authProvidersNamedBy(client, toolkit);
  // FIRST, because an unreadable action makes both counts below unreliable: it may name none, the
  // one already read, or another.
  if (unreadable) {
    throw new BrokerRefusalError(
      unreadableProviderSentence(toolkit, unreadable),
    );
  }
  if (named.size !== 1) {
    throw new BrokerRefusalError(
      named.size === 0
        ? `Arcade's action listing for ${toolkit} names no auth provider at all, so which of this account's connections belong to ${toolkit} could not be read. Nothing was read as connected and nothing was withdrawn — a connection may still be live at the vendor. Give ${toolkit} an auth provider in the Arcade dashboard and try again.`
        : `Arcade's action listing for ${toolkit} names ${named.size} different auth providers (${[...named].sort().join(", ")}), so which of this account's connections belong to ${toolkit} could not be read. Nothing was read as connected and nothing was withdrawn — a connection may still be live at the vendor. Settle ${toolkit} on one auth provider in the Arcade dashboard and try again.`,
    );
  }
  // The one id, taken off the set the refusal above has already narrowed to exactly one.
  const [authProvider] = [...named];
  const instances = await authProviderInstances(client, authProvider);
  const rows: ConnectionRow[] = [];
  for await (const item of pagedItems({
    pageSize: CONNECTION_PAGE_SIZE,
    maxPages: CONNECTION_MAX_PAGES,
    page: (offset) =>
      vendorCall(`the connection listing for ${toolkit}`, () =>
        client.admin.userConnections.list({
          user_id: vendorUserId,
          limit: CONNECTION_PAGE_SIZE,
          offset,
        }),
      ),
    malformed: `Arcade did not answer with a connection list, so what this account holds at ${toolkit} could not be read.`,
    unending: `Arcade's connection list never ended after ${CONNECTION_MAX_PAGES} pages, so it is not trusted.`,
    incomplete: (seen, total) =>
      `Arcade listed ${seen} of ${total} connections, so what this account holds at ${toolkit} could not be read in full.`,
    unreadableTotal: (shown) =>
      `Arcade reported its connection list's total_count as ${shown}, which is not a count, so whether what this account holds at ${toolkit} was listed in full could not be checked.`,
  })) {
    /*
     * A ROW THAT IS NOT AN OBJECT IS A HOLE IN THE LISTING, AND A HOLE IS NOT A ROW TO SKIP.
     *
     * `items: [null]` is what the live API sent here, and `item as ConnectionRow` believed it: the
     * very next line read `row.provider_id` off `null` and raised a bare `TypeError`, which is the
     * wrong answer in both directions. It carries a stack trace onto the Disconnect path where
     * this deployment's own sentence belongs; and the only reason the revoke invariant held on
     * this shape was that a crash is technically "not answering" — make the cast defensive with a
     * skip or a `?? []` and the listing silently becomes two rows instead of three, which is
     * `revoke` answering off a listing it could not read whole, the exact outcome
     * `broker.ts:712-717` forbids.
     *
     * SO IT REFUSES, in the register of this listing's own `malformed` sentence one block up: the
     * unreadable row is not attributable to any provider instance, and a DELETE spent on the rows
     * BESIDE it would be a partial ask reported as a clean success.
     */
    // ARRAYS ARE REFUSED WITH THE REST, which {@link record} alone would not do — it answers a
    // list as an object, and a list has no `provider_id`, so the row would be dropped silently
    // and the listing would again be read short.
    const row = Array.isArray(item) ? null : record(item);
    if (!row) {
      throw new Error(
        `Arcade's connection list carried ${shapeOf(item)} where a connection belongs, so what this account holds at ${toolkit} could not be read.`,
      );
    }
    const instance = textOf(row.provider_id)?.toLowerCase();
    if (instance !== undefined && instances.has(instance))
      rows.push(row as ConnectionRow);
  }
  return rows;
}

/**
 * The one `connection_status` measured on a usable connection at the live API: `"active"`.
 *
 * AN ALLOWLIST OF THE LIVE SPELLING RATHER THAN A DENYLIST OF THE DEAD ONES, because the dead
 * vocabulary cannot be enumerated from here — the SDK declares the field as a bare
 * `connection_status?: string` with no union, and a denylist missing one spelling would go on
 * reading that spelling as connected, which is the defect itself.
 */
const LIVE_CONNECTION_STATUS = "active";

/**
 * The `status` spellings a FRESH MINT may answer under which sending somebody to the consent screen
 * is the right next step: the flow has not begun (`not_started`) or is waiting for them (`pending`).
 *
 * AN ALLOWLIST, AND NOT THE SDK'S UNION TURNED AROUND, for {@link LIVE_CONNECTION_STATUS}'s reason.
 * `AuthorizationResponse.status` is declared as a four-way union in the generated types, but the
 * union is a description of what Arcade sends today, not a constraint on what arrives: a spelling
 * outside it deserializes with no complaint from anybody. The two outcomes that are NOT a consent
 * screen — `completed` and `failed` — are therefore refused by absence rather than by name, so that
 * a fifth spelling is refused with them instead of being handed to a browser as a live redirect.
 *
 * SEPARATE FROM {@link grantStateOf}'S READING, deliberately. That one reads the LISTING's
 * `requirements.authorization`, whose vocabulary is `token_status` plus an `active`/`inactive`
 * status, and whose question is "what does this account already hold". This one reads a mint's own
 * answer, whose question is "is a consent screen what happens next". Sharing a table between them
 * would make one vendor's change to either vocabulary move the other answer too.
 */
const MINT_AWAITS_CONSENT_STATUSES = new Set(["not_started", "pending"]);

/**
 * The listing's `token_status` spellings under which this account holds no usable token and a
 * consent is what would give it one. `completed` is the held grant; anything else is `unknown`.
 * Kept apart from {@link MINT_AWAITS_CONSENT_STATUSES} for the reason that set's docblock gives,
 * even where the spellings overlap: `failed` belongs here (a failed token is one to consent again
 * for) and not there (a failed MINT is not a consent screen to send somebody to).
 */
const TOKEN_AWAITS_CONSENT_STATUSES = new Set([
  "not_started",
  "pending",
  "failed",
]);

/**
 * Whether a connection row is one somebody can actually USE, read off the row's OWN `connection_status`.
 *
 * THE ROW'S EXISTENCE IS NOT THE ANSWER, WHICH IS WHAT THIS IS FOR. A user-connection row carries
 * `connection_status` beside its ids — it is in the key set {@link connectionsFor} quotes verbatim
 * — and that field is the vendor saying whether the connection still works. Treating a row's mere
 * presence as a yes answers `isConnected: true`, with a name beside it, for a connection Arcade is
 * reporting as expired, revoked at the provider, pending or failed. Nothing then goes wrong until a
 * tool call fails, far from the screen that said Connected, with no way back but guessing.
 *
 * SILENCE IS NOT A NO. An ABSENT status — the key missing, `undefined` or `null` — reads as live,
 * deliberately: the field is OPTIONAL on the wire (`connection_status?: string`), so a pessimistic
 * reading would answer "not connected" for every real connection against any engine that omits it
 * — `isConnected` false and `accountName` null — which is precisely the live defect this seam
 * already suffered once when it compared a provider TYPE to a provider INSTANCE. The rule is
 * therefore: the vendor said something other than live → not live; the vendor said nothing → the
 * existence of the row is all the evidence there is, and it stands.
 *
 * BUT A STATUS THAT IS PRESENT AND CANNOT BE READ IS NOT SILENCE. `{}`, `false`, `0`, a list, or a
 * BLANK string is the vendor saying SOMETHING about this connection in a shape this deployment does
 * not read — and "live" is the one answer that would act on it. It reads as not live, by
 * {@link vendorStatusOf}'s rule: a blank string on a field whose value is a decision is unreadable,
 * the judgement `authProvidersNamedBy` already makes of a blank `provider_id`. (This file once said
 * "absent or empty reads as live"; the empty half is withdrawn, so that one rule — absent is
 * `undefined`/`null`, blank is unreadable — holds on every vendor authorization field.)
 *
 * FOLDED AND TRIMMED, Amendment 16's client-side fold, for the reason every other comparison in
 * this file is: a case the vendor changes must not change an answer about somebody's account.
 *
 * NOT A FILTER ON {@link connectionsFor}. `revoke` must still delete a dead row — it is a row at the
 * vendor, and leaving it behind as unreachable debris while answering `false` ("there was nothing")
 * is the failure mode `revoke`'s own contract forbids. So the listing stays whole and only the
 * POSITIVE reads — `isConnected`, `accountName` — ask this question.
 */
function connectionIsLive(row: ConnectionRow): boolean {
  const status = vendorStatusOf(row.connection_status);
  if (status.kind === "absent") return true;
  return status.kind === "text" && status.text === LIVE_CONNECTION_STATUS;
}

/**
 * DELETE TAKES `connection_id` (`ac_...`), NOT `id` (`at_...`). A user-connection row carries both
 * and the listing prints `id` FIRST; the SDK declares `delete(id: string)` and does not say which.
 * Measured by hand on 2026-10-12 against a live Arcade project, with a script that is not in this
 * repository, and re-checked by nothing in CI: `at_...` answers 500, `ac_...` answers 204. Reading
 * the obvious field fails only when somebody presses Disconnect, the worst time to find out.
 */
async function deleteConnection(
  client: Arcade,
  connectionId: string | undefined,
): Promise<void> {
  if (!connectionId) {
    throw new Error("Arcade connection has no connection_id to delete.");
  }
  await vendorCall("a connection delete", () =>
    client.admin.userConnections.delete(connectionId),
  );
}

const record = (value: unknown): Record<string, unknown> | null =>
  value !== null && typeof value === "object"
    ? (value as Record<string, unknown>)
    : null;

/**
 * One listed action read into this deployment's vocabulary, or nothing when it has no name.
 *
 * `requirements.met` IS A BOOLEAN WITH TWO UNRELATED CAUSES AND IS NEVER READ HERE. It is false
 * both when the person has not consented and when a deployment-wide secret is unset — the live
 * listing shows `Github` requiring `GITHUB_SERVER_URL`, which an operator sets once for everybody
 * and which no amount of consenting moves. Sending somebody to a consent screen over that one
 * sends them somewhere that cannot help them, so the secrets are read FIRST and answer
 * `needs-operator` with the keys they name.
 *
 * `unknown` IS ITS OWN STATE RATHER THAN A PESSIMISTIC `needs-consent`, because not knowing is not
 * the same as not connected: telling somebody to authorize something they already authorized sends
 * them round twice. So anything the listing does not say clearly answers `unknown` with the reason.
 */
function grantStateOf(item: unknown): GrantState[] {
  const tool = record(item);
  const action = textOf(tool?.qualified_name);
  if (!action) return [];
  const requirements = record(tool?.requirements);

  /*
   * A SECRETS FIELD THAT IS NOT A LIST IS UNREADABLE, NOT EMPTY — the same judgement `classify`
   * makes about an empty `behavior`, one requirement description along. `secrets` absent is the
   * ordinary case and genuinely means this action needs no deployment secret; `secrets: {}`, or any
   * other non-list, is Arcade describing requirements in a shape this cannot read, and silently
   * folding it to "no secrets, none missing" lets the function go on to answer `authorized` for an
   * action that may be waiting on an unset `GITHUB_SERVER_URL`. Nobody is then told to set it: the
   * `needs-operator` state that exists to name it cannot fire, and the person is left with an
   * action the screen says they hold and the vendor refuses. `unknown` with a reason is what the
   * docblock's "anything the listing does not say clearly" already promises.
   */
  const rawSecrets = requirements?.secrets;
  if (
    rawSecrets !== undefined &&
    rawSecrets !== null &&
    !Array.isArray(rawSecrets)
  ) {
    return [
      {
        action,
        state: "unknown",
        reason:
          "Arcade listed this action's deployment secrets as something other than a list, so whether any is unset could not be read.",
      },
    ];
  }
  const missing: string[] = [];
  let secretUnreadable = false;
  for (const raw of Array.isArray(rawSecrets) ? rawSecrets : []) {
    const secret = record(raw);
    const key = textOf(secret?.key);
    if (!key) {
      secretUnreadable = true;
      continue;
    }
    if (secret?.met === false) missing.push(key);
    else if (secret?.met !== true) secretUnreadable = true;
  }
  if (missing.length > 0) return [{ action, state: "needs-operator", missing }];
  if (secretUnreadable) {
    return [
      {
        action,
        state: "unknown",
        reason:
          "Arcade listed a deployment secret for this action without saying whether it is set.",
      },
    ];
  }

  // NO AUTHORIZATION BLOCK IS THE VENDOR SAYING THIS ACTION NEEDS NONE, with every secret it does
  // need already read as set above — so it is usable, and `authorized` with no scopes is the state
  // that says so. See {@link authorizationRequirementOf} for why this is the one reading.
  // `not-required`, NEVER `held`: nobody approved it and no approval reaches it, so the consent
  // copy must not count it among what an approval approves. See {@link GrantState}.
  const read = authorizationRequirementOf(item);
  if (read.kind === "none") {
    return [
      {
        action,
        state: "authorized",
        scopes: [],
        authorization: "not-required",
      },
    ];
  }
  if (read.kind === "unreadable") {
    return [
      {
        action,
        state: "unknown",
        reason:
          read.field === "requirements"
            ? `Arcade listed this action's requirements as ${read.shape}, so what this account holds could not be read.`
            : `Arcade listed this action's authorization as ${read.shape}, so what this account holds could not be read.`,
      },
    ];
  }
  // THE SCOPES BY THE ONE READING, see {@link requiredScopesOf}: an unreadable `oauth2` or
  // `scopes` is `unknown`, never `[]` — `authorized []` is "the connection is the whole grant",
  // which is an answer about this account the listing did not give.
  const scopesRead = requiredScopesOf(item);
  if (scopesRead.kind === "unreadable") {
    return [
      {
        action,
        state: "unknown",
        reason: `Arcade listed the permissions this action needs as ${scopesRead.shape}, so what this account holds could not be read.`,
      },
    ];
  }
  const { scopes } = scopesRead;
  /*
   * `token_status` IS THE WHOLE OF WHAT THIS ACCOUNT HOLDS, AND `status` IS NOT READ HERE AT ALL.
   * The two sit side by side and answer different questions: `status` (`active`/`inactive`, with a
   * `status_reason` such as "Provider not found" in `fixtures/arcade-catalogue.json`) is the AUTH
   * PROVIDER's standing at this deployment, and is the same for everybody; `token_status` is this
   * account's token. Reading `status: "active"` as a grant when `token_status` was missing marked
   * EVERY action of a configured provider as held by everyone the listing was asked about (A7c), and
   * reading `inactive` as "go and consent" sends somebody to a consent screen for a provider that
   * is not there. So an absent or unreadable `token_status` is `unknown`, with the reason, and the
   * text is FOLDED AND TRIMMED by {@link vendorStatusOf} as every other vendor status is.
   */
  const tokenStatus = vendorStatusOf(read.authorization.token_status);
  if (tokenStatus.kind !== "text") {
    return [
      {
        action,
        state: "unknown",
        reason:
          tokenStatus.kind === "absent"
            ? "Arcade's listing did not say whether this account holds a token for this action."
            : `Arcade's listing gave this account's token status for this action as ${tokenStatus.shape}, so whether it is held could not be read.`,
      },
    ];
  }
  if (tokenStatus.text === "completed") {
    return [{ action, state: "authorized", scopes, authorization: "held" }];
  }
  if (TOKEN_AWAITS_CONSENT_STATUSES.has(tokenStatus.text)) {
    return [{ action, state: "needs-consent", scopes }];
  }
  return [
    {
      action,
      state: "unknown",
      reason:
        "Arcade's listing gave this account's token status for this action in a spelling this deployment does not read.",
    },
  ];
}

/**
 * What one account holds at one app, action by action.
 *
 * THIS IS THE ONE PLACE A `user_id` IS SENT ON A LISTING. The transport's `listTools` sends none
 * and reads no per-person state off the answer, because a catalogue is the same for everybody and a
 * per-person listing would make it one person's. Here the question IS about a person, so the
 * account's vendor id goes out with it.
 *
 * PAGED TO THE END, as `listApps` is and for its reason: this answers ONE `GrantState` PER ACTION,
 * so a single first page would quietly drop every action past it — `GithubApi` publishes hundreds —
 * and the grants screen would show a partial holding as the whole of one. A short page ends it and
 * an unverifiable listing throws; see {@link pagedItems}.
 */
async function grantsFor(
  client: Arcade,
  vendorUserId: string,
  toolkit: string,
): Promise<GrantState[]> {
  const grants: GrantState[] = [];
  for await (const item of pagedItems({
    pageSize: CATALOGUE_PAGE_SIZE,
    maxPages: CATALOGUE_MAX_PAGES,
    concurrency: CATALOGUE_CONCURRENCY,
    page: (offset) =>
      vendorCall(`the action listing for ${toolkit}`, () =>
        client.tools.list({
          toolkit,
          user_id: vendorUserId,
          limit: CATALOGUE_PAGE_SIZE,
          offset,
        }),
      ),
    malformed: `Arcade did not answer with an action list for ${toolkit}, so what this account holds there could not be read.`,
    unending: `Arcade's action list for ${toolkit} never ended after ${CATALOGUE_MAX_PAGES} pages, so it is not trusted.`,
    incomplete: (seen, total) =>
      `Arcade listed ${seen} of ${total} actions for ${toolkit}, so what this account holds there could not be read in full.`,
    unreadableTotal: (shown) =>
      `Arcade reported the action list for ${toolkit} with a total_count of ${shown}, which is not a count, so whether what this account holds there was listed in full could not be checked.`,
  })) {
    grants.push(...grantStateOf(item));
  }
  return grants;
}

/**
 * The auth provider a toolkit's connections are held under, read off the LISTING ITSELF.
 *
 * READ, NEVER DERIVED FROM THE TOOLKIT NAME. `requirements.authorization.provider_id` is the field
 * the fixture already carries beside the auth-config `id`, and it names an auth-provider
 * configuration rather than a toolkit — one Google provider serves `Gmail` and `GoogleCalendar`
 * both. Reading it is correct under BOTH readings of the field: if it did turn out to equal the
 * toolkit slug, the listing would simply say so. Comparing it to the toolkit name is correct under
 * only one, and would be invisible against every fixture in this tree, where `Github`, `Asana` and
 * `Attio` all happen to be named after themselves. There is NO FALLBACK to the toolkit name.
 *
 * PAGED TO ITS END THROUGH {@link pagedItems}, LIKE EVERY OTHER LISTING IN THIS FILE. An earlier
 * revision read ONE unpaged request here and argued the saving was free: every tool in a toolkit
 * shares its auth provider, so a further page could only repeat what the first already said. THAT
 * ARGUMENT IS DISPROVEN, measured against a real HTTP engine — a 150-action `Gmail` listing whose
 * first 100 actions sit under `google` and whose last 50 under `microsoft` answered `google`, off
 * the single request `/v1/tools?toolkit=Gmail`. The guard below could not fire, because it was
 * reading a PREFIX and a prefix agrees with itself. "Every tool shares its provider" is a statement
 * about what a toolkit ought to be, not about what the vendor sends, and this function's whole job
 * is to read what the vendor sends. The request also carried NO `limit`, so the window it judged
 * from was the vendor's default rather than {@link CATALOGUE_PAGE_SIZE} — a number this deployment
 * never chose and the vendor may change.
 *
 * The cost is one extra request only on a toolkit larger than a page, and it buys the same property
 * `grantsFor` and `connectionsFor` are paged for: a first page can never present as the whole of
 * one. A TRUNCATED LISTING NOW THROWS here too, rather than resolving a provider off whatever
 * arrived — the `incomplete` sentence below — which is right for the reason `connectionsFor`'s
 * comment gives: these three callers spend deletes.
 *
 * AND IT GUARDS RATHER THAN ASSUMES. The DISTINCT non-null provider ids across the WHOLE listing
 * are collected and anything other than exactly one answers `null`, so a toolkit that disagrees
 * with itself is UNANSWERED rather than silently resolved to whichever action came first. Case is
 * carried through untouched, so two spellings of one provider count as two and are likewise
 * unanswered; whether they are the same provider is the caller's comparison, and
 * `connectionSiblings` folds case for the one caller that makes it. A listing carrying ANY action
 * whose authorization could not be read is unanswered too, however many ids sit beside it — see
 * {@link authProvidersNamedBy}.
 *
 * `null` IS WHAT UNANSWERED MEANS, AND IT IS NOT AN ANSWER ANY CALLER MAY SPEND. It is not "no
 * provider", and a toolkit with no provider id anywhere lands on it for the same reason an
 * ambiguous one does. What a caller must do with it depends on what its own answer costs:
 *
 * - {@link connectionsFor} — the connection lifecycle, where the answer spends DELETEs and decides
 *   whether somebody is shown as connected — REFUSES, and reads {@link authProvidersNamedBy}
 *   directly so its sentence can say whether the listing named none or several. Answering no rows
 *   there was the live defect: `revoke` said `false` ("nothing to withdraw") with no delete spent
 *   while the caller deleted the local row anyway, and `isConnected`/`accountName` sent somebody
 *   who is already connected round a second authorization. Its comment has that in full.
 * - The SEAM member below hands `null` on unchanged, for `store.ts`'s sibling resolver, which
 *   counts an unresolved app as `unanswered` and ends nothing for it. That question spends
 *   nothing, so fail-closed is a real answer there and the seam's `Promise<string | null>` stands.
 *
 * `requirements.met` IS NOT READ HERE EITHER, for `grantStateOf`'s reason: this reads a DIFFERENT
 * field of the same `requirements.authorization` object.
 */
async function authProviderOf(
  client: Arcade,
  toolkit: string,
): Promise<string | null> {
  const { named, unreadable } = await authProvidersNamedBy(client, toolkit);
  // An unreadable block is UNANSWERED, for the reason several ids are: the one id beside it is not
  // the whole of what the listing says.
  if (unreadable) return null;
  return named.size === 1 ? [...named][0] : null;
}

/**
 * What a toolkit's listing says about its auth provider: the DISTINCT ids it names, and the first
 * action whose authorization this deployment could not read, if any.
 *
 * `unreadable` IS A THIRD ANSWER, NOT AN EMPTY CONTRIBUTION. An action whose `requirements` or
 * `requirements.authorization` arrives as a shape this deployment cannot read — or whose
 * `provider_id` is present and is not a name — might name ANY provider, so the set beside it is
 * not the whole of what the listing says. {@link authorizationRequirementOf} draws the same line for
 * the catalogue and the grants screen; this is that line applied to `provider_id`.
 */
type AuthProvidersNamed = {
  named: Set<string>;
  unreadable: {
    action: string | undefined;
    field: "requirements" | "authorization" | "provider_id";
    shape: string;
  } | null;
};

/**
 * Why a toolkit's provider could not be read off one unreadable action, for a refusal to say.
 * Names the FIELD and the SHAPE that arrived there, never the value, for {@link shapeOf}'s reason.
 */
function unreadableProviderSentence(
  toolkit: string,
  unreadable: NonNullable<AuthProvidersNamed["unreadable"]>,
): string {
  const where = unreadable.action
    ? `${toolkit}'s action ${unreadable.action}`
    : `one of ${toolkit}'s actions`;
  const field =
    unreadable.field === "provider_id"
      ? "auth provider id"
      : unreadable.field === "authorization"
        ? "authorization requirement"
        : "requirements";
  return `Arcade sent ${unreadable.shape} where ${where} carries its ${field}, so which auth provider ${toolkit}'s connections are held under could not be read — that action may name a provider the rest of the listing does not. Nothing was read as connected and nothing was withdrawn — a connection may still be live at the vendor. That is a change in what Arcade answers rather than a setting an operator can correct, so upgrading this deployment's @arcadeai/arcadejs is what fixes it.`;
}

/**
 * The DISTINCT auth provider ids a toolkit's listing names, read to the listing's end — and the
 * first action whose authorization could not be read.
 *
 * SEPARATED FROM {@link authProviderOf} SO THAT THE VERDICT AND THE EVIDENCE ARE TWO THINGS. The
 * seam's `authProviderOf` answers a provider or `null`, and `null` is a verdict with the evidence
 * thrown away — zero ids, nine ids and an unreadable block arrive at its caller as the same word.
 * {@link connectionsFor} REFUSES on any of them, and a refusal has to say which one happened and
 * name what it read, so it reads the evidence and `authProviderOf` folds it to its verdict. There is
 * still ONE reading of the wire.
 *
 * AN UNREADABLE BLOCK IS NO LONGER SKIPPED. It once contributed nothing and raised nothing, so a
 * `Gmail` listing of one `google` action beside one whose authorization arrived as a string
 * resolved to `google` — a single provider asserted off a listing this deployment did not read
 * whole, which is the fail-open direction for callers that spend DELETEs on the answer. ABSENCE is
 * still not unreadability: an action with no authorization block, or a block with no `provider_id`
 * (the live `Airtable` shape in `fixtures/arcade-catalogue.json`), names no provider and is read as
 * naming none, exactly as {@link authorizationRequirementOf} reads it.
 */
async function authProvidersNamedBy(
  client: Arcade,
  toolkit: string,
): Promise<AuthProvidersNamed> {
  const named = new Set<string>();
  let unreadable: AuthProvidersNamed["unreadable"] = null;
  for await (const item of pagedItems({
    pageSize: CATALOGUE_PAGE_SIZE,
    maxPages: CATALOGUE_MAX_PAGES,
    concurrency: CATALOGUE_CONCURRENCY,
    page: (offset) =>
      vendorCall(`the action listing for ${toolkit}`, () =>
        client.tools.list({ toolkit, limit: CATALOGUE_PAGE_SIZE, offset }),
      ),
    malformed: `Arcade did not answer with an action list for ${toolkit}, so the auth provider its connections are held under could not be read.`,
    unending: `Arcade's action list for ${toolkit} never ended after ${CATALOGUE_MAX_PAGES} pages, so the auth provider its connections are held under is not trusted.`,
    incomplete: (seen, total) =>
      `Arcade listed ${seen} of ${total} actions for ${toolkit}, so the auth provider its connections are held under could not be read in full.`,
    unreadableTotal: (shown) =>
      `Arcade reported the action list for ${toolkit} with a total_count of ${shown}, which is not a count, so whether the auth provider its connections are held under could be read in full is not known.`,
  })) {
    // Read to the END even after an unreadable action, so a truncated or malformed listing still
    // throws its own sentence rather than being reported as one unreadable row.
    const read = authorizationRequirementOf(item);
    if (read.kind === "none") continue;
    const action = textOf(record(item)?.qualified_name);
    if (read.kind === "unreadable") {
      unreadable ??= { action, field: read.field, shape: read.shape };
      continue;
    }
    const providerId = read.authorization.provider_id;
    if (providerId === undefined || providerId === null) continue;
    const provider = textOf(providerId);
    if (provider) named.add(provider);
    else
      unreadable ??= {
        action,
        field: "provider_id",
        shape: shapeOf(providerId),
      };
  }
  return { named, unreadable };
}

/**
 * The Arcade client, in the shape `createComposioClient` returns. `new Arcade({ apiKey })` opens no
 * socket and sends no request, so tests replace the SDK's PROTOTYPE methods before calling this.
 *
 * EVERY CALL TO THE VENDOR GOES THROUGH {@link vendorCall}, which is where a refusal becomes this
 * deployment's own sentence and the vendor's body stops. `callTool` still reaches the body's
 * `error.name` — a raw `APIError`'s `name` is the CLASS name through the prototype chain, never the
 * body's, so without the normalization the authorize prompt would be unreachable — but it reaches
 * it through {@link ArcadeFailureError}, not through a bare object thrown as if it were an error.
 */
export function createArcadeClient(apiKey: string): {
  actions: ArcadeActions;
  broker: ConnectedAppBroker;
} {
  const client = new Arcade({ apiKey });
  const actions: ArcadeActions = {
    // `total_count` IS NORMALIZED HERE, and this is the only place it can be. The transport
    // (`./arcade`) must not import this file — that direction is a cycle — so it cannot reach
    // {@link reportedTotalOf}, and what it receives has to already tell "the vendor did not say"
    // apart from "the vendor said zero". Handing it the SDK's `OffsetPage` does not: that object's
    // `total_count` is `body.total_count || 0`, so `listTools` read a `0` off an answer that
    // carried no total and its `raw.length < total` cross-check could never fire. The FIELD IS
    // OMITTED when the vendor omitted it, which is what the declared `total_count?: number` means.
    listTools: async (q) => {
      const answer = await vendorCall(
        `the action listing for ${q.toolkit}`,
        () =>
          client.tools.list({
            toolkit: q.toolkit,
            limit: q.limit,
            offset: q.offset,
          }),
      );
      // Passed through unchecked: a malformed listing is the transport's sentence to write, and
      // its own `Array.isArray` guard is what writes it. THE ITEMS ARE READ OFF THE RAW BODY for
      // {@link sentItemsOf}'s reason — handing over the page's manufactured `[]` would leave that
      // guard as dead as the totals the comment above describes, and a listing that answered no
      // items at all would refresh an app's actions down to none.
      const items = sentItemsOf(answer) as unknown[];
      // AND A TOTAL THIS CANNOT READ REFUSES HERE TOO, rather than being dropped on the way out.
      // The declared `total_count?: number` leaves the transport exactly two readings — a number
      // to cross-check against, or "the vendor did not say" — so a value that is neither has
      // nowhere honest to go: omitting it would switch off the transport's own
      // `raw.length < total` check and commit a truncated refresh as a whole catalogue.
      const total = reportedTotalOf(
        answer,
        (shown) =>
          `Arcade reported the action listing for ${q.toolkit} with a total_count of ${shown}, which is not a count, so whether the listing is whole could not be checked. Nothing was refreshed and the actions already recorded for this app are kept.`,
      );
      return total === undefined ? { items } : { items, total_count: total };
    },
    execute: async (r) =>
      vendorCall(`running ${r.tool_name}`, () =>
        client.tools.execute({
          tool_name: r.tool_name,
          input: r.input,
          user_id: r.user_id,
        }),
      ),
  };
  const broker: ConnectedAppBroker = {
    grantIsLocal: false,
    listApps: () => listApps(client),
    // 5.3: no auth config per app. Arcade's equivalent is an auth provider registered once in the
    // dashboard for the whole project, so there is nothing to create or delete here.
    ensureAuthConfig: async () => "not-needed",
    deleteAuthConfig: async () => {},
    // The field-entry pair REFUSES. Composio's field schemes are a person typing their own API key;
    // `admin.secrets` is a deployment-wide secret an operator sets once for everybody.
    connectionFields: () =>
      Promise.reject(new BrokerRefusalError(FIELDS_REFUSAL)),
    connectWithFields: () =>
      Promise.reject(new BrokerRefusalError(FIELDS_REFUSAL)),
    accountName: async ({ account, toolkit }) => {
      // Filtered by the row's own provider, as Composio's `accountsFor(..., toolkit, ...)` is: a
      // person connected to two apps must never be shown the OTHER app's name on this app's screen.
      //
      // AND BY THE ROW'S OWN `connection_status`, through {@link connectionIsLive}: this name is
      // shown beside "Connected", so a name read off a row the vendor reports as expired or revoked
      // says the connection is live in the one place somebody looks to check.
      for (const row of await connectionsFor(
        client,
        account.vendorUserId,
        toolkit,
      )) {
        if (!connectionIsLive(row)) continue;
        const info = row.provider_user_info as
          | { name?: unknown; login?: unknown }
          | null
          | undefined;
        const name = textOf(info?.name) ?? textOf(info?.login);
        if (name) return name;
      }
      return null;
    },
    // The mint. Stays a TOP-LEVEL member: the Composio connect flow calls it from routes.ts, so it
    // cannot move behind the nullable `authorizations` sub-surface.
    authorize: async ({ account, action }) => {
      if (!action) {
        throw new BrokerRefusalError(
          "Arcade grants per action, so an authorization needs the action it is for and none was given.",
        );
      }
      // NEVER SEND `next_uri`. THIS LOOKS LIKE A BUG AND IS A MEASUREMENT. The SDK declares the
      // field (`ToolAuthorizeParams.next_uri`), but against the live API it refuses EVERY value and
      // the mint answers `500 "error starting authorization challenge: invalid next URI"`: an app
      // page, the verifier's own origin, `cloud.arcade.dev` and a localhost address alike. Do not
      // "fix" this by passing a return address.
      //
      // `returnUrl` IS ACCEPTED AND IGNORED, for the same reason: the landing page comes from the
      // attempt row (spec D18), not from a parameter this vendor will take.
      //
      // THE REFUSAL IS MEDIATED, AND ON THIS CALL THAT IS NOT A STYLE POINT: the body an
      // authorization answers with is the one that carries a bearer `url`, and the SDK's `APIError`
      // puts the body it could not read a `message` off into its own `message`. See
      // {@link vendorCall}; the route's definite-or-uncertain decision reads `status` through
      // `normalizeArcadeError` and is unaffected.
      // THROUGH {@link requireBody}: a mint that answered an empty body, or a body of literal
      // `null`, has `answer === null` wearing `AuthorizationResponse`, and the `status` read below
      // would raise a bare `TypeError` rather than the sentence this route shows somebody.
      const answer = requireBody(
        `the authorization for ${action}`,
        await vendorCall(`the authorization for ${action}`, () =>
          client.tools.authorize({
            tool_name: action,
            user_id: account.vendorUserId,
          }),
        ),
      );
      // WHAT THE VENDOR SAID ABOUT THIS AUTHORIZATION, READ BEFORE ITS URL IS READ AS A NEXT STEP.
      // `tools.authorize` does not only answer "go to this screen": it answers `completed` for an
      // account that already holds the grant, `failed` for one the vendor could not begin — and it
      // may answer either WITH a `url` beside it, so the absent-url refusal below is not this guard
      // in disguise. Unread, both were handed back as a live consent link: somebody already
      // connected is sent round a screen they finished, and a failed authorization is dressed up
      // as a working one, with an `ar_…` recorded against the attempt that can never complete.
      //
      // AN ALLOWLIST OF THE SPELLINGS UNDER WHICH CONSENT IS GENUINELY THE NEXT STEP, for the
      // reason {@link LIVE_CONNECTION_STATUS} gives: the dead vocabulary cannot be enumerated from
      // here. The SDK's declared union is a convenience, not a promise about the wire — an engine
      // answering `revoked` or `expired` type-checks as nothing and a denylist missing that
      // spelling goes on sending a browser to it, which is the defect itself.
      //
      // SILENCE IS NOT A NO, as it is not in {@link connectionIsLive}: `status` is OPTIONAL on the
      // wire, so an ABSENT field (missing, `undefined`, `null`) leaves the url and the id as the
      // whole of the evidence and they stand. A status that is PRESENT AND UNREADABLE — `{}`,
      // `false`, a number, a blank string — is not silence: the vendor said something about this
      // authorization and this deployment cannot tell what, so the bearer url beside it is NOT
      // handed on as a live redirect. {@link vendorStatusOf} is the one reading of both, and it
      // FOLDS AND TRIMS the text for this file's standing reason: a case the vendor changes must not
      // change what somebody is told about their own account.
      //
      // A `BrokerRefusalError` AND NOT A BARE `Error`, which is the difference between being told
      // and being locked out. The mint route keys its three outcomes on what was thrown: an
      // authored refusal is DEFINITE, so the attempt is discarded and the actor may press Authorize
      // again at once, with this sentence shown; a bare `Error` normalizes to `null` and is read as
      // "the mint may be live", leaving the attempt standing for its fifteen-minute TTL. Nothing
      // IS live here — the vendor answered, and said this is not a consent to walk through.
      const read = vendorStatusOf(answer.status);
      if (read.kind === "unreadable") {
        throw new BrokerRefusalError(
          `Arcade answered this account's authorization for ${action} with ${read.shape} where its status belongs, so whether a consent screen is the next step could not be read and nobody was sent anywhere. Press Authorize again to start a fresh one.`,
        );
      }
      const status = read.kind === "text" ? read.text : undefined;
      if (status !== undefined && !MINT_AWAITS_CONSENT_STATUSES.has(status)) {
        throw new BrokerRefusalError(
          status === "completed"
            ? `Arcade answered that this account's authorization for ${action} is already completed, so nobody was sent to a consent screen. Reload this page: the grant it is reporting is already in place.`
            : `Arcade answered that this account's authorization for ${action} is "${status}" rather than one waiting for consent, so nobody was sent anywhere and nothing was connected. Press Authorize again to start a fresh one.`,
        );
      }
      // The url is a bearer capability: it goes back to the caller and nowhere else.
      const url = answer.url;
      if (typeof url !== "string" || url === "") {
        throw new Error(
          "Arcade answered an authorization with no url to visit.",
        );
      }
      // The mint's own `ar_…` id: spec D24 binds it to the callback's `auth_id`. A mint that
      // answered none is not a success, and the refusal is here so that a null can never be
      // minted from an Arcade answer — `authorizationId` is non-null for every Arcade mint.
      const authorizationId = answer.id;
      if (typeof authorizationId !== "string" || authorizationId === "") {
        throw new Error("Arcade answered an authorization with no id.");
      }
      return { redirectUrl: url, authorizationId };
    },
    // 6.2: the connection-lifecycle trio.
    // A LIVE ROW AND NOT MERELY A ROW. The seam's word is "currently attached to this app at the
    // vendor", and a row Arcade reports as expired, revoked, pending or failed is not that; see
    // {@link connectionIsLive}, which also says why a row with NO status still counts.
    isConnected: async ({ account, toolkit }) =>
      (await connectionsFor(client, account.vendorUserId, toolkit)).some(
        connectionIsLive,
      ),
    // Answers what was REQUESTED: true when something was found and every delete was accepted,
    // false when there was nothing. Every delete is attempted, then ANY failure throws: a partial
    // ask must not read as `false` ("nothing there") nor as a clean `true`.
    //
    // AND `false` IS ONLY EVER SAID OFF A LISTING READ WHOLE, which is {@link connectionsFor}'s
    // promise rather than this one's: an unreadable, truncated or UNATTRIBUTABLE listing throws out
    // of it before this line, so `rows.length === 0` here means the vendor said so. `false` with no
    // delete spent is the live defect's exact signature — the caller deletes the local row on it —
    // and `arcade-revoke-invariant.test.ts` asserts the outcome rather than any one mechanism.
    //
    // ON EVERY ROW, LIVE OR NOT, WHICH IS WHY THIS DOES NOT ASK {@link connectionIsLive}. A dead row
    // is still a row at the vendor: skipping it would leave it standing while this answered `false`
    // ("there was nothing to withdraw"), and a reconnect would then be made beside debris nobody can
    // see. Deleting a connection the vendor already considers finished costs one call and is the
    // only reading under which Disconnect means what it says.
    revoke: async ({ account, toolkit }) => {
      const rows = await connectionsFor(client, account.vendorUserId, toolkit);
      if (rows.length === 0) return false;
      const outcomes = await Promise.allSettled(
        rows.map((row) => deleteConnection(client, row.connection_id)),
      );
      const failed = outcomes.filter((o) => o.status === "rejected");
      if (failed.length > 0) {
        throw new Error(
          `Arcade revoke failed for ${failed.length} of ${rows.length} connections.`,
          { cause: (failed[0] as PromiseRejectedResult).reason },
        );
      }
      return true;
    },
    revokeAccount: (accountId) => deleteConnection(client, accountId),
    // 6.3: the read-only status pair. Both are DECLARED here because the seam requires them —
    // `grantsFor` is a member every broker answers, and `authorizations` is the sub-surface Arcade
    // alone runs, so a null here would say Arcade mints nothing to poll, which is false. The
    // bodies are 6.3's. `status` must narrow to `{ status, userId, scopes }` and nothing else: the
    // raw `auth.status` response carries `context.token`, a live provider access token, plus the
    // person's full profile.
    grantsFor: ({ account, toolkit }) =>
      grantsFor(client, account.vendorUserId, toolkit),
    // Read off the listing's own `requirements.authorization.provider_id`, never derived from the
    // toolkit name and never falling back to it. See `authProviderOf` above.
    authProviderOf: (toolkit) => authProviderOf(client, toolkit),
    authorizations: {
      /**
       * Where one minted authorization has got to — THREE FIELDS READ OUT AND THE RESPONSE OBJECT
       * DROPPED HERE, inside the adapter, so nothing outside this file ever holds it.
       *
       * THIS DELIBERATELY INVERTS THIS CODEBASE'S CARRY-THE-VENDOR-ERROR-AS-`cause` CONVENTION.
       * That convention is right everywhere else: a vendor's own words are what a maintainer needs
       * when a call fails. It is wrong here, because `auth.status` answers with `context.token` — a
       * LIVE, WORKING provider access token for the person who just consented — and their full
       * `user_info` profile beside it, while `url` is a bearer capability of its own. A status
       * response LOOKS LIKE METADATA, which is exactly how the throwaway harness that proved this
       * flow came to write the token to a file on its first run.
       *
       * So the protection is the RETURN TYPE and not a comment asking the next person to remember:
       * what is not returned cannot be logged, attached as a `cause`, or written into an audit
       * payload by code that never sees it. Do not widen this, and do not add `url`.
       */
      status: async (id, options) => {
        // THE REFUSAL IS MEDIATED TOO, for the same reason the RESPONSE is: a status this vendor
        // would not answer is answered ABOUT a flow whose body carries the token and the url.
        //
        // AND THE CALLER'S DEADLINE REACHES THE WIRE: an abandoned poll closes its socket rather
        // than leaving this deployment holding one open against a vendor nobody is waiting on.
        //
        // AND THROUGH {@link requireBody}, for `authorize`'s reason: an empty body arrives here
        // as `null` wearing the declared response type, and the three field reads below would
        // raise a bare `TypeError` instead of saying what happened.
        const answer = requireBody(
          "an authorization status read",
          await vendorCall("an authorization status read", () =>
            client.auth.status({ id }, { signal: options?.signal }),
          ),
        );
        const scopes = answer.scopes;
        // THE ONE STATUS READING ({@link vendorStatusOf}): folded and trimmed, and an absent or
        // unreadable status is `"unknown"`, which the return leg refuses as not finished.
        const settled = vendorStatusOf(answer.status);
        return {
          status: settled.kind === "text" ? settled.text : "unknown",
          userId: textOf(answer.user_id) ?? null,
          scopes: Array.isArray(scopes)
            ? scopes.filter((s): s is string => typeof s === "string")
            : [],
        };
      },
      // `handle` is opaque to the seam; `flow_id` is Arcade's word for it and stops in this file.
      // A `user_mismatch` answer is an ANSWER, so it surfaces as `{ mismatch: true }`; any other
      // failure is an outage or a bug and is rethrown as the sentence {@link vendorCall} wrote for
      // it — `user_mismatch` is still read, because the body's `error.name` survives the mediation
      // and `normalizeArcadeError` answers off the carried failure.
      confirmReturn: async ({ handle, vendorUserId }, options) => {
        let answer: { auth_id?: unknown };
        try {
          // THROUGH {@link requireBody}, for `authorize`'s reason. The refusal it writes is
          // raised INSIDE the try, which is deliberate and harmless: `normalizeArcadeError`
          // answers `null` for it, so it is not read as `user_mismatch` and is rethrown as
          // itself by the `throw error` below — an unreadable body is an outage, which is the
          // same judgement the `auth_id` check further down already states.
          answer = requireBody(
            "the return-leg confirmation",
            await vendorCall("the return-leg confirmation", () =>
              client.auth.confirmUser(
                {
                  flow_id: handle,
                  user_id: vendorUserId,
                },
                { signal: options?.signal },
              ),
            ),
          );
        } catch (error) {
          if (normalizeArcadeError(error)?.name === "user_mismatch") {
            return { mismatch: true };
          }
          throw error;
        }
        // THE WHOLE SUBJECT OF THE BINDING, CHECKED HERE AS THE MINT CHECKS ITS OWN — see
        // `authorize` above. `ConfirmUserResponse.auth_id` is DECLARED required by the SDK's types
        // and is VALIDATED by nothing in it, so an answer that omits the field arrives as
        // `undefined` wearing the type `string`, and `{ authorizationId: undefined }` would be a
        // confirmation made against nothing that the seam's own type says is an id.
        //
        // AND IT THROWS RATHER THAN ANSWERING `{ mismatch: true }`, which is the contract routes.ts
        // states at its binding: where the vendor's real shape differs from what was assumed, this
        // does NOT answer a clean refusal — the return leg surfaces an outage, which is honest,
        // because an id that could not be read is not evidence that the handle belongs to somebody
        // else. A refusal reading "not your authorization" would blame the person for an answer
        // their vendor failed to make.
        const authorizationId = answer.auth_id;
        if (typeof authorizationId !== "string" || authorizationId === "") {
          throw new Error(
            "Arcade confirmed a return with no authorization id.",
          );
        }
        return { authorizationId };
      },
    },
  };
  return { actions, broker };
}