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.

23.5 KB
Raw Blame
import { queryOptions } from "@tanstack/react-query";
import { client } from "@/lib/client";
// This import closes a cycle: `./provider-vocabulary` imports `pluginsProvider` from this file.
// It is safe for one reason, and the reason is the rule. Both live bindings that cross it —
// `directoryReadFailure` here, `pluginsProvider` there — are `export function` declarations,
// which are fully initialised during module instantiation, so neither can be caught in the
// temporal dead zone whichever module evaluates first; and both are only ever called from inside
// a function body (a `queryFn`, `directoryRouteDecision`), long after both modules have finished
// evaluating. Nothing may call across this import at module scope. A
// `const X = directoryReadFailure("...")` at the top level of this file would reach `VOCABULARY`,
// a lexical `const` in the other module, mid-evaluation: it throws under one evaluation order and
// not the other, so it can pass every test and still fail in a production bundle.
import {
  directoryReadFailure,
  type PluginsProvider,
} from "./provider-vocabulary";

/**
 * Re-exported, not re-declared.
 *
 * The field list is asked for by a POST, so it lives beside its only producer in `./mutations` —
 * a second copy here would be free to drift from the shape that write actually returns.
 */
export type { BrokerField } from "./mutations";

/** A tool one server offers, as the Plugins page sees it. */
export type PluginTool = {
  serverId: string;
  name: string;
  description: string;
  inputSchema: Record<string, unknown>;
  /** `<serverId>/<name>`. What a grant names. */
  ref: string;
  /** Whether it changes something. Anything not positively known to be a read is a write. */
  effect: "read" | "write";
  /**
   * Whether the vendor warns that it destroys something.
   *
   * Beside {@link effect} rather than folded into it: the rule engine judges reads and writes and
   * gains nothing from a third value, while a person deciding whether to switch an action on is
   * asking a different question. Recorded from the vendor's own labels, so false is an absence of a
   * claim rather than a claim of safety.
   */
  destructive: boolean;
  grantedTo: string[];
};

/**
 * A grant on a tool this server does not currently advertise.
 *
 * Held and not offered: nothing reaches a model, because a Bot is told about a tool only when the
 * grant and the tool list agree. That is a fact about what the vendor advertises today, not about the
 * grant, so it is reported rather than quietly dropped — a connector that starts advertising the name
 * again offers it again.
 */
export type WithdrawnGrant = {
  /** `<serverId>/<toolName>`. What a grant names, and what an administrator revokes. */
  ref: string;
  name: string;
  grantedTo: string[];
};

export type PluginServer = {
  id: string;
  title: string;
  logo?: string | null;
  vendor: string;
  url: string;
  summary: string;
  docsUrl: string;
  /** `first-party` for a reviewed entry, `custom` for one an administrator added by URL. */
  provenance: string;
  hasCredential: boolean;
  toolsRefreshedAt: string | null;
  lastError: string | null;
  /**
   * What the last refresh left out for its names. A warning: the rest were stored. Optional because
   * a server replica older than this field does not send it, mid-rollout.
   */
  skippedTools?: string[];
  addedBy: string | null;
  /**
   * Whether this server registers its own OAuth client (RFC 7591) rather than waiting on an
   * administrator to paste one in.
   */
  dynamicClient: boolean;
  /**
   * How this server's authorization config was CREATED, for the brokered rows that have one.
   *
   * What was written down when somebody enabled the app, not what the catalogue publishes today.
   * The catalogue is the vendor's, and an app it starts advertising under a different scheme has
   * not moved the config this deployment already created — so a screen deciding what a live
   * connection does reads this and never a fresh listing. The vocabulary is the vendor's own scheme
   * literals (`OAUTH2`, `DCR_OAUTH`, `API_KEY`, `NO_AUTH`, and the rest), so it is a string rather
   * than a union this page would have to keep level with Composio's.
   *
   * Null is not an older brokered row. It is a row that is not brokered at all.
   */
  authScheme: string | null;
  tools: PluginTool[];
  /** Empty for a healthy connector. See {@link WithdrawnGrant}. */
  withdrawn: WithdrawnGrant[];
  /**
   * Whether this app is PERSONAL, held one credential per person, or SHARED, with a single
   * deployment-held account that every Bot holding a grant acts as. Null for a server that has
   * never been asked, which reads as personal everywhere today.
   *
   * What a row's {@link PluginConnection.holder} is checked against, and the only place that
   * distinction is decided — a connection row never switches an app between the two on its own.
   */
  accountMode: "personal" | "shared" | null;
  /**
   * Whether a Shared app's one deployment-held account is connected yet.
   *
   * Asked of the server rather than read off the connections list, because a Shared app with
   * nothing connected is not an absence from that list — see `GET /connections`, which lists it
   * anyway so it can be offered a Connect action. Meaningless, and always false, while
   * {@link accountMode} is not `"shared"`.
   */
  sharedVendorConnected: boolean;
  /**
   * Who may give this app to a Bot: any Bot's owner, for their own Bot (`any`), or only an admin
   * (`admin`), with the default for its account filled in. Every person's own account defaults to
   * `any`, as do the built-in Routines; everything else to `admin`.
   */
  ownerGrants: "any" | "admin";
  /** What an admin chose, or null where the default is in force. */
  ownerGrantsChosen: "any" | "admin" | null;
};

