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.

43.7 KB
Raw Blame
import type { BrokerApp, FieldScheme } from "../broker";
import type { ComposioResult } from "../composio";
import type {
  AccountRow,
  CheckedAuthConfig,
  VendorAccountStatus,
  VendorAuthConfig,
  VendorTool,
  VendorToolkitDetail,
} from "../composio-vendor";

/**
 * The Composio client's shapes and constants: the vendor seam it is built over, and the names and
 * limits its methods share. Split out of `../composio-adapter.ts`, which re-exports what it always
 * exported. No `@composio/core` here; the adapter is still the one file that imports it.
 */

/**
 * The one file in `server/src` that imports `@composio/core`, and what it owes the rest of them.
 *
 * `./composio` describes calling an action and `./broker` describes everything that has to be true
 * before one can be called; both are written as narrow projections that name no vendor type, so
 * that the SDK's shape — its constructor, its retries, its zod schemas and whatever the next
 * version renames — is confined here. This module is the adapter that satisfies both from one
 * client. A second importer of `@composio/core` under `server/src` would undo that, because the
 * point of a single import site is that a version bump has exactly one file to be read against.
 *
 * NO SESSION IS EVER CREATED, AND THAT IS A SECURITY BOUNDARY RATHER THAN A PREFERENCE. The SDK's
 * `composio.create(...)` and `sessions.create(...)` open a Composio tool-router session, and a
 * session brings Composio's own hosted surface with it — a remote shell and a Python sandbox that
 * this deployment neither asked for, cannot see into, and could not audit if a model reached them.
 * Everything below is a plain per-call request carrying a user id. A `create` of a session
 * anywhere in this file is a defect, not an optimisation, and it will not look like one: the
 * session API is the shortest path to most of what this file does the long way.
 *
 * EVERY LISTING PASSES AN EXPLICIT LIMIT AND EVERY LISTING IS READ TO THE END OF ITS CURSOR.
 * Composio's default page is 20, which is smaller than the number of actions Gmail alone publishes,
 * and through the SDK's tool wrapper the default did a second thing as well: `getRawComposioTools`
 * set `important=true` whenever a toolkit query arrived with no limit, no tags and no search
 * (`@composio/core` 0.18.1, `src/models/Tools.ts:505-515`), so an omitted limit silently narrowed
 * the answer to the vendor's own "important" subset and nothing in the result said a filter had
 * been applied. {@link LISTING_LIMIT} is the documented page ceiling and therefore the fewest round
 * trips a listing can be read in.
 *
 * AND THE LIMIT IS A PAGE RATHER THAN THE ANSWER, WHICH IS WHAT CHANGED. Two of the four listings
 * here used to meet a full page and refuse it, because the SDK wrapper around them could not ask
 * for a second — one takes no cursor, the other drops the response's. That was never true of the
 * vendor: both raw endpoints carry `cursor` and `next_cursor`, and Composio publishes more than
 * {@link LISTING_LIMIT} toolkits, so the catalogue refusal fired on every call and the app picker
 * showed an operator nothing at all. All four now go through {@link everyRowOf}, which follows the
 * cursor until the vendor stops offering one and refuses rather than truncates when it cannot.
 *
 * THE API KEY NEVER LEAVES THIS FILE. It arrives as {@link createComposioClient}'s only argument,
 * goes straight into the vendor's constructor, and is held from there on by the vendor's client
 * inside a closure. Nothing below logs it, no thrown message quotes it, and neither of the two
 * returned objects carries a field that could be read back to it — they expose eight methods and
 * no state. A key in a log line is a key in a log aggregator, and a key in an error message is a
 * key in an audit row and in a model's context.
 */

/**
 * What this adapter needs of `@composio/core`'s client, written as a shape rather than as a class.
 *
 * A TEST SATISFIES IT WITH AN OBJECT LITERAL, which is the entire argument for it and the reason
 * {@link buildComposioClient} takes one of these instead of an API key. The vendor's own client
 * cannot be constructed without a key and answers nothing without a network, so an adapter that
 * built its own client would be an adapter no test could reach — and this is the file where the
 * field names, the argument order and the refusal below would go wrong unnoticed.
 *
 * Every member is written with METHOD syntax deliberately. Method parameters are compared
 * bivariantly, so a real `Composio` — whose signatures carry optional request-options arguments
 * and wider parameter types than the calls here use — satisfies this without a cast.
 *
 * THE TWO DELETES ARE NOT `Composio`'s, AND THAT IS THE ONE PLACE THIS SHAPE DIVERGES FROM IT. Both
 * of the vendor's own wrappers hard-code the request body they send — `this.client.authConfigs
 * .delete(nanoid, undefined, requestOptions)` and the same line for connected accounts
 * (`@composio/core` 0.18.1, `src/models/AuthConfigs.ts:303-311` and
 * `src/models/ConnectedAccounts.ts:532-540`) — so through them the `revoke_on_delete` parameter
 * cannot be passed at all, and both calls soft-delete while the grant at Google or Slack stands. So
 * the shape below asks for the underlying client's signature instead, and
 * {@link createComposioClient} satisfies it from `composio.getClient()`. See
 * {@link ComposioBroker.revoke} for what that flag is and what its absence made this deployment
 * claim.
 */
