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.4 KB
Raw Blame
import { queryOptions } from "@tanstack/react-query";
import { client } from "@/lib/client";

/**
 * What each work app is for the person looking, on one Bot, and the requests they file when only an
 * administrator can change it.
 *
 * THE STATE IS THE SERVER'S. The browser draws `state` and `requestKind` as they arrive and never
 * derives either from the other fields: whether an app is switched off, held by the Bot, connected
 * by this person or waiting on a team account is read on the server from the same tables every
 * call gate reads.
 */

/**
 * The eight things a person can be told about one app on one Bot.
 *
 * `ready` — usable now. `not_connected` / `reconnect` — waiting on an account: this person's own,
 * which they connect or reconnect themselves, or on somebody else's Team Bot the owner's, which only
 * the owner can (see `accountHolder`). `shared_not_connected` — a Shared app whose team account an
 * administrator has not connected. `shared_not_approved` — a Shared app whose team account IS
 * connected, but an administrator has not approved this Bot's audience for it, so every call is
 * refused; the refused call files the administrator's request itself, so there is none to press.
 * `disabled` — switched off at the deployment, for the reason `unavailable` gives. `not_granted` —
 * enabled, and this Bot holds none of it; only an admin can give it. `owner_grantable` — the same,
 * except the person looking owns the Bot and the app is open to owners, so they can give it
 * themselves (see `needsConnect`).
 */
export type AppAccessState =
  | "ready"
  | "not_connected"
  | "reconnect"
  | "shared_not_connected"
  | "shared_not_approved"
  | "disabled"
  | "not_granted"
  | "owner_grantable";

/**
 * Why an app is switched off. `absent` — nobody switched it on here. `composio_unconfigured` — a
 * brokered app (Composio or Arcade) on a deployment with no key for its broker. The other three — a scheme the server cannot
 * read, an OAuth client nobody registered, a token nobody pasted — are a set-up left unfinished.
 */
export type AppUnavailable =
  | "absent"
  | "composio_unconfigured"
  | "scheme_unreadable"
  | "oauth_client_missing"
  | "token_missing";

/** What a press of Request access asks an administrator for. */
export type AppAccessRequestKind = "enable" | "grant" | "connect_shared";

export type AppAccess = {
  /** The server id the app has, or the one enabling it would mint. What a request names. */
  key: string;
  /** The app's own name — "Gmail", never a humanised server id. */
  displayName: string;
  logo: string | null;
  /** A brokered app names its broker; a catalogue or custom app is reached directly. */
  provider: "composio" | "arcade" | "catalogue" | "custom";
  /** Whose account calls land in: each person's own, one team account, or nobody's. */
  account: "personal" | "shared" | "deployment";
  /** How the account is connected: this deployment's OAuth flow, a broker's consent, or a key form. */
  connect: "oauth" | "consent" | "key" | null;
  authScheme: string | null;
  accountMode: "personal" | "shared" | null;
  state: AppAccessState;
  /** Why the app is switched off, when state is "disabled"; null otherwise. */
  unavailable: AppUnavailable | null;
  /**
   * Whose account a personal-account app's calls use for this person on this Bot: "you", or "owner"
   * when this is somebody else's published Team Bot and its owner has connected the app (calls then
   * run on the owner's account). null when the app is not a personal-account app.
   */
  accountHolder: "you" | "owner" | null;
  /**
   * True when calls will use this person's OWN account on somebody else's Team Bot and they have not
   * given standing consent: the first use raises an "Allow once / Always allow" card. State is "ready".
   */
  asksFirst: boolean;
  /** Whether this Bot holds any of the app's tools. */
  granted: boolean;
  /** Who may give the app to a Bot: any Bot's owner, or only an admin. */
  ownerGrants: "any" | "admin";
  /** Whether everything this Bot holds of the app was given by its owner, who may take it back. */
  givenByOwner: boolean;
  /**
   * In `owner_grantable`, whether giving it has to start with connecting the person's own account.
   * False in every other state.
   */
  needsConnect: boolean;
  /**
   * When the account this app runs in for this person was connected, or null. Read by the chat card
   * to tell an account lost at the vendor from one connected again since. See `AppAccessCard`.
   */
  connectedAt: string | null;
  /** The request Request access files for this state; null where the next step is the person's. */
  requestKind: AppAccessRequestKind | null;
  /** This person's pending request of exactly that kind — drawn as "Requested". */
  request: { id: string; kind: AppAccessRequestKind; createdAt: string } | null;
};