export type PluginSkill = {
  id: string;
  slug: string;
  /** Whose it is. Null means the deployment's: an administrator looks after it. */
  ownerUserId: string | null;
  title: string;
  summary: string;
  instructions: string;
  origin: string;
  installedBy: string | null;
  grantedTo: string[];
  /**
   * The tools this skill says it needs, as `<serverId>/<toolName>` refs.
   *
   * A declaration, not a grant, and the difference is the whole reason anybody may write a skill:
   * naming a tool here cannot make it callable. Selection intersects this with what the Bot was
   * granted, so a skill naming a tool its Bot does not hold selects the skill and loads nothing.
   * `grantedTo` on the tool side is what decides.
   */
  tools: string[];
};

export type CatalogueItem = {
  key: string;
  title: string;
  vendor: string;
  summary: string;
  docsUrl: string;
  /**
   * Whose credential reaches this server.
   *
   * `deployment-bearer` is a token an administrator holds for everybody, and the only one this page
   * can collect. `user-oauth` is reached as whoever is asking, so each person connects their own
   * account and there is no token to type here. `builtin` is a first-party capability that runs
   * inside this deployment — there is nothing to connect and nothing to type.
   */
  auth: "none" | "deployment-bearer" | "user-oauth" | "builtin";
  /** True for a vendor that gives every customer their own hostname. */
  perInstance: boolean;
};

/** One app in Composio's directory, as the picker shows it. */
export type ComposioApp = {
  slug: string;
  name: string;
  description: string;
  logo: string | null;
  categories: string[];
  /** The size of the decision, shown before enabling. */
  actionCount: number;
  /**
   * How many of those actions the provider classified, how many distinct non-empty scope sets they
   * ask for, and how many carry a scope at all — three more facts of the size-of-the-decision kind.
   *
   * REQUIRED AND NULLABLE, NEVER OPTIONAL, AND NOTHING HERE WRITES `?? 0`. `0` means measured and
   * none, so the coverage warning fires; `null` means the provider does not publish it, so the page
   * says nothing. An optional field makes those the same shape at the call site, and the natural
   * `?? 0` fires a coverage warning on a Composio deployment — a false alarm at exactly the moment
   * somebody is deciding whether to trust an app.
   *
   * An action with no scopes is not its own permission: it is covered by any approval at all, so it
   * joins no group. `scopedActionCount` is what keeps `permissionCount: 1` over two actions from
   * reading as one permission covering both.
   */
  classifiedCount: number | null;
  permissionCount: number | null;
  scopedActionCount: number | null;
  enabled: boolean;
};

