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.

8.9 KB
Raw Blame
import * as arcade from "./arcade";
import * as builtinRoutines from "./builtin-routines";
import * as composio from "./composio";
import * as driveRest from "./google-drive-rest";
import type { ListedTool, McpCallResult } from "./mcp";
import * as mcp from "./mcp";

/**
 * How this deployment reaches one vendor: which protocol, from the kind `./access` resolved.
 *
 * WHY THIS EXISTS. Every connector used to be MCP, so "the transport" was an import. Google's Drive
 * MCP server turned out to be gated behind a developer preview, and the same product's ordinary REST
 * API is generally available — so one vendor needed a second way in, and a second way in wants a
 * seam rather than a branch at each call site.
 *
 * The interface STARTED as MCP's OWN: `listTools` and `callTool`, the two functions {@link ./mcp}
 * already exported, with the shapes it already used. That direction matters. Had the REST adapter
 * been given its own interface with MCP adapted to fit, MCP would have become a special case of a
 * shape invented for Drive. As it is, MCP is the contract the adapters conform to, which is why
 * swapping Drive back is one field on one catalogue entry and not a refactor.
 *
 * What has been added since is a SUPERSET of that shape rather than a departure from it, so an
 * MCP-shaped implementation still satisfies the seam unchanged. `listTools` answers `ListedTool[]`,
 * which is `McpTool` plus fields describing what a listing said about an action; the connection
 * carries an `actorId` and a `botId` for the transports whose authorization is the actor rather
 * than a credential; and one reserved key on `args` hands a transport the recorded version of the
 * action being called. Every addition is OPTIONAL, and that is what keeps an MCP-shaped
 * implementation an implementation of this interface rather than an exception to it.
 *
 * This paragraph used to say those fields were ones "a broker publishes and an MCP server does
 * not", and that `mcp.ts` therefore read none of them. Both were false: the MCP specification
 * defines `annotations.destructiveHint`, servers do publish it, and `mcp.ts` was dropping it — so a
 * tool a vendor declared destructive classified as a read wherever a curated write list omitted it.
 * `mcp.ts` now reads that hint, and deliberately does not read `readOnlyHint`, because a hint may
 * narrow what a Bot may do and may never widen it. The effect column is therefore not one
 * transport's vocabulary; it is what any listing was willing to say.
 *
 * There are exactly two call sites in the whole system — the tool listing and the tool call — and
 * both take a transport from here. Nothing else reads a `TransportKind` at all: the OAuth flow,
 * the grants, the policy engine and the audit trail are written without one. Whose credential a
 * row goes out on is a SEPARATE axis — `./access`'s `CredentialSource` — and that one is NOT
 * protocol-blind, since the brokered branch of the credential selection looks a person's
 * connection up in `composio_connections` by name. Read the blindness as a claim about this union
 * and not about the store.
 */
