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.

10.5 KB
Raw Blame
import { createHash } from "node:crypto";
import { HeadlessToolSuspension } from "@openbot/toolkit/headless-tools";
import { eq } from "drizzle-orm";
import { PERSON_QUESTION_WAITING } from "../approvals/question-resume";
import type { ApprovalService } from "../approvals/service";
import { currentApprovalContext } from "../approvals/types";
import {
  type AuditInitiator,
  type AuditStore,
  PERSON_INITIATOR,
} from "../audit";
import { groupSourceForRun } from "../channels/group";
import type { ChannelStore } from "../channels/routes";
import type { DeploymentConfig } from "../config";
import type { Database } from "../db/client";
import { channelMemberships } from "../db/schema";
import type { DeliveryScope } from "../delivery/types";
import type { PeopleStore } from "../people/store";
import type { PluginStore } from "../plugins/store";
import { REFUSAL_MARKER } from "../plugins/tools";
import { createPrivateShareCheck } from "../proactive/private-share";
import { createWorkQueue } from "../work/queue";
import { type RunAssertion, readRunAssertion } from "./callback-token";
import type { HandoffDesk } from "./handoff";
import {
  authoriseCoordinationRun,
  createCoordinationTools,
  readCoordinationHandoffClaim,
} from "./handoff-tool";
import type { AgentProfileStore } from "./profile-store";
import type { AgentActor } from "./profile-types";

/**
 * Bots coordinating with each other and with people: handing work on, asking a person a question,
 * and the per-run tools a Bot is given for both.
 *
 * Moved out of index.ts verbatim. `notify` is taken as a function because index.ts assigns delivery
 * after this is created: a question reads it when it is routed, never when this is built.
 */