export type PluginsPage = {
  catalogue: CatalogueItem[];
  servers: PluginServer[];
  skills: PluginSkill[];
  /**
   * Whether a Bot holding no credential of its own can still call a tool back.
   *
   * True when the deployment has a shared secret configured for it. A grant decides whether a tool
   * is offered to a model at all; this decides whether the call it makes can be authenticated. With
   * neither this nor a credential issued to the Bot, every call is refused before it reaches the
   * grant, the boundary or the audit trail, which is not something a grant switch can show.
   */
  botsMayCallBack: boolean;
  /**
   * The redirect URI to register with a `user-oauth` vendor, exactly as this deployment will send it.
   *
   * From the server rather than assembled here, because it has to match what was registered
   * character for character. Null when the deployment has no public URL and so cannot complete a
   * consent flow at all.
   */
  redirectUri: string | null;
  /**
   * Whether this deployment has Composio configured.
   *
   * A boolean about configuration and never the key: the page needs to know whether the directory
   * can be browsed at all, and that question is answerable without the API key ever leaving the
   * server.
   */
  composioConfigured: boolean;
  /**
   * Whether this deployment's broker authorizes ONE ACTION AT A TIME.
   *
   * A DECLARED CAPABILITY, read with a presence test and never a vendor name. The server computes
   * it from the very expression `/servers/:id/authorize` and the `/arcade/verify` return leg gate
   * on, so a screen that draws the per-action grant list and the routes that serve its buttons
   * cannot key on different facts. Gating on `provider === "arcade"` instead left a broker named
   * arcade whose flow is absent drawing a list whose every Authorize press 503s.
   *
   * Required, like `composioConfigured` and unlike `provider`: a capability is a value the server
   * declares, so the type does not offer "did not say" as a third answer. False on Composio, whose
   * auth config fixes one state for a whole toolkit, so a Composio deployment is unchanged.
   */
  authorizesPerAction: boolean;
  /**
   * Which vendor brokers this deployment's apps, as a NAME. Read it through {@link pluginsProvider}.
   *
   * A screen that FILTERS by brokered-ness needs no provider name: one provider holds rows at a
   * time (spec D3), which is why `brokeredAccountsListedOn` is a predicate over `provenance`. A
   * screen that NAMES a vendor ("Browse Composio", the `/admin/plugins/composio` route,
   * `COMPOSIO_API_KEY`, "Reached through Composio") cannot derive that name from a row, and this
   * field is the only thing that answers it. Separate from `composioConfigured`, which asks whether
   * the directory can be browsed at all.
   *
   * A name, never a key and never a capability: nothing about the vendor key travels with it.
   * Optional because a payload from an older server does not carry it.
   */
  provider?: "composio" | "arcade";
};

/**
 * The provider a payload names, `"composio"` when the server did not say.
 *
 * So a Composio deployment renders byte-identically and a page served by an older server does not
 * blank. Also `"composio"` before the page has loaded.
 */
export function pluginsProvider(
  page: PluginsPage | undefined,
): "composio" | "arcade" {
  return page?.provider ?? "composio";
}

/** What one Bot holds, which is all the runtime needs to offer it. */
export type GrantedPlugins = {
  tools: {
    ref: string;
    toolName: string;
    description: string;
    inputSchema: Record<string, unknown>;
  }[];
  skills: {
    slug: string;
    title: string;
    summary: string;
    instructions: string;
  }[];
};

export const pluginKeys = {
  all: ["plugins"] as const,
  page: () => ["plugins", "page"] as const,
  forAgent: (agentId: string) => ["plugins", "for-agent", agentId] as const,
  connections: () => ["plugins", "connections"] as const,
  siblings: (serverId: string) => ["plugins", "siblings", serverId] as const,
  composioApps: (query: string) =>
    ["plugins", "composio", "apps", query] as const,
};

/**
 * One account this person has connected, from their own point of view.
 *
 * DELIBERATELY NON-UNIFORM, because `/api/plugins/connections` concatenates two reads: connections
 * held in this deployment's own vault, and brokered ones Composio keeps on our behalf. The fields a
 * settings row draws from — the server id, the scope, the date — line up across both, which is why
 * one type covers both. The pair below does not, so it is optional rather than required: making it
 * required would be a lie the compiler then enforced on every held row.
 */