export type VendorTransport = {
  /**
   * Whether discovering the tool list needs somebody's credential.
   *
   * True for MCP, where the list is an answer from a remote server that will not give it up
   * unauthenticated. False whenever no credential has to be SELECTED for the listing: either
   * because the list is this code, as it is for Drive and Routines, or because the transport
   * already holds the one key it lists on and never receives it through the connection, as
   * Composio does — a broker publishes an action's schema to anybody who asks with the
   * deployment's own key.
   *
   * It is on the transport rather than assumed by the caller because getting it wrong is a whole
   * broken setup flow. Assumed true, an administrator configuring Drive was sent to their own
   * settings page to connect a personal account, purely so a token could be minted, passed to a
   * function that ignores it, and discarded — then sent back to press refresh. Nothing about that
   * sequence hinted that the middle step was doing no work.
   */
  listNeedsCredential: boolean;
  listTools(connection: {
    url: string;
    token?: string;
    /** Where `token` goes when the vendor does not read `Authorization`; only MCP reads it. */
    tokenHeader?: string;
    /**
     * Declared by the shared connection shape, and never supplied on THIS path.
     *
     * `refreshTools` is the only caller of `listTools` in the system, and it passes `{url, token}`.
     * No implementation here even accepts either field: `builtin-routines` takes no argument at
     * all, Composio takes only `url`, and MCP and Drive take `{url, token}`. So a transport that
     * read one would read `undefined` every time, and nothing on the listing path may be
     * authorized by them.
     *
     * The actor is the authorization on the CALLING path instead — see {@link callTool} below,
     * where Routines and Composio each refuse a run attributed to nobody. Listing is not
     * somebody's: it is what this deployment offers everybody. A list that insisted on an actor
     * would be asked without one, store zero tools, and leave the vendor advertising nothing to
     * anybody.
     */
    actorId?: string;
    botId?: string;
  }): Promise<ListedTool[]>;
  callTool(
    connection: {
      url: string;
      token?: string;
      tokenHeader?: string;
      /**
       * Who this call is for, and which Bot is making it.
       *
       * Ignored where a CREDENTIAL is the authorization: MCP and Drive answer to a token, and whose
       * it is was settled before the connection was built, so neither module's `Connection` type
       * carries these at all. Read where the ACTOR is the authorization: Routines acts on this
       * deployment's own tables, and Composio opens one person's account with a key the deployment
       * holds for everybody, so both refuse a run attributed to nobody rather than run it as
       * somebody. A routine is somebody's; so is a mailbox.
       *
       * They come off the connection, which the call path derives from the session, and are never
       * read out of `args`. A model that could name either could schedule work as another person or
       * read another person's mail.
       */
      actorId?: string;
      /** The Bot the run belongs to. A routine runs as its Bot, which is never a name a model supplies. */
      botId?: string;
    },
    toolName: string,
    args: Record<string, unknown>,
  ): Promise<McpCallResult>;
};

/**
 * The protocols this deployment can dial.
 *
 * A closed union rather than a string, so adding one is a change to this file and to the registry
 * below together. Named by a catalogue entry for a curated vendor and by `./access` from the row's
 * provenance for a Composio app; either way, a kind that does not exist should not typecheck.
 */
export type TransportKind =
  | "mcp"
  | "google-drive-rest"
  | "builtin-routines"
  | "composio"
  | "arcade";

/**
 * The kinds a CATALOGUE ENTRY may name, which is every one except the broker's.
 *
 * CRITERION. Neither broker's transport (`composio`, `arcade`) is writable in a reviewed entry, and the compiler is what says so.
 *
 * REASON. A brokered row is reached by an app slug read off its url and a per-person connection
 * looked up by that slug; a catalogue entry has neither, and `accessFor` answers `toolkit: null`
 * and `credential` from the entry's auth kind for everything it resolves. So an entry declaring
 * `transport: "composio"` yielded a Composio dial with no app named, no brokered gate, and
 * `reachedAs` taken from an auth kind that has nothing to do with whose account the broker would
 * have run in — a row that walks past both store gates while satisfying every type in the module
 * that claims to enumerate how a row can be reached. No entry declares it, which is why this is a
 * door being shut rather than a bug being fixed, and why shutting it costs nothing.
 *
 * `Exclude` rather than a hand-written second union, so a kind added above is offered to the
 * catalogue automatically and only the broker stays out.
 */
export type CuratedTransportKind = Exclude<
  TransportKind,
  "composio" | "arcade"
>;

const TRANSPORTS: Record<TransportKind, VendorTransport> = {
  mcp,
  "google-drive-rest": driveRest,
  "builtin-routines": builtinRoutines,
  composio,
  arcade,
};

/**
 * The transport for a resolved kind.
 *
 * A kind rather than a catalogue entry, because deciding the kind is no longer this file's business.
 * It used to read `entry?.transport ?? "mcp"`, which was complete while every server either had an
 * entry or was somebody's MCP endpoint — and silently wrong for a Composio app, which has no entry
 * and would have had `composio://gmail` dialled as an HTTP server. `./access` decides now, once, for
 * every row shape; this is the lookup that follows.
 */
export function transportFor(kind: TransportKind): VendorTransport {
  return TRANSPORTS[kind];
}