export type ComposioVendor = {
  tools: {
    /**
     * Every action of one app, one page at a time, THROUGH THE RAW CLIENT RATHER THAN THE WRAPPER.
     *
     * `getRawComposioTools` was here and could not be paged. `ToolListParamsSchema` names no cursor
     * field at all (`@composio/core` 0.18.1, `src/types/tool.types.ts:257-266`) and the method ends
     * `tools.items.map(...)` (`src/models/Tools.ts:561`), dropping the response's `next_cursor`
     * before any caller sees it — so through the wrapper a page at {@link LISTING_LIMIT} and a
     * listing longer than one were the same array, and `./composio` refused rather than commit a
     * fragment as the whole truth about an app. The raw client is the difference: `ToolListParams`
     * carries `cursor`, "a base64 encoded string of the page and limit", and `ToolListResponse`
     * carries `next_cursor` (`@composio/client` 0.1.0-alpha.76, `resources/tools.d.ts:421-432` and
     * `:200-204`). The request IS expressible, and {@link everyRowOf} makes it.
     *
     * WHAT THE WRAPPER WAS DOING THAT THIS HAS TO KEEP DOING IS TWO PARAMETERS AND ONE NO-OP.
     * `toolkit_versions` is the SDK's own `toolkitVersions` config, which defaults to "latest"
     * (`src/utils/config-defaults/ConfigDefaults.node.ts`) and was forwarded on every listing it
     * made (`src/models/Tools.ts:548`); it decides which `version` each action comes back with,
     * which is the value a later call sends back to Composio, so it is passed here as the literal
     * the default is. `important` is the one this file already knew about and is now simply not
     * named: the wrapper set it to "true" whenever a toolkit query carried no limit (`:505-515`),
     * which NARROWS the answer to a featured subset that nothing in the answer declares. And the
     * no-op is `applyDefaultSchemaModifiers`, which returns its argument untouched unless
     * `dangerouslyAllowAutoUploadDownloadFiles` is on (`:242-248`); it defaults off
     * (`ConfigDefaults.node.ts`) and {@link createComposioClient} does not turn it on — which is
     * the premise `./composio`'s file-upload guard is written on.
     *
     * AND `ToolSchema.parse` IS GONE WITH IT, WHICH IS A GAIN AND A COST, BOTH WRITTEN DOWN
     * ELSEWHERE. The gain is that the parse STRIPPED every schema key its `ParametersSchema` did
     * not name before any caller could see it — see {@link ComposioAction.inputParameters}, where
     * that loss was recorded as unavoidable and where the fix was named as this exact call. The
     * cost is that nothing validates the row: {@link actionOf} carries every check now, including
     * the container, and {@link pageOf} carries the envelope.
     */
    list(query: {
      toolkit_slug: string;
      limit: number;
      toolkit_versions: "latest";
      /** Where the last page left off, ABSENT on the first request rather than undefined. */
      cursor?: string;
    }): Promise<{
      /**
       * `unknown` BECAUSE NOTHING HAS LOOKED AT IT, which is the difference between this listing
       * and the two the SDK still serves. Their transformers open `response.items.map(...)`, so a
       * malformed envelope dies inside the vendor's package; a generated client parses the body and
       * returns it. {@link pageOf} is where that is answered.
       */
      items?: unknown;
      /** The vendor's own word for "there is another page", read by {@link everyRowOf}. */
      next_cursor?: unknown;
    } | null>;
    getRawComposioToolBySlug(
      slug: string,
      options?: { version?: string },
    ): Promise<VendorTool>;
    execute(
      slug: string,
      body: {
        arguments: Record<string, unknown>;
        userId: string;
        version: string;
        /**
         * WHICH ACCOUNT OF THE PERSON'S TO RUN IN, absent where any of theirs will do.
         *
         * `ToolExecuteParams` carries it and `Tools.execute` forwards it to the client
         * (`@composio/core` 0.18.1), so this is the wire's own field rather than one this
         * deployment composes. Why a verification cannot go without it is written at
         * {@link ComposioActions.execute}: a person and an app do not name an account, and one
         * person may hold several for one app.
         */
        connectedAccountId?: string;
      },
    ): Promise<ComposioResult>;
  };
  toolkits: {
    /**
     * The app catalogue, one page at a time, THROUGH THE RAW CLIENT FOR THE SAME REASON.
     *
     * AND THIS IS THE ONE THAT WAS BROKEN IN FRONT OF PEOPLE. `Toolkits.getToolkits` does forward a
     * `cursor` (`@composio/core` 0.18.1, `src/models/Toolkits.ts:68`) — so the wrapper could ASK
     * for a second page — but `transformToolkitListResponse` returns `response.items.map(...)`, a
     * bare array (`src/utils/transformers/toolkits.ts:16-43`), so there is no cursor to put in it.
     * One half of a pager is not a pager, and `fetchDirectory` refused a full page because it could
     * not tell a complete catalogue from a truncated one. Composio publishes more than
     * {@link LISTING_LIMIT} toolkits, so that refusal fired on the FIRST call, every time, and an
     * operator opening the app picker saw no apps at all. `ToolkitListResponse` carries
     * `next_cursor` and `ToolkitListParams` carries `cursor` (`@composio/client` 0.1.0-alpha.76,
     * `resources/toolkits.d.ts:322-326`, `:467-478`), so the whole request was expressible the
     * entire time.
     *
     * `sort_by` IS THE WIRE'S SPELLING OF WHAT WAS `sortBy`, and it still matters even though the
     * listing is no longer finite. What it buys now is order rather than coverage: the rows reach a
     * picker in the order Composio thinks people want them, and the page ceiling in
     * {@link PAGE_CEILING} is the one case left where being cut off is possible at all.
     *
     * NO SEARCH TERM, WHICH IS THE SAME DECISION FOR A DIFFERENT REASON THAN BEFORE. It used to be
     * that the SDK's params named no search field and the parse stripped what it did not name, so a
     * term passed here would vanish before the request. `ToolkitListParams` DOES name `search`
     * (`:480-484`), so that is no longer the argument. The argument is that the catalogue is held
     * for ten minutes and searched in this process by both of its callers — the picker and the
     * enable route's slug check — and a per-term request would be a per-term cache. Searching over
     * the held rows is this deployment's own job and stays so.
     */
    list(query: {
      limit: number;
      sort_by: "usage";
      /** Where the last page left off, ABSENT on the first request rather than undefined. */
      cursor?: string;
    }): Promise<{
      /** `unknown` for the reason the action listing's is — see {@link pageOf}. */
      items?: unknown;
      /** The vendor's own word for "there is another page", read by {@link everyRowOf}. */
      next_cursor?: unknown;
    } | null>;
    /**
     * ONE app, read for the one thing the catalogue listing does not carry: what it asks a person.
     *
     * The listing above answers which apps exist and which scheme each of them authenticates with;
     * it does not answer which boxes a form for that scheme needs. That is published per app and it
     * moves — one app wants a key, the next wants a key and a workspace subdomain — so it is asked
     * for at the moment a person presses Connect rather than derived from anything held here. See
     * {@link ComposioBroker.connectionFields}.
     *
     * NO PAGE AND NO CURSOR, because a toolkit is one object rather than a listing: this is the one
     * vendor read in this file where there is no second page to be mistaken for the whole answer.
     */
    retrieve(slug: string): Promise<VendorToolkitDetail>;
  };
  authConfigs: {
    list(query: {
      toolkit: string;
      limit: number;
      /**
       * Ask for the disabled ones too, ALWAYS, which is why this is the literal and not a boolean.
       *
       * The vendor's listing returns enabled configs unless asked otherwise
       * (`AuthConfigListParamsSchema.showDisabled`, `@composio/core` 0.18.1,
       * `src/types/authConfigs.types.ts:124-131`), and a config this listing cannot see is a config
       * {@link ComposioBroker.ensureAuthConfig} creates a second of — which is the exact split that
       * method exists to prevent, arriving through the one door it was not watching. Every question
       * this file asks of the listing is better served by seeing a disabled config and saying so:
       * creation must not duplicate it, deletion must remove it, and consent must refuse against
       * it rather than mint a link that cannot work.
       */
      showDisabled: true;
      /**
       * Where the last page left off, ABSENT on the first request rather than undefined.
       *
       * `AuthConfigListParamsSchema` names it and `AuthConfigs.list` forwards it
       * (`@composio/core` 0.18.1, `src/types/authConfigs.types.ts:124-131`,
       * `src/models/AuthConfigs.ts:95`), which is the fact that decides how a truncated answer is
       * handled here: the catalogue refuses a full page because it has no way to ask for the next
       * one, and this listing does. See {@link everyRowOf}.
       */
      cursor?: string;
    }): Promise<{
      items: VendorAuthConfig[];
      /**
       * The vendor's own word for "there is another page", which was being discarded at this type.
       *
       * `unknown` RATHER THAN `string | null`, because the transformer writes `response.next_cursor
       * ?? null` (`src/utils/transformers/authConfigs.ts:80`) and that is the wire's value with no
       * check on it — a numeric cursor reaches {@link everyRowOf} exactly as Composio sent it, which
       * is the one shape that could be read as the end of a listing that has not ended.
       *
       * `AuthConfigListResponseSchema` carries it (`@composio/core` 0.18.1,
       * `src/types/authConfigs.types.ts:129-133`) and
       * `transformAuthConfigListResponse` fills it in from `next_cursor` on every answer
       * (`src/utils/transformers/authConfigs.ts:72-80`). Omitting it here did not make the
       * truncation go away; it made it unobservable, because a field a projection does not name is
       * a field no caller and no test of a caller can ask about. {@link everyRowOf} reads it, and
       * follows it until the vendor stops offering one — so a listing at {@link LISTING_LIMIT} is
       * no longer a fragment this file can mistake for the whole answer.
       */
      nextCursor?: unknown;
    }>;
    /**
     * Create one auth config, and hand back the id Composio gave it.
     *
     * `Promise<unknown>` UNTIL NOW, AND THE ANSWER WAS NEVER LOOKED AT. That was read as harmless
     * because nothing here needs the id — the next listing finds the config by its name. It is not:
     * `transformCreateAuthConfigResponse` builds what this resolves to by dereferencing
     * `response.auth_config.id` and `response.toolkit.slug` (`@composio/core` 0.18.1,
     * `src/utils/transformers/authConfigs.ts:96-106`), so a drift in the answer's SHAPE raises a
     * `TypeError` inside the vendor's package — after the create has gone out and been answered.
     * {@link ComposioBroker.ensureAuthConfig} then reported that no config had been created, over a
     * config standing at Composio that nothing in this deployment names. Reading the reply is what
     * makes the difference between "nothing was created" and "something may have been" a fact
     * rather than an assumption.
     *
     * `id?: unknown` FOR THE REASON EVERY OTHER FIELD IN THIS PROJECTION IS ONE: the `transform()`
     * around it is the warn-only kind (`src/utils/transform.ts:26-36`), so
     * `CreateAuthConfigResponseSchema` spelling the id a required string is the answer Composio
     * MEANS to send rather than a fact about the one that arrived.
     *
     * NULLABLE THOUGH THE VENDOR'S OWN DECLARATION IS NOT, exactly as the account delete below is:
     * the generated client parses the body and returns it, and reading a field off a `null` would
     * be a crash carrying a sentence that reads like a stack trace.
     */
    create(
      toolkit: string,
      /**
       * THE UNION, BECAUSE THE MANAGED TYPE IS RIGHT FOR ONE KIND OF APP AND WAS SENT FOR ALL OF
       * THEM. A self-registering app has no Composio-owned OAuth client behind it and a key app
       * has no consent screen to send anybody to, so both are created as custom configs — carrying
       * the scheme, and never a credential, which is per-connection rather than per-config. The
       * managed shape has no field to name a scheme with, which is why this is a union of two
       * shapes rather than one shape with an optional field.
       */
      options:
        | { type: "use_composio_managed_auth"; name: string }
        | {
            type: "use_custom_auth";
            authScheme: FieldScheme | "DCR_OAUTH";
            name: string;
            /**
             * EMPTY, AND PRESENT, WHICH IS NOT THE CONTRADICTION IT LOOKS LIKE.
             *
             * Neither config this deployment creates carries a secret — a self-registering app
             * needs none and a key app's key belongs to each connection made against the config
             * rather than to the config — but `CreateCustomAuthConfigParamsSchema` spells
             * `credentials` REQUIRED (`@composio/core` 0.18.1,
             * `src/types/authConfigs.types.ts:52-65`) and `AuthConfigs.create` `safeParse`s its
             * options before it builds a body (`src/models/AuthConfigs.ts:132-137`). So an absent
             * field is not "no credentials sent"; it is a `ValidationError` raised inside the
             * vendor's package with no request made at all. The empty record is what carries
             * nothing THROUGH that check, and the type says so rather than leaving the next reader
             * to discover it from a failed enable.
             */
            credentials: Record<string, never>;
          },
    ): Promise<{ id?: unknown } | null>;
    /**
     * Delete one auth config, and ask for the upstream credentials on it to be revoked too.
     *
     * THE SAME TRAP AS THE ACCOUNT DELETE BELOW, one level up. The endpoint "soft-deletes an
     * authentication configuration" and revokes "the upstream credentials of every connection using
     * this auth config" only when the flag is passed (`@composio/client` 0.1.0-alpha.76,
     * `resources/auth-configs.d.ts:60-72` and `:651-659`), so a delete without it leaves every
     * grant that was ever made against this config alive at the provider.
     *
     * WHICH IS WHY IT IS PASSED HERE EVEN THOUGH THE ACCOUNTS WERE ALREADY ASKED FOR INDIVIDUALLY.
     * Removing an app revokes each connected person first and drops the config last, and that loop
     * reaches exactly the people this deployment has a `composio_connections` row for. An account
     * whose row drifted — cleared by a confirm that Composio answered `false` to, or lost with a
     * database this deployment restored — is invisible to it and still live at the vendor. This is
     * the one call that reaches those, and there is nothing on this config that removing the app is
     * not meant to end.
     *
     * AND ITS REPLY CARRIES NO VERDICT, WHICH IS WHY THIS ONE IS NOT READ WHERE THE ACCOUNT DELETE
     * BELOW IS. That is the obvious question to ask of a call whose answer is awaited and dropped —
     * {@link ComposioBroker.revokeAccount} exists to argue that not throwing is not the same as
     * having been done, and the same gap one level up would have `removeServer` deleting the app's
     * row behind a config that is still standing. It was asked and the answer is in the vendor's own
     * type: `AuthConfigDeleteResponse` has exactly one field, an OPTIONAL `revoke_job_id`, and no
     * `success` (`@composio/client` 0.1.0-alpha.76, `resources/auth-configs.d.ts:377-385`). The
     * account delete's `ConnectedAccountDeleteResponse` does carry `success: boolean` (`:7447-7451`),
     * which is what {@link withdrawalDeclined} reads. There is nothing here to read, so `unknown`
     * is the honest declaration rather than a field this deployment would be inventing.
     *
     * WHAT THE REPLY DOES SAY IS THAT THE REVOCATION IS A BACKGROUND JOB. `revoke_job_id` is
     * "present only when `revoke_on_delete=true`", and the vendor's own comment on it says to track
     * the job and its per-connection results in the Composio dashboard because "a programmatic
     * endpoint to poll this job is not yet generally available". So a clean return here means the
     * config was deleted and the upstream revocations were STARTED — not that they finished. That
     * limit belongs to Composio rather than to this deployment, and it is why `removeServer`'s
     * promise is the one it makes: every account is asked to be withdrawn before anything here is
     * deleted, which is as far as the vendor lets anybody go.
     */
    delete(id: string, params: { revoke_on_delete: true }): Promise<unknown>;
  };
  connectedAccounts: {
    list(query: {
      userIds: string[];
      toolkitSlugs: string[];
      /**
       * Which statuses this particular question is about — see {@link CONNECTED} and
       * {@link REVOCABLE}, which are the only two answers this file gives.
       */
      statuses: VendorAccountStatus[];
      /**
       * Both sharing models, ALWAYS, which is why this is the literal and not the enum.
       *
       * OMITTING IT IS NOT "NO OPINION", in exactly the way an omitted limit is not. The parameter
       * defaults to private accounts only (`ConnectedAccountListParamsSchema.accountType`,
       * `@composio/core` 0.18.1, `src/types/connectedAccounts.types.ts:286-293`), so a person whose
       * account for an app is a SHARED one reads as not connected, is told to connect an app they
       * already have, and — far worse — is invisible to the revoke, which then reports that there
       * was nothing to withdraw while their grant stands. Neither of the two questions this file
       * asks has any reason to care how an account is shared: the gate is about whether this person
       * can act through the app, and the revoke is about ending every account they can act through.
       */
      accountType: "ALL";
      /**
       * Which authorization configs the question is about, ABSENT where it is about all of them.
       *
       * THE TWO QUESTIONS DIFFER HERE TOO, AND ONLY ONE OF THEM MAY ACT. `authConfigIds` is a
       * parameter of the listing (`ConnectedAccountListParamsSchema.authConfigIds`,
       * `@composio/core` 0.18.1, `src/types/connectedAccounts.types.ts:260-264`) forwarded as
       * `auth_config_ids` (`src/models/ConnectedAccounts.ts:117`), and omitting it asks about every
       * config in the project — this deployment's and an operator's hand-made ones alike. That is
       * the right question for {@link ComposioBroker.isConnected}, which only reads whether a person
       * can act through the app, and the wrong one for {@link ComposioBroker.revoke}, which deletes
       * what it finds: see there for why an account on somebody else's config is not this
       * deployment's to end.
       *
       * NEVER THE EMPTY ARRAY. A caller with no configs of its own has nothing to scope TO, and an
       * empty filter is the shape most likely to be read as no filter at all by whatever is on the
       * far side — which would be the unscoped listing arriving through the parameter added to
       * prevent it. `revoke` answers before it asks in that case.
       */
      authConfigIds?: string[];
      limit: number;
      /**
       * Where the last page left off, ABSENT on the first request rather than undefined.
       *
       * `ConnectedAccountListParamsSchema` names it and `ConnectedAccounts.list` forwards it
       * (`@composio/core` 0.18.1, `src/types/connectedAccounts.types.ts:259-266`,
       * `src/models/ConnectedAccounts.ts:118`). This is the listing the paging matters most for:
       * {@link ComposioBroker.revoke} answers `true` for "this person's access has ended", and one
       * page of their accounts is not the set of their accounts. See {@link everyRowOf}.
       */
      cursor?: string;
    }): Promise<{
      /**
       * The id, and `data.displayName` read by name, are the only fields read off an account.
       * `data` and `state.val` also carry the account's tokens, and nothing else is read from them.
       *
       * `transformConnectedAccountResponse` spreads the raw item and overrides the fields it
       * renames (`@composio/core` 0.18.1, `src/utils/transformers/connectedAccounts.ts:52-66`), so
       * `id` and `data` arrive exactly as Composio sent them inside the same warn-only
       * `transform()` as everything else here. An account with no id is the one shape the revoke
       * below cannot act on, and {@link withdrawableAccounts} is what says so about it.
       *
       * THE ROW ITSELF IS AN OBJECT BY CONSTRUCTION, which is why only the fields are in doubt. The
       * same function reads `response.auth_config.id` (`:60`) on its way to building each row, so a
       * row that is not an object raises inside the vendor's code and never reaches this listing.
       */
      items: AccountRow[];
      /**
       * The same truncation signal as the auth-config listing above, from the same vendor schema.
       *
       * `ConnectedAccountListResponseSchema` spells it `nullish`
       * (`src/types/connectedAccounts.types.ts:297-303`) and the transformer sets it on every
       * answer (`src/utils/transformers/connectedAccounts.ts:109-117`). It matters more here than
       * anywhere else in this file: {@link ComposioBroker.revoke} answers `true` for "this
       * person's access has ended", and it used to have seen only one page of the accounts it
       * would have to end. {@link everyRowOf} follows it until there is none left.
       */
      nextCursor?: unknown;
    }>;
    /**
     * Mint one person's connect link against one auth config, with the page to come back to.
     *
     * `link` RATHER THAN `initiate`, AND RATHER THAN `toolkits.authorize`. All three end at a
     * redirect url, and only the choice between them decides whether this deployment keeps working.
     * `toolkits.authorize` takes a user id, a toolkit and an optional auth config id and has no
     * parameter for a callback at all (`@composio/core` 0.18.1, `src/models/Toolkits.ts:333-338`),
     * which is why consent used to end on Composio's hosted page — the address below has nowhere
     * to travel on that call. `initiate` does carry one (`:249`), but the endpoint under it is
     * retired for Composio-managed OAuth on redirectable schemes — cutover 2026-05-08 for new
     * organizations and 2026-07-03 for the rest, after which it throws
     * `ComposioLegacyConnectedAccountsEndpointRetiredError` (`src/models/ConnectedAccounts.ts:146-160`)
     * — and `use_composio_managed_auth` is exactly what {@link ComposioBroker.ensureAuthConfig}
     * creates. `link` is the vendor's own named replacement for that combination, carries the
     * callback, and answers in the same shape.
     *
     * TAKING THE AUTH CONFIG ID IS NOT A COST HERE. It is the one thing `toolkits.authorize` was
     * doing for us, and it did it by listing the configs and creating one at Composio's managed
     * defaults where it found none — which this deployment already does for itself, at enable
     * time, named so an operator can find it in their dashboard. The listing below is that same
     * read; the creation is not repeated, because an app with no config is a state to report
     * rather than one to paper over.
     */
    link(
      userId: string,
      authConfigId: string,
      options: { callbackUrl: string },
    ): Promise<{ redirectUrl?: unknown }>;
    /**
     * Create one person's account from the secret they typed, WITHOUT a consent screen anywhere.
     *
     * THE RAW CLIENT FOR THE REASON BOTH DELETES ARE RAW, and a sharper one. `@composio/core`'s
     * `connectedAccounts.initiate` is the wrapper over this endpoint, and the endpoint under it is
     * retired for the managed-auth path — it throws
     * `ComposioLegacyConnectedAccountsEndpointRetiredError` (`@composio/core` 0.18.1,
     * `src/models/ConnectedAccounts.ts:146-160`) — while `link`, which replaced it, mints a consent
     * url and has nowhere to put a typed value at all. What this flow needs is neither: the person
     * has already typed their credential into a form here, so there is no screen to send them to
     * and nothing to come back from. `@composio/client`'s own create takes the state directly
     * (`0.1.0-alpha.76`, `resources/connected-accounts.d.ts:33`, `:7502-7511`), which is the whole
     * of what this call is.
     *
     * NO `validate_credentials`, AND ITS ABSENCE IS DELIBERATE RATHER THAN AN OVERSIGHT. The
     * parameter exists on the same body and the vendor marks it EXPERIMENTAL (`:7505-7509`).
     * Whether a typed key actually works is settled here by making a call with it rather than by
     * asking Composio to grade it, because a connection Composio accepts is not a connection that
     * works: a wrong value comes back `ACTIVE`.
     *
     * `id` AND `status` READ AS `unknown`, for the reason every other vendor field in this
     * projection is. The generated client declares both as required
     * (`ConnectedAccountCreateResponse`, `:121-146`), which is the schema's promise about what
     * Composio means to send rather than a fact about what arrived — and the id is the one field
     * this whole call exists to answer, so a missing one is a refusal here rather than an
     * `undefined` handed on as the account somebody is meant to be able to undo.
     */
    create(body: {
      auth_config: { id: string };
      /**
       * The person, and the secret they typed, in the shape the vendor's own builder assembles.
       *
       * `state` IS `unknown` BECAUSE WHAT GOES IN IT IS THE APP'S QUESTION RATHER THAN THIS FILE'S
       * ANSWER. The generated client declares it as a fourteen-member union keyed on the scheme,
       * each member's `val` carrying whatever fields that app publishes plus `[k: string]: unknown`
       * (`@composio/client` 0.1.0-alpha.76, `resources/connected-accounts.d.ts:7551`, `:8083-8086`)
       * — so naming a shape here would be this file asserting which boxes an app asks for, which is
       * exactly the thing {@link ComposioBroker.connectionFields} exists to go and ask.
       */
      connection: { user_id: string; state: unknown };
    }): Promise<{ id?: unknown; status?: unknown }>;
    /**
     * Delete one connected account, and ask for the grant behind it to be revoked too.
     *
     * WITHOUT THE FLAG THIS CALL DOES NOT REVOKE ANYTHING, and that is the vendor's own description
     * of it: it "soft-deletes a connected account by marking it as deleted in the database", which
     * "prevents the account from being used for API calls but preserves the record"
     * (`@composio/client` 0.1.0-alpha.76, `resources/connected-accounts.d.ts:59-72`). The refresh
     * token at Google or Slack survives that untouched. Every path in this deployment that claims
     * to end somebody's access — a person disconnecting, an administrator removing an app, a person
     * being offboarded — runs through here, so an unflagged delete made all three of those claims
     * false at once and wrote `true` into the audit trail beside them.
     *
     * WHAT THE FLAG BUYS IS A REQUEST AND NOT A RESULT, which is the whole reason
     * {@link ComposioBroker.revoke}'s answer is named the way it is. The upstream revocation runs as
     * a background job; the response carries its `revoke_job_id` and the vendor documents that no
     * generally available endpoint polls it (`:7447-7459`). Nothing here can say the provider tore
     * the refresh token up, and nothing here pretends to.
     *
     * BUT THE ANSWER DOES SAY WHETHER COMPOSIO DID ITS OWN HALF, AND THAT WAS BEING DISCARDED.
     * `ConnectedAccountDeleteResponse` carries a REQUIRED `success: boolean`, "indicates whether
     * the connected account was successfully deleted" (`@composio/client` 0.1.0-alpha.76,
     * `resources/connected-accounts.d.ts:7445-7459`). This used to be `Promise<unknown>`, read for
     * nothing, on the argument that no field on the answer could support a stronger claim than "we
     * asked". That argument is true of the REVOCATION and false of the DELETE: a 200 carrying
     * `success: false` is Composio saying it did not delete the account, so the background job the
     * flag asks for was never started either — and {@link ComposioBroker.revoke} answered `true`
     * over the top of it while the grant stood at the provider. Reading it is not a stronger claim
     * than "we asked"; it is the difference between having asked and having been refused.
     *
     * DECLARED `success?: unknown` RATHER THAN AT THE VENDOR'S OWN `boolean`, for the reason every
     * other field in this projection is: the generated client parses the body and hands it over, so
     * "required" is the schema's promise about what Composio means to send rather than a fact about
     * what arrived. {@link withdrawalDeclined} is where the three answers are told apart.
     *
     * `revoke_job_id` IS DELIBERATELY NOT READ, and its absence is deliberately not a refusal. The
     * same declaration marks it optional and says it is present "only when `revoke_on_delete=true`"
     * — which says when it CAN appear, not that it always does — so a guard on it would turn every
     * withdrawal Composio accepted into a permanent failure the first time they stopped sending it,
     * which is the shape of mistake this file has already made twice in the other direction.
     *
     * NULLABLE AND OPTIONAL THOUGH THE VENDOR'S OWN DECLARATION IS NEITHER, because the generated
     * client has two answers it resolves with no document: a 204 becomes `null` and a JSON reply
     * carrying `content-length: 0` becomes `undefined` (`@composio/client` 0.1.0-alpha.76,
     * `src/internal/parse.ts:16-42`). Declaring this at the vendor's `ConnectedAccountDeleteResponse`
     * would be the same assertion-over-a-wire-value every other field here refuses to make, and it
     * would hide the one case {@link withdrawalDeclined} has to tell from a refusal.
     */
    delete(
      id: string,
      params: { revoke_on_delete: true },
    ): Promise<{ success?: unknown } | null | undefined>;
  };
};