export type PluginConnection = {
  serverId: string;
  /**
   * Whether the credential behind this row has been withdrawn or deleted, present only on a HELD
   * row — a brokered one keeps no secret here, so it has no equivalent question.
   *
   * A ROW IS NOT ACCESS. Revoking a credential leaves this row pointing at it, and reconnecting
   * moves `credential_id` and `updated_at` without touching `connected_at`, so the presence of a
   * row says nothing about whether the app can be used and nothing visible changes when it can be
   * again. Anything drawing the word "connected" has to read this; anything listing the apps
   * somebody has ever connected does not.
   *
   * Undefined on a brokered row and on any shape written before this existed, and the absence
   * reads as not revoked.
   */
  revoked?: boolean;
  /** What the vendor actually granted, which is not always what was asked for. Empty for brokered. */
  scope: string;
  connectedAt: string;
  /**
   * Whose account this row is: the signed-in person's own, or the one standing account of a Shared
   * app (see {@link PluginServer.accountMode}) that every Bot holding a grant acts as regardless of
   * who is asking. Undefined on a shape written before the distinction existed, which reads as
   * `"person"` — see {@link personalConnections}, which is what a screen asking "is this mine" reads
   * through rather than comparing against the literal.
   */
  holder?: "person" | "deployment";
  /**
   * Whether the deployment's one shared account is connected, present only on a DEPLOYMENT row.
   *
   * A Shared app's row is listed even when nothing is connected to it yet — see
   * {@link PluginServer.sharedVendorConnected} — so a reader cannot take the row's presence for a
   * yes. This is the field that answers.
   *
   * NOTE: an unconnected deployment row has no real date for {@link connectedAt} either, which
   * would want that field widened to `string | null` to say so honestly. Left as `string` here
   * instead — `connected-accounts/$key.tsx` hands it straight to `new Date(...)`, and widening
   * turned that red under `bun run typecheck`. A row with nothing connected must therefore be read
   * through this field, not through `connectedAt`, until that caller is dealt with.
   */
  connected?: boolean;
  /**
   * The email of whoever connected the shared account, present only on a DEPLOYMENT row.
   *
   * Null is reachable: nobody has connected it yet, or the row predates this being recorded.
   */
  connectedBy?: string | null;
  /**
   * The vendor's own name for the connected account (an org, a bot, a workspace), present only on
   * a DEPLOYMENT row.
   *
   * Shown instead of a person's name precisely because there isn't one here — the account is the
   * deployment's, and this is what tells one Shared app's row apart from another's otherwise
   * identical "connected" answer.
   */
  displayName?: string | null;
  /**
   * Whether a real call was last made with this credential, present only on a BROKERED row.
   *
   * Only a brokered row has anything to re-check: this deployment holds no secret for it, only a
   * note that Composio said yes, and that note can drift when somebody ends the connection in
   * Composio's own dashboard. A held connection has no equivalent question, so its rows carry
   * neither field, and the absence of the pair is what tells the two READS apart — nothing more.
   *
   * It is NOT how a reader learns how an app connects. That comes from {@link PluginServer.authScheme}
   * on the server, and a page deriving it from a connection row instead would be a second answer to
   * a question already carried.
   */
  verified?: boolean;
  /**
   * When {@link PluginConnection.verified} was last earned, present only on a brokered row.
   *
   * Null is reachable and means never checked, which is why it stays null rather than collapsing
   * the way `connectedAt` does. For the rows an older migration backfilled it is the moment of
   * consent rather than of a probe, so it is not read as "this connection answered then".
   */
  verifiedAt?: string | null;
  /**
   * Which action the last check of this key actually SPENT, present only on a brokered row.
   *
   * A RECORD READ OFF THE ROW, not a reading of what the app publishes now — which is why it
   * survives a reload where the answer to a connect or a re-check cannot, and why nothing the
   * catalogue does afterwards can move it. Read together with {@link PluginConnection.verified} it
   * separates the three situations that share the one word `false`: no probe means nothing was
   * tried, because at the time of the check the app published nothing safe to spend a key on; a
   * probe with `verified` means the check ran and passed; and a probe WITHOUT it means the check
   * ran and the vendor refused the key, over an account that is still standing.
   *
   * A PAST TENSE, AND ONLY THAT. It is what the SENTENCE beneath the row is drawn from. What it
   * must never be asked is whether the key could be checked again — see
   * {@link PluginConnection.checkable}, which is the present-tense answer and a different field
   * because it is a different question.
   *
   * Optional for the same reason the pair above is: that endpoint concatenates two reads, and only
   * the brokered one carries any of this. Undefined is the absence of the field and not a fourth
   * state.
   */
  probe?: string | null;
  /**
   * Whether the app has anything to check this key against TODAY, present only on a brokered row.
   *
   * ASKED OF THE APP AND NOT OF THE CONNECTION, out of the same chooser a real check would use: has
   * this app published an action safe to spend somebody's key on — a vendor-labelled read, not
   * destructive, needing no arguments, recorded at a version that can be called. It is what the
   * Re-check button is drawn from, and nothing else here is.
   *
   * SEPARATE FROM {@link PluginConnection.probe} BECAUSE COLLAPSING THEM DEADLOCKS THE PAGE. While
   * the button read the record, a key connected to an app with nothing to try recorded null, for
   * good — and the button stayed withheld however much the app published later, though pressing it
   * is the only thing that could ever put an action in the record. The past and the present are two
   * questions; the row asks them separately and answers them separately.
   *
   * Optional for the same reason as the fields above, and false and absent mean the same thing to
   * the only reader there is: nothing to press. That is why a screen may flatten this where it
   * passes `probe` through unflattened — a missing verdict and a null verdict are different
   * sentences, while a missing gate and a closed gate are the same gate.
   */
  checkable?: boolean;
};

