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.

13.6 KB
Raw Blame
import { and, asc, eq, isNull, or } from "drizzle-orm";
import { recordAuditEvent } from "../../audit";
import {
  agentProfiles,
  agents,
  mcpServers,
  mcpTools,
  pluginGrants,
  skills,
  skillTools,
  vendorNameOf,
} from "../../db/schema";
import type { StoreContext } from "./context";
import { PluginRefusedError, type SkillActor, type SkillRecord } from "./model";

/** Skills, and what the store answers about Bots and servers for the routes and the desk. */
export function skillMethods(context: StoreContext) {
  const { database, auditStore, grantsFor, toolsDeclaredBy, knownToolRefs } =
    context;
  return {
    /**
     * The skills this person may see: the deployment's, plus their own.
     *
     * An administrator sees every skill in the deployment, including other people's, because
     * governing what Bots are told is the job of the surface they are looking at.
     */
    async listSkills(actor?: SkillActor): Promise<SkillRecord[]> {
      const visible =
        !actor || actor.isAdmin
          ? undefined
          : or(isNull(skills.ownerUserId), eq(skills.ownerUserId, actor.id));
      const rows = await database
        .select()
        .from(skills)
        .where(visible)
        .orderBy(asc(skills.title));
      const grants = await grantsFor(
        "skill",
        rows.map((row) => row.slug),
      );
      const declared = await toolsDeclaredBy(rows.map((row) => row.id));
      return rows.map((row) => ({
        id: row.id,
        slug: row.slug,
        ownerUserId: row.ownerUserId,
        title: row.title,
        summary: row.summary,
        instructions: row.instructions,
        origin: row.origin,
        installedBy: row.installedBy,
        grantedTo: grants.get(row.slug) ?? [],
        tools: declared.get(row.id) ?? [],
      }));
    },

    /** Whose a skill is, or `undefined` if there is no such skill. Null owner means the deployment's. */
    async skillOwner(slug: string): Promise<string | null | undefined> {
      const [row] = await database
        .select({ ownerUserId: skills.ownerUserId })
        .from(skills)
        .where(eq(skills.slug, slug))
        .limit(1);
      return row ? row.ownerUserId : undefined;
    },

    /**
     * Whose a Bot is, or `undefined` if there is no such Bot.
     *
     * Read here rather than through the coworker store because the only question this file asks is
     * "may this person put their skill on that Bot", and a whole profile is more than that needs.
     */
    /**
     * Whether this Bot can be granted handing work on, or `undefined` if there is no such Bot.
     *
     * Any Bot that exists can: a built-in Bot runs `message_bot` in this process, and a Bot at its
     * own endpoint calls back for it through the signed tool callback, which reaches the same desk.
     */
    async agentCanHandOn(agentId: string): Promise<boolean | undefined> {
      const [row] = await database
        .select({ id: agents.id })
        .from(agents)
        .innerJoin(agentProfiles, eq(agentProfiles.agentId, agents.id))
        // A deleted Bot is not one anybody may be given, and answering about it at all would say it
        // had existed.
        .where(and(eq(agents.id, agentId), isNull(agentProfiles.deletedAt)))
        .limit(1);
      return row ? true : undefined;
    },

    /**
     * Whether this Bot is one somebody could be handed work by, at all.
     *
     * The TARGET of a bot grant, unlike the grantee, may perfectly well run at its own endpoint —
     * being handed work is not the same as being able to hand it on. What it may not be is absent:
     * `ref` is bare text with no foreign key, so a typo stored happily, `message_bot` was offered,
     * and every hop refused as not-granted. That is the same row-that-cannot-work this check exists
     * to stop, arriving from the other side.
     */
    async agentIsRegistered(agentId: string): Promise<boolean> {
      const [row] = await database
        .select({ id: agents.id })
        .from(agents)
        .innerJoin(agentProfiles, eq(agentProfiles.agentId, agents.id))
        .where(and(eq(agents.id, agentId), isNull(agentProfiles.deletedAt)))
        .limit(1);
      return row !== undefined;
    },

    /**
     * Whether this deployment has an app by this id.
     *
     * The narrowest question a caller can ask about a server, and deliberately not `listServers`,
     * which materialises every tool and every grant in the deployment to answer. One row, one
     * column, one limit — this runs on the grant path, which is a person waiting on a switch.
     *
     * Existence only. Whether the app currently ADVERTISES a given tool is a different question and
     * is not asked here: a grant naming a tool a server has stopped offering is a supported state
     * ({@link GrantOnWithdrawnTool}), held and not offered, because what a vendor advertises today
     * is not what somebody decided yesterday. A grant naming no app at all is not that state.
     */
    async serverExists(serverId: string): Promise<boolean> {
      if (!serverId) return false;
      const [row] = await database
        .select({ id: mcpServers.id })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId))
        .limit(1);
      return row !== undefined;
    },

    /**
     * Whether this server publishes an action named EXACTLY this.
     *
     * One indexed read on `mcp_tools`, and deliberately not `listServers`, which materialises every
     * tool and every grant in the deployment to answer. The comparison is `=` on the stored text and
     * so CASE-SENSITIVE: Arcade names are dotted and case-sensitive and are never normalized, and
     * `Gmail.SendEmail` is not `gmail.sendemail`.
     *
     * ASKED OF `vendor_name`, WHICH IS THE NAME THE QUESTION IS ABOUT. Every caller of this reaches
     * it holding an action out of the per-action authorization flow, and that flow speaks the
     * vendor's spelling from end to end: `grantsFor` lists what Arcade reports, the Authorize button
     * sends that back, the attempt row stores it, `?action=` carries it home and `authorize({
     * action })` is refused by the vendor under any other spelling. Asking `name` — this
     * deployment's own identifier, which for Arcade is the qualified name with its toolkit removed —
     * would make this gate answer false for every action that exists, and `/servers/:id/authorize`
     * would refuse the whole flow with "does not publish an action by that name".
     *
     * The two columns hold the same string for every other transport, so no other provider's gate
     * moves. See {@link mcpTools.vendorName}.
     */
    async serverPublishesAction(
      serverId: string,
      action: string,
    ): Promise<boolean> {
      if (!serverId || !action) return false;
      const [row] = await database
        .select({ name: vendorNameOf() })
        .from(mcpTools)
        .where(and(eq(mcpTools.serverId, serverId), eq(vendorNameOf(), action)))
        .limit(1);
      return row !== undefined;
    },

    async agentOwner(agentId: string): Promise<string | null | undefined> {
      const [row] = await database
        .select({ ownerUserId: agentProfiles.ownerUserId })
        .from(agentProfiles)
        .where(eq(agentProfiles.agentId, agentId))
        .limit(1);
      return row ? row.ownerUserId : undefined;
    },

    async installSkill(input: {
      slug: string;
      title: string;
      summary: string;
      instructions: string;
      origin?: string;
      /** Whose it is. Null writes a skill for the whole deployment, which is an admin's to make. */
      ownerUserId: string | null;
      /**
       * The tools this skill needs, as `<serverId>/<toolName>` refs. Absent leaves whatever was
       * declared before; an empty array clears it, which is how a skill stops asking for anything.
       */
      tools?: string[];
      by: string;
    }): Promise<void> {
      /*
       * Checked before anything is written, so a save is all-or-nothing from the caller's side: a
       * skill is never left saved with half its declarations because the fourth ref was a typo.
       */
      const declared =
        input.tools === undefined
          ? undefined
          : [...new Set(input.tools.map((ref) => ref.trim()).filter(Boolean))];
      if (declared !== undefined && declared.length > 0) {
        const known = await knownToolRefs(declared);
        const unknown = declared.filter((ref) => !known.has(ref));
        if (unknown.length > 0) {
          throw new PluginRefusedError(
            `No tool by that name has been seen here: ${unknown.join(", ")}. A skill names tools as serverId/toolName, and the server has to have been refreshed at least once.`,
            // No policy rule refused this; the name simply matches nothing. `rule` is what an audit
            // reader is shown as the reason, and inventing one here would put a rule in the trail
            // that nobody wrote.
            null,
          );
        }
      }

      await database
        .insert(skills)
        .values({
          id: input.slug,
          slug: input.slug,
          ownerUserId: input.ownerUserId,
          title: input.title,
          summary: input.summary,
          instructions: input.instructions,
          origin: input.origin ?? "yours",
          installedBy: input.by,
        })
        // Editing keeps the owner it already had. Whose a skill is, is not something a re-save
        // should quietly change, and the route has already checked this person may edit it.
        // `installed_by` is left alone too: it records who first installed it, not who last saved.
        .onConflictDoUpdate({
          target: skills.slug,
          set: {
            title: input.title,
            summary: input.summary,
            instructions: input.instructions,
            /*
             * WHERE THE TEXT NOW COMES FROM, WRITTEN BESIDE THE TEXT.
             *
             * CRITERION. A save through here leaves `origin` saying what it says on an insert.
             *
             * REASON. `origin = 'catalogue'` is the condition the package seed (`tenant-package.ts`,
             * `setWhere`) overwrites a skill on at every boot. Leaving it standing after somebody
             * edited a shipped skill here kept the row eligible, so the next boot silently replaced
             * their edit with the package's text — the exact outcome that seed's own comment says
             * it exists to prevent ("rather than the package silently replacing something somebody
             * wrote").
             */
            origin: input.origin ?? "yours",
            updatedAt: new Date(),
          },
        });

      /*
       * Replaced wholesale rather than merged. What a skill needs is a set the author is editing, so
       * a save says what it is now; merging would make removing one a thing with no gesture for it.
       */
      if (declared !== undefined) {
        await database
          .delete(skillTools)
          .where(eq(skillTools.skillId, input.slug));
        if (declared.length > 0) {
          await database.insert(skillTools).values(
            declared.map((ref) => ({
              skillId: input.slug,
              ref,
              declaredBy: input.by,
            })),
          );
        }
      }

      await recordAuditEvent(auditStore, {
        eventType: "configuration.changed",
        targetType: "skill",
        targetId: input.slug,
        payload: {
          actor: input.by,
          change: "skill_installed",
          skill: input.slug,
          // Recorded because it is what the skill will pull into a model's context once selection is
          // built. It changes nothing about what may be called; the grant still decides that.
          ...(declared === undefined ? {} : { declares: declared }),
        },
      });
    },

    async uninstallSkill(slug: string, by: string): Promise<void> {
      await database.transaction(async (transaction) => {
        await transaction
          .delete(pluginGrants)
          .where(
            and(eq(pluginGrants.kind, "skill"), eq(pluginGrants.ref, slug)),
          );
        await transaction.delete(skills).where(eq(skills.slug, slug));
      });
      await recordAuditEvent(auditStore, {
        eventType: "configuration.changed",
        targetType: "skill",
        targetId: slug,
        payload: { actor: by, change: "skill_uninstalled", skill: slug },
      });
    },

    /**
     * The Bots one Bot has been granted, read fresh.
     *
     * NEVER CACHED. Whether one Bot may address another is a decision an administrator can change,
     * and a grant revoked a minute ago has to apply to the next hop rather than after a restart. It
     * is a single indexed read, which is the right price for that.
     */
    /**
     * The Bots this one may hand work to.
     *
     * Whatever the grantee's type. A Bot at its own endpoint is offered `message_bot` as a tool it
     * calls back for, and the call reaches the same handoff desk, grant check and caps as a built-in
     * Bot's (see `createCoordinationTools`). This used to keep only built-in grantees, from before
     * remote Bots could call back for coordination, which left every remote Bot's grant reading as
     * configured while no hop ever happened.
     *
     * The join keeps a grant held by a Bot that no longer exists from counting.
     */
    async botsReachableFrom(agentId: string): Promise<string[]> {
      const rows = await database
        .select({ ref: pluginGrants.ref })
        .from(pluginGrants)
        .innerJoin(agents, eq(agents.id, pluginGrants.agentId))
        .where(
          and(eq(pluginGrants.kind, "bot"), eq(pluginGrants.agentId, agentId)),
        );
      return rows.map((row) => row.ref);
    },
  };
}