/**
 * The suffix every auth config this deployment creates carries, so a reader can tell whose it is.
 *
 * An auth config is visible in Composio's own dashboard beside any that were made by hand there,
 * and the two are otherwise indistinguishable. The name is the only field this deployment gets to
 * choose, so it is where the provenance goes.
 */
export const CONFIG_SUFFIX = "(OpenBot)";

/**
 * How many different unrecognised statuses one refusal names before it stops naming them.
 *
 * The set it bounds is as large as the app's config listing, which is paged — see
 * {@link everyRowOf} — so without a bound the length of an operator's refusal is decided by how
 * many authorization configs somebody made. Five is past the number of distinct words this can
 * plausibly be about: `AuthConfigRetrieveResponseSchema` names two, and a vendor that has invented
 * five more at once is a package upgrade rather than a sentence to read.
 */
export const STATUSES_NAMED = 5;

/**
 * Whether this deployment made that auth config, which is the question every decision here turns on.
 *
 * THE SUFFIX IS WRITTEN FOR EXACTLY THIS AND WAS NOT BEING READ. Both callers used to take the
 * first row of an unordered listing, and the two consequences are of different sizes. Removing an
 * app deleted whatever came back first — which can be a config an operator built by hand, with
 * their own scopes and their own tool restrictions, taking every account on it down with it.
 * Beginning a connection attached a person to whatever came back first — which can be a
 * configuration nobody here chose and this deployment cannot see or tighten. And because the order
 * is the vendor's, the two calls can resolve DIFFERENT rows, so an app could be removed while
 * people kept connecting against a config the removal left behind.
 *
 * MATCHED ON THE END OF THE NAME rather than on the whole of it, because the rest of the name is an
 * app's title as an administrator saw it at enable time and titles are edited. The suffix is the
 * part this file writes. Trailing whitespace is tolerated for the same reason it is tolerated
 * anywhere a human-edited string is compared: a name that picked up a space in a dashboard is the
 * same config.
 *
 * IT TAKES A {@link CheckedAuthConfig} AND NOT A {@link VendorAuthConfig}, which is what makes this
 * one line honest. A predicate cannot refuse — it answers true or false — so reading a name the
 * vendor may not have sent here could only ever have meant silently answering `false`, and `false`
 * from this function means "somebody else's config": untouched by a removal, and satisfying the
 * check that stops a second one being created. {@link readableConfigs} is where the absence becomes a
 * sentence instead, upstream of every caller.
 */