export type PluginConnections = {
  connections: PluginConnection[];
  redirectUri: string | null;
};

/**
 * The connections that are the signed-in person's own. A Shared app's row is the deployment's, and
 * every screen that asks "is this mine" must never read it as yes.
 */
export function personalConnections(
  rows: PluginConnection[],
): PluginConnection[] {
  return rows.filter((row) => row.holder !== "deployment");
}

/**
 * The signed-in person's own connections.
 *
 * There is no version of this scoped to anybody else: the endpoint answers for whoever is asking,
 * so a page cannot accidentally render somebody else's.
 */
export function connectionsQueryOptions() {
  return queryOptions({
    queryKey: pluginKeys.connections(),
    queryFn: async (): Promise<PluginConnections> => {
      const response = await client("/api/plugins/connections", {
        fallback: "Couldn't load your connections.",
      });
      return response.json();
    },
  });
}

/**
 * What disconnecting this app would also end, as the server computed it.
 *
 * `siblings` are other apps' toolkit names (never this one) and `unanswered` is a COUNT of apps that
 * could not be asked about. A deployment whose broker holds one account per app always answers
 * empty.
 */
export type ConnectionSiblings = { siblings: string[]; unanswered: number };

export function connectionSiblingsQueryOptions(serverId: string) {
  return queryOptions({
    queryKey: pluginKeys.siblings(serverId),
    queryFn: async (): Promise<ConnectionSiblings> => {
      const response = await client(
        `/api/plugins/servers/${encodeURIComponent(serverId)}/connection/siblings`,
        {
          fallback: "Couldn't read which other apps share this connection.",
        },
      );
      const body: Partial<ConnectionSiblings> = await response.json();
      /*
       * NARROWED RATHER THAN TRUSTED: an answer that is not this shape is read as "nothing to say",
       * which draws no warning, rather than a throw that takes the whole page down for a sentence.
       */
      return {
        siblings: Array.isArray(body.siblings) ? body.siblings : [],
        unanswered:
          typeof body.unanswered === "number" && body.unanswered > 0
            ? body.unanswered
            : 0,
      };
    },
  });
}

export function pluginsPageQueryOptions() {
  return queryOptions({
    queryKey: pluginKeys.page(),
    queryFn: async (): Promise<PluginsPage> => {
      const response = await client("/api/plugins", {
        fallback: "Plugins could not be loaded.",
      });
      return response.json();
    },
  });
}

/**
 * The active broker's app directory, narrowed by a search term.
 *
 * The term goes to our own endpoint because the vendor's client drops a search parameter and
 * answers with an unfiltered page, so filtering has to happen somewhere that admits to doing it.
 */
export function composioAppsQueryOptions(
  query: string,
  provider: PluginsProvider,
) {
  return queryOptions({
    queryKey: pluginKeys.composioApps(query),
    queryFn: async (): Promise<{ apps: ComposioApp[] }> => {
      const response = await client(
        `/api/plugins/composio/apps?q=${encodeURIComponent(query)}`,
        { fallback: directoryReadFailure(provider) },
      );
      return response.json();
    },
  });
}

/**
 * Polled grant snapshot for what the active Bot should be offered; call-time checks still enforce.
 */
export function agentPluginsQueryOptions(agentId: string) {
  return queryOptions({
    queryKey: pluginKeys.forAgent(agentId),
    enabled: agentId.length > 0,
    refetchInterval: 15_000,
    queryFn: async (): Promise<GrantedPlugins> => {
      const response = await client(
        `/api/plugins/for/${encodeURIComponent(agentId)}`,
        { fallback: "Couldn't load this Bot's apps." },
      );
      return response.json();
    },
  });
}