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.

28.1 KB
Raw Blame
import { connectAppRefusal } from "@openbot/shared/connect-prompt";
import { and, eq } from "drizzle-orm";
import { currentApprovalContext } from "../../approvals/types";
import { type AuditInitiator, recordAuditEvent } from "../../audit";
import {
  evaluateActionPolicy,
  type PolicyContext,
  policyInitiator,
} from "../../computer/policy";
import { withoutStatement } from "../../db/query-failure";
import {
  brokeredConnections,
  mcpTools,
  pluginGrants,
  vendorNameOf,
} from "../../db/schema";
import { classifyTool, tokenHeaderFor } from "../catalogue";
import { VERSION_ARG } from "../composio";
import { inspectToolArguments } from "../content-governance";
import { shareTargetOf } from "../share-target";
import type { AccountMode } from "../shared-accounts";
import { transportFor } from "../transport";
import type { StoreContext } from "./context";
import {
  effectiveUrl,
  type PluginDecision,
  type PluginKind,
  PluginRefusedError,
  reachedAsFor,
  toolNameFor,
  UNATTRIBUTED_ACTOR,
  withoutEmptyOptionals,
} from "./model";

/** Deciding whether a Bot may call a tool, and calling it. */
export function callMethods(context: StoreContext) {
  const {
    options,
    database,
    auditStore,
    injectedVendor,
    connectionTokenFor,
    requireServer,
    brokerProvider,
  } = context;
  return {
    /**
     * May this Bot use this plugin?
     *
     * The single question every caller asks, so there is one place the answer is decided and one
     * place to audit it. A missing row is a refusal, not an oversight.
     */
    async decide(
      kind: PluginKind,
      ref: string,
      agentId: string,
    ): Promise<PluginDecision> {
      const [row] = await database
        .select()
        .from(pluginGrants)
        .where(
          and(
            eq(pluginGrants.kind, kind),
            eq(pluginGrants.ref, ref),
            eq(pluginGrants.agentId, agentId),
          ),
        )
        .limit(1);

      if (!row) {
        return {
          allowed: false,
          reason:
            kind === "mcp"
              ? `This Bot has not been given the tool ${ref}.`
              : `This Bot has not been given the skill ${ref}.`,
        };
      }
      return { allowed: true };
    },

    /**
     * Call a tool on somebody else's server, on a Bot's behalf.
     *
     * Decide, record, then act, which is the order the computer gateway uses and for the same
     * reason: a call that was permitted and then failed is exactly what an investigation needs to
     * see, and a trail written only on success cannot show it. The grant is checked first because a
     * tool this Bot was never given should not reach the policy engine, the vault or the network.
     */
    async callTool(input: {
      ref: string;
      args: Record<string, unknown>;
      botId: string;
      actorId: string;
      initiator?: AuditInitiator;
      /**
       * Whose connected account the call goes out on, when that is not the asker's: a Team Bot
       * reaching its owner's account (team-bots/team-bots.ts). Every gate is still the asker's.
       */
      credentialActorId?: string;
    }): Promise<{ text: string; isError: boolean }> {
      const [serverId, ...rest] = input.ref.split("/");
      const toolName = rest.join("/");
      if (!serverId || !toolName) {
        throw new PluginRefusedError(`${input.ref} is not a tool.`, null);
      }

      /*
       * Who the trail says made this call, which is not what the call is made AS.
       *
       * `input.actorId` stays the value every gate is decided on, and the empty string must go on
       * matching no grant and no connection anywhere. This is only what the row says: a run nobody
       * could be attributed to is `unattributed` rather than blank, on the criterion at
       * {@link DEPLOYMENT_ACTOR}, and never `deployment` — a run this deployment could not put a
       * name to is not the deployment having acted.
       */
      const auditActor = input.actorId || UNATTRIBUTED_ACTOR;

      const decision = await this.decide("mcp", input.ref, input.botId);
      if (!decision.allowed) {
        await recordAuditEvent(auditStore, {
          eventType: "mcp.call_rejected",
          targetType: "mcp_tool",
          targetId: input.ref,
          ...(input.initiator ? { initiator: input.initiator } : {}),
          payload: {
            actor: auditActor,
            bot: input.botId,
            server: serverId,
            tool: toolName,
            refusal: "not_granted",
            reason: decision.reason,
          },
        });
        throw new PluginRefusedError(decision.reason, null);
      }

      const { row, entry, access, app } = await requireServer(serverId);

      const advertised = await database
        .select({
          name: mcpTools.name,
          vendorName: vendorNameOf(),
          inputSchema: mcpTools.inputSchema,
          effect: mcpTools.effect,
          destructive: mcpTools.destructive,
          version: mcpTools.version,
        })
        .from(mcpTools)
        .where(
          and(eq(mcpTools.serverId, serverId), eq(mcpTools.name, toolName)),
        )
        .limit(1);

      const effect = classifyTool(
        entry,
        toolName,
        advertised.length > 0,
        advertised[0]?.effect,
      );

      const args = withoutEmptyOptionals(
        input.args,
        advertised[0]?.inputSchema as Record<string, unknown> | undefined,
      );

      /*
       * The version this action was listed at, handed to the transport that needs one.
       *
       * Under a reserved key rather than as a parameter on the shared signature, because that
       * signature is MCP's and three other transports implement it. The Composio transport strips
       * the key before anything reaches the vendor, and asserts that it did.
       *
       * A `__version` in the model's own arguments is not an argument: it is this key, and no
       * vendor publishes it. So it is stripped unconditionally, whatever its value, and that strip
       * is the whole protection. The recorded version is then merged into arguments that provably
       * cannot carry the key, which makes both spread orders identical: the merge order has no
       * reachable failure mode. Do not read the strip as belt-and-braces on top of an ordering
       * guarantee — the ordering is the redundant half, and removing the strip is what would let a
       * model choose which revision of an action runs.
       *
       * Absent when the app has not been refreshed since the column existed, and because the key
       * was stripped there is then no version at all for the transport to read, which is what makes
       * its refusal hold rather than guessing — a guessed version is a call against an action's
       * other behaviour.
       */
      const { [VERSION_ARG]: _dropped, ...modelArgs } = args;
      const vendorArgs = advertised[0]?.version
        ? { ...modelArgs, [VERSION_ARG]: advertised[0].version }
        : modelArgs;

      /**
       * The same policy the computer actions are judged by, asked about a tool call.
       *
       * Every field is present, including the ones a tool call has no use for, and that is load
       * bearing rather than tidy. This engine treats an expression it cannot evaluate as a match,
       * which is correct for a browser action on an element the server could not resolve. Applied to
       * a tool call it is a disaster: the boundary this product ships in `.env.example` denies
       * `contains(element.name, "submit") || key == "Enter"`, and with `element` and `key` absent
       * that rule is unevaluable, so it would match, so every deployment using the shipped preset
       * would refuse every MCP call for a reason mentioning a submit button.
       *
       * Neutral values instead. Empty strings match no substring, no key and no extension, so a rule
       * written about the browser evaluates to false against a tool call, which is the honest answer:
       * a tool call did not click anything. A rule meant to catch tool calls says so, with `mcp` or
       * with `intent`.
       */
      const context: PolicyContext = {
        tool: { name: toolNameFor(input.ref) },
        bot: { id: input.botId },
        actor: { id: input.actorId },
        page: { url: "", host: "" },
        element: { ref: "", role: "", name: "", type: "" },
        key: "",
        file: { path: "", name: "", extension: "" },
        // Empty, like the browser fields above: an MCP call runs no shell command, but a
        // `deny: contains(command, "rm -rf")` names `command`, and an unbound identifier throws and
        // fails closed — which would refuse every MCP call once a deployment wrote a rule about its
        // shell. An empty command matches no such rule.
        command: "",
        intent: effect === "write" ? "write_tool" : "read_tool",
        mcp: { server: serverId, tool: toolName, effect },
        /*
         * The real one, and this is the path where it is not neutral. A routine's turn reaches its
         * tools through here, carrying the initiator its run assertion was signed with, so this is
         * where `initiator.kind == "routine"` becomes a rule a deployment can actually write. A
         * chat turn arrives with none and reads as a person.
         */
        initiator: policyInitiator(input.initiator),
      };

      const verdict = evaluateActionPolicy(options.policy(), context);

      /*
       * The parts of the row that are known before the attempt, held rather than written.
       *
       * Everything here is a fact about the decision, and the decision is final at this point. What
       * is NOT yet known is whether the call worked, which is why this is a variable and not a write:
       * the row goes down once, after the outcome exists.
       */
      const decided = {
        actor: auditActor,
        bot: input.botId,
        server: serverId,
        tool: toolName,
        effect,
        /*
         * Whose credential this call goes out with.
         *
         * Without it the trail cannot answer "who did this run reach as", which is the whole question
         * a per-person connector raises — two rows for the same tool and the same Bot can legitimately
         * have seen entirely different documents, and nothing else in the row says why.
         */
        reachedAs: reachedAsFor(
          access,
          input.credentialActorId ?? input.actorId,
        ),
        decision: {
          allowed: verdict.allowed,
          mode: verdict.mode,
          rule: verdict.matched,
          source: verdict.source,
          carriedOut: verdict.forward,
        },
      };

      /*
       * A refusal is written on the POLICY's answer, not on whether the call was then let through.
       *
       * This deployment declining is the whole event, and it is recorded before the throw so that a
       * refusal cannot be lost by the caller's error handling.
       *
       * In `dry-run` the policy still refuses and the mode forwards anyway, which is the whole point
       * of the mode: `evaluateActionPolicy` returns `allowed: false` with `forward: true` so a rule
       * can be tried against live traffic before it starts refusing anybody. Writing this row on
       * `forward` therefore recorded nothing at all on this surface for exactly the traffic an
       * operator switched dry-run on to measure — the browser gateway keys its row on
       * `decision.allowed` and does record it — so `Blocked` on the audit page, and every
       * `eventType=mcp.call_rejected` query behind it, answered "this rule would refuse none of your
       * tool calls" about calls it would refuse. The rule then looked inert, and enforcing it
       * started refusing Bots with no warning in the trail.
       *
       * `decision.carriedOut` is what tells the two rows apart: false is a call this deployment
       * stopped, true is one dry-run recorded and let past. The outcome row below is unchanged, so a
       * forwarded call still says separately whether the vendor answered.
       */
      if (!verdict.allowed) {
        await recordAuditEvent(auditStore, {
          eventType: "mcp.call_rejected",
          targetType: "mcp_tool",
          targetId: input.ref,
          ...(input.initiator ? { initiator: input.initiator } : {}),
          payload: decided,
        });
      }
      if (!verdict.forward) {
        throw new PluginRefusedError(verdict.reason, verdict.matched);
      }

      /**
       * Structural policy answers whether this Bot may call this tool. Content inspection answers
       * whether the arguments would carry a credential out of the deployment. It runs after policy
       * and before credentials are read or a vendor is contacted, and its result contains paths and
       * categories only: never the values it refused.
       *
       * IT IS ASKED ABOUT WHAT WOULD BE SENT, WHICH IS `vendorArgs` AND NOT `args`.
       *
       * CRITERION. The object this inspection judges is the object handed to the transport below,
       * identically — not a version of it taken before the reserved key was stripped and the
       * recorded one merged in.
       *
       * REASON. It was asked about `args`, so the gate and the call were about two different
       * objects, and they came apart in both directions. Whatever is merged in below the strip left
       * this deployment WITHOUT HAVING BEEN LOOKED AT, which is not a boundary at all — it is a
       * boundary around a neighbouring value. And the reserved key, which is stripped
       * unconditionally and provably reaches no vendor, was still judged: a model that put anything
       * credential-shaped under `__version` had its granted call refused and its person told the
       * arguments carry credential material, over material that was never going anywhere and a
       * refusal no rule of this deployment's asked for.
       */
      const contentDecision = inspectToolArguments(vendorArgs);
      if (!contentDecision.safe) {
        await recordAuditEvent(auditStore, {
          eventType: "mcp.call_rejected",
          targetType: "mcp_tool",
          targetId: input.ref,
          ...(input.initiator ? { initiator: input.initiator } : {}),
          payload: {
            ...decided,
            decision: { ...decided.decision, carriedOut: false },
            refusal: "sensitive_tool_arguments",
            contentInspection: {
              reason: contentDecision.reason,
              findings: contentDecision.findings,
            },
          },
        });
        throw new PluginRefusedError(
          contentDecision.reason === "sensitive_content"
            ? "The tool call was refused because its arguments contain a password or key."
            : "The tool call was refused because its arguments could not be inspected safely.",
          null,
        );
      }

      /*
       * A write that sends content to other people asks the owner first, whatever their general
       * approvals switch says. Pending throws the check's own wait, which a headless turn and the
       * open chat both turn into a paused tool call; denied is a refusal like any other.
       */
      const share =
        effect === "write" && options.privateShareCheck
          ? shareTargetOf(serverId, toolName, vendorArgs)
          : null;
      if (share && options.privateShareCheck) {
        const shareVerdict = await options.privateShareCheck({
          ownerUserId: input.actorId,
          botId: input.botId,
          audience: share.audience,
          content: share.content,
          origin: { kind: "unknown" },
        });
        if (shareVerdict.status !== "allowed") {
          await recordAuditEvent(auditStore, {
            eventType: "mcp.call_rejected",
            targetType: "mcp_tool",
            targetId: input.ref,
            ...(input.initiator ? { initiator: input.initiator } : {}),
            payload: {
              ...decided,
              decision: { ...decided.decision, carriedOut: false },
              refusal:
                shareVerdict.status === "pending"
                  ? "private_share_pending"
                  : "private_share_denied",
            },
          });
          // A pending share outside any run that can wait says so and sends nothing.
          if (shareVerdict.status === "pending" && currentApprovalContext())
            throw shareVerdict.suspension;
          throw new PluginRefusedError(shareVerdict.message, null);
        }
      }

      /*
       * A SHARED ACCOUNT ANSWERS TO WHOEVER CAN STEER THE BOT, and that is checked on every call.
       *
       * The grant says this Bot may use the app; it says nothing about who may reach the Bot. A
       * Shared app acts as one team account for everyone, so a Bot opened to more people than an
       * administrator approved would hand that account to all of them. The gate decides that here,
       * at call time, so an audience widened a moment ago is caught on its next call. With no gate
       * wired there is nothing that can answer the question, and the call is refused rather than
       * assumed safe.
       */
      /*
       * DECIDED ON, AND KEYED BY, THE APP'S ANSWERING ROW — never the dialled one. A duplicate row
       * at a Shared app's url saying `personal` must not take the call round this gate, and an
       * approval is a fact about the app, so it is asked for under the app's id whichever row the
       * grant happens to name. `gatedMode` then travels to {@link connectionTokenFor}, which
       * refuses if the account it resolves is not the one this gate was decided about.
       */
      const gatedMode: AccountMode | null =
        access.credential !== "brokered"
          ? null
          : app?.accountMode === "shared"
            ? "shared"
            : "personal";
      if (gatedMode === "shared" && app) {
        const verdict = options.sharedUse
          ? await options.sharedUse({
              botId: input.botId,
              serverId: app.id,
              title: row.title,
              actorId: input.actorId,
              ...(input.initiator ? { initiator: input.initiator } : {}),
            })
          : {
              allowed: false as const,
              message: `${row.title} is shared, and OpenBot can't check who may use it, so it wasn't called.`,
            };
        if (!verdict.allowed) {
          await recordAuditEvent(auditStore, {
            eventType: "mcp.call_rejected",
            targetType: "mcp_tool",
            targetId: input.ref,
            ...(input.initiator ? { initiator: input.initiator } : {}),
            payload: {
              ...decided,
              decision: { ...decided.decision, carriedOut: false },
              refusal: verdict.refusal ?? "shared_audience",
            },
          });
          throw new PluginRefusedError(verdict.message, null);
        }
      }

      /*
       * THE APPROVAL GATE IS ASKED UNDER THE APP'S ID TOO, for a brokered row whose app has an
       * answering row. Rules are written against the app — the Shared default is `${appId}/*`
       * scoped to the app's id — so a write granted through a duplicate row has to be judged as
       * the app's, or it matches no rule and walks past the ask an administrator set. `target`
       * still names the dialled row, which is what the call itself goes to; every other row is
       * asked about exactly as before.
       */
      const gateApp = access.credential === "brokered" ? app : null;
      const approval = await options.approvalGate?.({
        actorId: input.actorId,
        botId: input.botId,
        toolRef: gateApp ? `${gateApp.id}/${toolName}` : input.ref,
        effect,
        scope: gateApp ? gateApp.id : serverId,
        args: vendorArgs,
        target: { serverId, toolName, url: row.url, effect },
        continuation: currentApprovalContext(),
      });
      if (approval && "replay" in approval)
        return approval.replay as { text: string; isError: boolean };

      /*
       * Attempt first, record second.
       *
       * The row now says what HAPPENED rather than what was permitted. It used to be written here,
       * before the two lines below, which meant a call that died at the vendor left `call_succeeded`
       * behind it — and a per-person connector fails at exactly these two lines: no connection for
       * the asker, a refresh token the vendor no longer accepts, an API not enabled for the project.
       * Every one of those was invisible, and worse than invisible, because the trail asserted the
       * opposite.
       *
       * `isError` counts as a failure. A vendor that answers the protocol correctly to say the tool
       * itself failed has not completed the call, and a reader counting successes should not be told
       * it did.
       */
      try {
        const { token, vendorUserId } = await connectionTokenFor(
          row,
          entry,
          input.credentialActorId ?? input.actorId,
          access,
          gatedMode,
        );
        const vendor =
          injectedVendor ?? transportFor(access.transport).callTool;
        const result = await vendor(
          {
            url: effectiveUrl(row, entry),
            token,
            tokenHeader: tokenHeaderFor(entry),
            actorId: vendorUserId ?? input.credentialActorId ?? input.actorId,
            botId: input.botId,
          },
          /*
           * THE NAME THE VENDOR KNOWS, WHICH IS THE ONLY ONE IT WILL ANSWER TO. `toolName` is this
           * deployment's half of the ref and is what the model was offered; Arcade is called by the
           * qualified name its listing gave. They are the same string for every other transport,
           * which is what the fallback records rather than papers over — see
           * {@link mcpTools.vendorName}.
           *
           * FALLING BACK TO `toolName` RATHER THAN REFUSING, because a row this read did not find
           * is not an unknown action: `classifyTool` above is built to decide on an app whose
           * listing predates its catalogue entry, and the call goes on to the vendor to be judged
           * there. The fallback is reached only for an action with no recorded row at all, and for
           * those two names were never distinct.
           */
          advertised[0]?.vendorName ?? toolName,
          vendorArgs,
        );
        await recordAuditEvent(auditStore, {
          eventType: result.isError ? "mcp.call_failed" : "mcp.call_succeeded",
          targetType: "mcp_tool",
          targetId: input.ref,
          ...(input.initiator ? { initiator: input.initiator } : {}),
          /*
           * The vendor's own words, when it is reporting a failure.
           *
           * Only on the failure branch, and this is the whole point of the distinction. A successful
           * result is somebody's data — a file listing, a document — and it has no business in an
           * audit row that an administrator can read. An `isError` result is a message written for
           * whoever operates this deployment, and it is the most useful sentence available: Google
           * refuses the Drive MCP server with "The caller does not have permission", which named the
           * problem after a generic message had already cost a round of probing.
           *
           * Capped, because the failure branch is not a promise about length.
           */
          payload: result.isError
            ? {
                ...decided,
                failure:
                  result.text.slice(0, 400) || "the tool reported an error",
              }
            : decided,
        });
        const answer = { text: result.text, isError: result.isError };
        await approval?.complete(answer);
        /*
         * The one answer that leaves this block without returning: see below the catch. Thrown
         * from in here, the catch would write a second `mcp.call_failed` row about the same call.
         */
        if (!result.accountGone) return answer;
      } catch (error) {
        /*
         * Recorded, then rethrown unchanged. The caller's behaviour is unaffected — what changes is
         * that the failure now exists in the trail, which is where somebody asking "is this connector
         * working" looks. The vendor's own sentence is kept, since for a 403 that is the sentence
         * naming which API is not enabled.
         *
         * Capped like the `isError` branch above, and for the same reason: parts of this sentence
         * came from the vendor, and a failure is not a promise about length.
         */
        await recordAuditEvent(auditStore, {
          eventType: "mcp.call_failed",
          targetType: "mcp_tool",
          targetId: input.ref,
          ...(input.initiator ? { initiator: input.initiator } : {}),
          payload: {
            ...decided,
            /*
             * Asked through {@link withoutStatement}, because not every throw in this block is a
             * vendor's sentence.
             *
             * The vendor's own words are what this field is for and are kept. But every query on
             * the way here throws a `DrizzleQueryError` whose message is our statement and its
             * bound values — credential ids, user ids, server ids — and `audit_events` is read by
             * an operator and exported. A dump in the row that records a failed call is the same
             * disclosure the tool-list replace was fixed for, in the trail rather than on a page.
             */
            failure: (error instanceof Error
              ? withoutStatement(error)
              : String(error)
            ).slice(0, 400),
          },
        });
        throw error;
      }
      /*
       * THE ACCOUNT IS GONE AT THE VENDOR, AND THE PERSON CAN PUT IT BACK FROM WHERE THEY ARE. The
       * only way here: every other answer returned inside the block and every throw left the catch.
       *
       * Recorded above as the failure it is, with the vendor's condition in the trail. Handed on as
       * a refusal carrying an app card rather than as the vendor's error, because nothing on this
       * deployment's rows knows the account is gone — the app reads as ready on every screen — and
       * the card is the one place the person is told, with Reconnect beside it. A Shared app's
       * account is the deployment's, so there the card says an administrator has to reconnect it.
       *
       * AND THE ROW GOES, as it does when a confirm hears the same no from the vendor: the row is
       * only the vendor's last answer, and one that outlived the account would go on reading
       * `ready` on every screen — `show_app_access` telling the model to use the app straight after
       * this card — and would make the connect route refuse a fresh connection until somebody
       * found Disconnect. Deleted, the app reads not connected for the person, or the team account
       * not connected for everybody, which is the truth and the state whose button fixes it. Like
       * the confirm's, the delete files no trail entry: nobody disconnected anything here.
       */
      if (access.credential === "brokered" && access.toolkit)
        await database
          .delete(brokeredConnections)
          .where(
            gatedMode === "shared"
              ? and(
                  eq(brokeredConnections.provider, brokerProvider),
                  eq(brokeredConnections.app, access.toolkit),
                  eq(brokeredConnections.holder, "deployment"),
                )
              : and(
                  eq(brokeredConnections.provider, brokerProvider),
                  eq(brokeredConnections.app, access.toolkit),
                  eq(brokeredConnections.holder, "person"),
                  eq(
                    brokeredConnections.userId,
                    input.credentialActorId ?? input.actorId,
                  ),
                ),
          );
      throw new PluginRefusedError(
        connectAppRefusal({
          serverId: row.id,
          title: row.title,
          message:
            gatedMode === "shared"
              ? `The shared ${row.title} account is no longer connected, so this wasn't done. Ask an admin to reconnect it.`
              : `Your ${row.title} account is no longer connected, so this wasn't done. Reconnect it and ask again.`,
          reason: gatedMode === "shared" ? "shared" : "reconnect",
          at: new Date().toISOString(),
        }),
        null,
      );
    },
  };
}