export function madeHere(config: CheckedAuthConfig): boolean {
  return config.name.trimEnd().endsWith(CONFIG_SUFFIX);
}

/**
 * The statuses that answer "is this person connected", which is the narrow question of the two.
 *
 * ACTIVE ONLY. An `INITIATED` account is somebody who started an authorization and never finished
 * it, and an `EXPIRED` or `REVOKED` one is a grant that no longer opens anything; counting any of
 * them as connected tells a person their app is wired up and then fails every call they make with
 * it.
 */
export const CONNECTED: VendorAccountStatus[] = ["ACTIVE"];

/**
 * The statuses that answer "what is there to revoke", which is a deliberately wider question.
 *
 * THE TWO QUESTIONS ARE NOT THE SAME ONE, AND TREATING THEM AS ONE LEFT GRANTS STANDING. This used
 * to be a single ACTIVE listing shared by both, on the argument that "connected" and "there is
 * something to revoke" are the same fact. They are not. A half-finished consent can already have
 * been granted at the provider with the callback never delivered; an `EXPIRED` account is an access
 * token that lapsed and a refresh token that did not; an `INACTIVE` one is a live grant the vendor
 * has set aside. None of them should tell a person they are connected, and every one of them is
 * something whose withdrawal is the entire point of pressing disconnect.
 *
 * `REVOKED` IS THE ONE STATUS LEFT OUT, and left out on purpose rather than forgotten. It is the
 * only value that positively says the grant is already gone, so including it would have this
 * deployment delete a tombstone and then record that it ended somebody's access — the one way the
 * audit field can be made to lie in the direction nobody would check.
 */