export function wireCoordination(deps: {
  handoffDesk: HandoffDesk;
  config: DeploymentConfig;
  approvalService: ApprovalService;
  agentProfileStore: AgentProfileStore;
  actorFor: (ownerUserId: string) => Promise<AgentActor>;
  channelSourceForRun: (
    run: RunAssertion,
  ) => Promise<{ channelId: string; botId: string } | null>;
  database: Database;
  pluginStore: PluginStore;
  bootAuditStore: AuditStore;
  peopleStore: PeopleStore;
  sourceForCoordinationRun: (
    run: RunAssertion,
  ) => Promise<{ channelId: string; botId: string } | null>;
  channelStore: ChannelStore;
  notify: (
    scope: DeliveryScope,
    input: {
      id: string;
      text: string;
      kind: "question";
      requestId: string;
    },
  ) => Promise<void>;
}) {
  const {
    handoffDesk,
    config,
    approvalService,
    agentProfileStore,
    actorFor,
    channelSourceForRun,
    database,
    pluginStore,
    bootAuditStore,
    peopleStore,
    sourceForCoordinationRun,
    channelStore,
  } = deps;
  const personQuestions = createWorkQueue(database);
  const coordination = createCoordinationTools({
    desk: handoffDesk,
    caps: config.handoff,
    approvalGate: approvalService.gate,
    privateShare: {
      check: createPrivateShareCheck({ approvals: approvalService.store }),
      // Resolved the way the desk resolves it: an id wins, then a single visible name. Null for the
      // owner's own Bot or a deployment Bot, since nobody else reads that work.
      audienceFor: async (from, target) => {
        const roster = await agentProfileStore.list(
          await actorFor(from.actorId),
        );
        const wanted = target.trim().toLowerCase();
        const found =
          roster.find((candidate) => candidate.id.toLowerCase() === wanted) ??
          roster.find(
            (candidate) =>
              !candidate.hidden &&
              candidate.deletedAt === null &&
              candidate.name.toLowerCase() === wanted,
          );
        if (!found?.ownerUserId || found.ownerUserId === from.actorId)
          return null;
        return {
          kind: "handoff",
          id: found.ownerUserId,
          recipientUserIds: [found.ownerUserId],
          label: found.name,
        };
      },
      // A question from a conversation other people are in reaches them too, so it is held like a
      // handoff to another person. Only the owner reading it is the ordinary, unheld case.
      questionAudience: async (from) => {
        const channel = await channelSourceForRun(from);
        const group = channel ? null : await groupSourceForRun(database, from);
        const source = channel ?? group;
        if (!source) return null;
        const members = (
          await database
            .select({ userId: channelMemberships.userId })
            .from(channelMemberships)
            .where(eq(channelMemberships.channelId, source.channelId))
        ).map((row) => row.userId);
        if (members.every((userId) => userId === from.actorId)) return null;
        return {
          audience: {
            kind: group ? "group" : "channel",
            id: source.channelId,
            recipientUserIds: members,
          },
          // A channel thread is the conversation itself; a group Bot's own thread also holds context
          // only its owner has seen.
          origin: channel
            ? { kind: "shared_conversation", sharedWithUserIds: members }
            : { kind: "private_conversation" },
        };
      },
    },
    botsReachableFrom: (botId) => pluginStore.botsReachableFrom(botId),
    auditStore: bootAuditStore,
    authoriseRun: (run) =>
      authoriseCoordinationRun(run, {
        canUseBot: async (scope) => {
          const person = await peopleStore.find(scope.actorId);
          if (!person || person.revoked) return false;
          return (
            (await agentProfileStore.get(
              await actorFor(scope.actorId),
              scope.botId,
            )) !== null
          );
        },
        sourceThread: sourceForCoordinationRun,
        delegationFor: (claim) => readCoordinationHandoffClaim(database, claim),
      }),
    route: async (question) => {
      const source = await sourceForCoordinationRun(question);
      if (!source)
        return {
          refusal: "That question could not reach its source conversation.",
        };
      const key = createHash("sha256")
        .update(
          JSON.stringify([
            question.actorId,
            question.botId,
            question.runId,
            question.question,
          ]),
        )
        .digest("hex");
      const queued = await personQuestions.offer({
        kind: "person.question",
        key,
        payload: {
          ...question,
          sourceBotId: source.botId,
          channelId: source.channelId,
          mode: "completed_question",
          toolName: "ask_person",
          args: {
            question: question.question,
            ...(question.why ? { why: question.why } : {}),
          },
        },
      });
      if (queued === "refused")
        return { refusal: "The question could not be saved for its person." };
      await channelStore.recordActivity(
        await actorFor(question.actorId),
        source.channelId,
        {
          text: `A question needs your answer: ${question.question}`,
          agentId: source.botId,
          at: new Date(),
        },
        { id: `question:${key}` },
      );
      if (question.threadId) {
        // A person reads this in Slack or on their phone, where "general-assistant" is an id, not a name.
        const botName =
          (
            await agentProfileStore
              .get(await actorFor(question.actorId), question.botId)
              .catch(() => null)
          )?.name ?? question.botId;
        await deps.notify(
          {
            ownerUserId: question.actorId,
            channelId: source.channelId,
            agentId: source.botId,
            threadId: question.threadId,
          },
          {
            id: key,
            text: `${botName} asks: ${question.question}`,
            kind: "question",
            requestId: key,
          },
        );
      }
      return {
        reached:
          "the person in the source conversation; the question is saved awaiting their reply",
      };
    },
  });
  const coordinationForActor =
    (
      actorId: string,
      initiator: AuditInitiator = PERSON_INITIATOR,
      baseDepth = 0,
    ) =>
    async (botId: string, input: import("@ag-ui/client").RunAgentInput) => {
      const assertion = readRunAssertion(
        input.forwardedProps?.openbotRun,
        config.keyEncryptionKey,
      );
      if (
        assertion &&
        (assertion.botId !== botId || assertion.actorId !== actorId)
      )
        throw new Error("The run assertion does not match this Bot and owner.");
      const run: RunAssertion = assertion?.handoff
        ? assertion
        : {
            botId,
            actorId,
            runId: input.runId,
            threadId: input.threadId,
            depth: assertion?.depth ?? baseDepth,
            initiator: assertion?.initiator ?? initiator,
          };
      const tools = await coordination.toolsForRun(run);
      return tools.map((tool) => ({
        ...tool,
        execute: async (args: unknown) => {
          if (!args || typeof args !== "object" || Array.isArray(args))
            return `${REFUSAL_MARKER} Tool arguments must be an object.`;
          const result = await coordination.call({
            name: tool.name,
            args: args as Record<string, unknown>,
            run,
          });
          if (!result)
            throw new Error("A coordination tool was not dispatched.");
          /*
           * A responsibility's question pauses its run, the way an approval does.
           *
           * Left running, the run ended "succeeded" the moment the question was saved, and the answer
           * came back to a run that was already over: the Bot read it, and then the store refused its
           * progress because it was not from the responsibility's current run, so the goal stayed
           * open for ever. Suspended, the run waits, and the answer resumes that same run as this
           * tool's result, with the right to record progress and finish.
           */
          const snapshot = currentApprovalContext();
          if (
            tool.name === "ask_person" &&
            run.initiator?.kind === "responsibility" &&
            snapshot &&
            !result.text.startsWith(REFUSAL_MARKER)
          )
            throw new HeadlessToolSuspension(
              "This responsibility is waiting for the person's answer.",
              {
                kind: PERSON_QUESTION_WAITING,
                continuation: snapshot,
              },
            );
          return result.text;
        },
      }));
    };
  return { coordination, coordinationForActor };
}