/** A request as the person who filed it and the administrator answering it both read it. */
export type AppAccessRequest = {
  id: string;
  appKey: string;
  appTitle: string;
  kind: AppAccessRequestKind;
  status: "pending" | "approved" | "dismissed" | "cancelled";
  agentId: string | null;
  botName: string | null;
  requestedBy: string;
  requesterEmail: string | null;
  requesterName: string | null;
  createdAt: string;
  resolvedAt: string | null;
  resolvedBy: string | null;
};

/** The administrator's inbox: the requests asked for, and a count per app for the Plugins list. */
export type AppAccessInbox = {
  requests: AppAccessRequest[];
  counts: { total: number; byApp: Record<string, number> };
};

/*
 * UNDER `["plugins"]`, so every plugin write that already refreshes the plugin screens — connecting
 * an account, enabling an app, granting a tool — refreshes what these say too, without each of
 * those writes having to know this view exists.
 */
export const appAccessKeys = {
  all: ["plugins", "app-access"] as const,
  bot: (agentId: string) => ["plugins", "app-access", "bot", agentId] as const,
  app: (agentId: string, app: string) =>
    ["plugins", "app-access", "bot", agentId, "app", app] as const,
  inbox: (app?: string) =>
    ["plugins", "app-access", "inbox", { app: app ?? null }] as const,
  giveable: ["plugins", "app-access", "giveable"] as const,
};

/** An app this person could give their own Bots. */
export type GiveableApp = Pick<
  AppAccess,
  "key" | "displayName" | "logo" | "account"
>;

/**
 * The apps this person could give their own Bots: switched on and open to owners, and connected
 * where the app runs on their own account. What the New Bot sheet offers ticked, and the switches
 * on a Bot's page. Empty where an admin turned the feature off for them.
 */
export function giveableAppsQueryOptions() {
  return queryOptions({
    queryKey: appAccessKeys.giveable,
    queryFn: (): Promise<GiveableApp[]> =>
      client("/api/plugins/giveable", "apps", {
        fallback: "Couldn't load your apps.",
      }),
  });
}

/** Every work app this Bot holds, with what each is for the person asking. */
export function botAppsQueryOptions(agentId: string) {
  return queryOptions({
    queryKey: appAccessKeys.bot(agentId),
    queryFn: (): Promise<AppAccess[]> =>
      client(`/api/plugins/for/${encodeURIComponent(agentId)}/apps`, "apps", {
        fallback: "This Bot's apps could not be loaded.",
      }),
  });
}

/**
 * One app, by key or by name, whether or not this Bot holds it — what a card in a conversation
 * asks, so it never draws a stale state.
 */
export function botAppQueryOptions(agentId: string, app: string) {
  return queryOptions({
    queryKey: appAccessKeys.app(agentId, app),
    queryFn: (): Promise<AppAccess> =>
      client(
        `/api/plugins/for/${encodeURIComponent(agentId)}/apps/${encodeURIComponent(app)}`,
        "app",
        { fallback: `What ${app} is for this Bot could not be loaded.` },
      ),
  });
}

/**
 * The pending requests an administrator answers: one app's, or all of them. The counts are always
 * the whole deployment's. `enabled` is false for anybody who is not an administrator, who would be
 * answered 403.
 */
export function appAccessInboxQueryOptions(enabled: boolean, app?: string) {
  return queryOptions({
    queryKey: appAccessKeys.inbox(app),
    queryFn: async (): Promise<AppAccessInbox> => {
      const query = app ? `?app=${encodeURIComponent(app)}` : "";
      const response = await client(`/api/plugins/access-requests${query}`, {
        fallback: "Access requests could not be loaded.",
      });
      return response.json();
    },
    enabled,
  });
}