export const REVOCABLE: VendorAccountStatus[] = [
  "INITIALIZING",
  "INITIATED",
  "ACTIVE",
  "FAILED",
  "EXPIRED",
  "INACTIVE",
];

/**
 * How long one catalogue answer is served to everybody who asks for it.
 *
 * THE CATALOGUE IS READ ONCE PER SEARCH KEYSTROKE OTHERWISE, WHICH IS WHAT THIS IS ABOUT. The admin
 * picker debounces its search field and then asks `/composio/apps`, and that route filters in this
 * process precisely because Composio's toolkit listing takes no search term — so every distinct term
 * a person types is another request for the whole directory, a few hundred rows of it, to answer a
 * question about one. Typing "linear" pulls the catalogue four or five times, and enabling the app
 * afterwards pulls it once more.
 *
 * TEN MINUTES BECAUSE OF WHAT GOES STALE IN IT. The rows are Composio's published toolkits: an app
 * is added to their catalogue or its action count moves every so often, never within one
 * administrator's sitting, and the worst a stale row can do here is show a description or a count
 * that is a few minutes behind. Held for a working session it would be a cache nobody could explain
 * to an operator whose new app is missing; held for seconds it would not survive the debounce it
 * exists for.
 */
export const DIRECTORY_TTL_MS = 10 * 60 * 1000;

/**
 * The held catalogue as a copy nobody else holds, which is what makes handing it out safe.
 *
 * WHAT WAS HANDED OUT WAS THE CACHE ITSELF. One array of one set of row objects was returned to
 * every caller for ten minutes, so a route that sorted the rows in place reordered the catalogue for
 * everybody, and one that edited a row — a title trimmed for display, a description truncated —
 * edited what the next caller would read as Composio's answer. Nothing does that today, which is
 * precisely the problem with leaving it: the first caller that does will have changed a cache it
 * had no idea it was holding, and the fault will surface in the NEXT request rather than its own.
 *
 * `categories` AND `connection` ARE BOTH COPIED, because a shallow spread of the row would hand
 * either of them on by reference. This used to copy the array and say it was "the one field here
 * that is not a primitive", which is what let the other one through: {@link BrokerConnection} is an
 * object in every one of its five shapes, so the row's spread carried one object out of the cache
 * and into every caller for the whole ten minutes — the exact sharing this function exists to end,
 * surviving in the field it is worst in. `connection` is what the app picker hides an `unsupported`
 * app by and what the enable route branches on to decide whether to create an authorization config
 * at all, so a caller that edited the object it was handed would be editing what those two
 * decisions read of every later caller's rows.
 *
 * SPREAD RATHER THAN NAMED PER KIND, so that adding a member to the union — or a field to one of
 * them — cannot quietly reintroduce the sharing. The spread of a union widens to the union, which
 * is the one shape here a `switch` on `kind` would have to be kept in step with by hand.
 *
 * COPIED RATHER THAN FROZEN, which was the other candidate. Freezing would make the sharing safe by
 * making a mutation throw, but the type says `BrokerApp[]` and a caller is entitled to sort a list
 * it was given; turning a reasonable caller into a `TypeError` is a worse answer than a few hundred
 * small objects, which is nothing beside the request this cache exists to avoid.
 */
export function copyOf(apps: Promise<BrokerApp[]>): Promise<BrokerApp[]> {
  return apps.then((held) =>
    held.map((app) => ({
      ...app,
      categories: [...app.categories],
      connection: { ...app.connection },
    })),
  );
}