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.

21.0 KB
Raw Blame
import type { DrawnComponent } from "@openbot/toolkit/run-turn";
import { resolveUpdateRoute, type UpdateRoute } from "../agents/lifecycle";
import type { WorkItem, WorkQueue } from "../work/queue";
import type { ExpoPushTransport } from "./push";
import type { DeliveryStore } from "./store";
import {
  type ChatTransport,
  type DeliveryBinding,
  DeliveryProviderError,
  DeliveryRefusedError,
  type DeliveryScope,
  type TextTransport,
} from "./types";
/** What a paired chat turn produced besides its reply, surfaced in that same turn. */
export type InlineTurnExtras = {
  approvals: string[];
  questions: { id: string; text: string }[];
};
export type ConverseResult =
  | { kind: "unbound" }
  | { kind: "duplicate"; binding: DeliveryBinding }
  | {
      kind: "replied" | "waiting";
      binding: DeliveryBinding;
      inboxId: string;
      replyText: string;
      /** Display components the turn drew, for a chat surface that can draw them natively. */
      components?: DrawnComponent[];
      extras: InlineTurnExtras;
      waiting?: { kind: string; requestId?: string; approvalId?: string };
    }
  | {
      kind: "failed";
      binding: DeliveryBinding;
      inboxId: string;
      message: string;
    };
/** Twilio error 21610: the recipient has opted out, so Twilio refuses the send. */
const TWILIO_UNSUBSCRIBED = "21610";
export type DeliveryWorkKind =
  | "delivery.inbound"
  | "delivery.outbound"
  | "delivery.push-receipt";
export const DELIVERY_WORK_KINDS: DeliveryWorkKind[] = [
  "delivery.inbound",
  "delivery.outbound",
  "delivery.push-receipt",
];
type RouterStore = Pick<
  DeliveryStore,
  | "findBinding"
  | "binding"
  | "bindingsFor"
  | "devices"
  | "device"
  | "removeDevice"
  | "offerInbox"
  | "inbox"
  | "setInbox"
  | "offerOutbox"
  | "outbox"
  | "startOutbox"
  | "setOutbox"
  | "offerReceipt"
  | "recordInbox"
  | "setSmsOptOut"
  | "botIdentity"
>;
export function createDeliveryRouter(deps: {
  store: RouterStore;
  queue: Pick<WorkQueue, "claim" | "renew" | "finish" | "release">;
  owner: string;
  authoriseScope(scope: DeliveryScope): Promise<boolean>;
  runTurn(
    input: DeliveryScope & { runId: string; text: string; signal: AbortSignal },
  ): Promise<{
    replyText: string;
    components?: DrawnComponent[];
    waiting?: boolean;
  }>;
  providers: {
    /** Slack and Teams both reach people through the OpenTag pairing's proactive delivery. */
    slack?: TextTransport;
    teams?: TextTransport;
    sms?: TextTransport;
    push?: ExpoPushTransport;
  };
  /** The person's routing by kind; defaults to the lifecycle lane's `resolveUpdateRoute`. */
  routeFor?(input: {
    ownerUserId: string;
    agentId: string;
    kind: "reply" | "question" | "approval";
  }): Promise<UpdateRoute>;
  /** Unused since Slack events feed `ingestSlackEvent` from the pairing route; kept for assembly. */
  notifyEvent?(event: {
    ownerUserId: string;
    source: "slack";
    externalId: string;
    type: string;
    payload: Record<string, unknown>;
  }): Promise<unknown>;
  audit?(event: {
    ownerUserId: string;
    channelId: string;
    id: string;
    kind: string;
    state: string;
  }): Promise<void>;
}) {
  const leaseMs = 60_000;
  /**
   * Bindings with a paired chat turn open in this process. An approval or question raised during
   * that turn is shown in the turn itself (an OpenTag card, or text), so it is collected here rather
   * than also sent as a second, proactive message to the same person.
   */
  const inline = new Map<string, InlineTurnExtras>();
  async function notify(
    scope: DeliveryScope,
    input: {
      id: string;
      text: string;
      kind: "reply" | "question" | "approval";
      requestId?: string | null;
    },
    includeBindings = true,
  ) {
    if (!(await deps.authoriseScope(scope)))
      throw new DeliveryRefusedError("Conversation access has been revoked.");
    // Progress/decision/question routing and the per-Bot notification preference. Fails open.
    const route = await (deps.routeFor ?? resolveUpdateRoute)({
      ownerUserId: scope.ownerUserId,
      agentId: scope.agentId,
      kind: input.kind,
    });
    if (includeBindings)
      for (const binding of await deps.store.bindingsFor(scope)) {
        const open = inline.get(binding.id);
        if (open && input.kind === "approval" && input.requestId) {
          open.approvals.push(input.requestId);
          continue;
        }
        if (open && input.kind === "question") {
          open.questions.push({
            id: input.requestId ?? input.id,
            text: input.text,
          });
          continue;
        }
        // Teams is a chat surface like Slack; routing names chat transports as `slack` until the
        // lifecycle lane lists `teams` separately.
        if (
          !route.allows(
            binding.transport === "teams" ? "slack" : binding.transport,
          )
        )
          continue;
        await deps.store.offerOutbox({
          ...scope,
          dedupeKey: `${input.kind}:${input.id}:binding:${binding.id}`,
          bindingId: binding.id,
          deviceId: null,
          transport: binding.transport,
          text: input.text,
          kind: input.kind,
          requestId: input.requestId ?? null,
        });
      }
    if (route.allows("push"))
      for (const device of await deps.store.devices(scope.ownerUserId))
        await deps.store.offerOutbox({
          ...scope,
          dedupeKey: `${input.kind}:${input.id}:device:${device.id}`,
          bindingId: null,
          deviceId: device.id,
          transport: "push",
          text: input.text,
          kind: input.kind,
          requestId: input.requestId ?? null,
        });
  }
  async function receive(input: {
    source: "sms";
    realm: string;
    identity: string;
    address?: string;
    externalId: string;
    text: string;
    echo?: boolean;
  }) {
    if (input.echo) return { queued: false };
    const binding = await deps.store.findBinding(
      input.source,
      input.realm,
      input.identity,
      input.address,
    );
    if (!binding || !(await deps.authoriseScope(binding)))
      return { queued: false };
    // Opted out by STOP: their texts start no turns until they send START.
    if (binding.optedOutAt) return { queued: false };
    const result = await deps.store.offerInbox({
      ownerUserId: binding.ownerUserId,
      channelId: binding.channelId,
      agentId: binding.agentId,
      threadId: binding.threadId,
      bindingId: binding.id,
      source: input.source,
      realm: input.realm,
      externalId: input.externalId,
      text: input.text,
    });
    // The downstream event engine deduplicates independently: a provider retry can recover an
    // interrupted event insertion without re-running the conversational turn.
    return result;
  }
  /**
   * One paired Slack/Teams message, run now and answered in the same AG-UI stream.
   *
   * The same canonical turn as every other delivery (`runTurn`: the owner's selected Bot, in the
   * bound Intelligence thread, with learning, governance, approvals and audit), recorded in the
   * inbox for dedupe and visibility but not queued, since the caller is waiting for the answer.
   */
  async function converse(input: {
    transport: ChatTransport;
    realm: string;
    identity: string;
    externalId: string;
    text: string;
    signal: AbortSignal;
  }): Promise<ConverseResult> {
    const binding = await deps.store.findBinding(
      input.transport,
      input.realm,
      input.identity,
    );
    if (!binding || !(await deps.authoriseScope(binding)))
      return { kind: "unbound" };
    const scope = {
      ownerUserId: binding.ownerUserId,
      channelId: binding.channelId,
      agentId: binding.agentId,
      threadId: binding.threadId,
    };
    const row = await deps.store.recordInbox({
      ...scope,
      bindingId: binding.id,
      source: input.transport,
      realm: input.realm,
      externalId: input.externalId,
      text: input.text,
    });
    if (!row) return { kind: "duplicate", binding };
    // Slack responsibilities are fed by the pairing route through `ingestSlackEvent`, once per
    // event, so the turn itself does not also emit one.
    const extras: InlineTurnExtras = { approvals: [], questions: [] };
    inline.set(binding.id, extras);
    try {
      const result = await deps.runTurn({
        ...scope,
        runId: row.id,
        text: input.text,
        signal: input.signal,
      });
      await deps.store.setInbox(row.id, "sent");
      await deps.audit?.({
        ...scope,
        id: row.id,
        kind: "inbound",
        state: "sent",
      });
      return {
        kind: extras.approvals.length || result.waiting ? "waiting" : "replied",
        binding,
        inboxId: row.id,
        replyText: result.replyText,
        ...(result.components?.length ? { components: result.components } : {}),
        extras,
      };
    } catch (error) {
      // The governed turn stopped for a person: a durable approval or hand-off is now pending.
      if (
        error instanceof Error &&
        error.name === "HeadlessToolSuspension" &&
        "waiting" in error &&
        error.waiting &&
        typeof error.waiting === "object"
      ) {
        const waiting = error.waiting as {
          kind: string;
          requestId?: string;
          approvalId?: string;
        };
        const pending = waiting.approvalId ?? waiting.requestId;
        if (
          waiting.kind === "approval" &&
          pending &&
          !extras.approvals.includes(pending)
        )
          extras.approvals.push(pending);
        await deps.store.setInbox(
          row.id,
          "accepted",
          "Waiting for a person's decision.",
        );
        return {
          kind: "waiting",
          binding,
          inboxId: row.id,
          replyText: "",
          extras,
          waiting,
        };
      }
      const message =
        error instanceof DeliveryRefusedError
          ? error.message
          : "The agent turn failed. Inspect the conversation before retrying.";
      await deps.store.setInbox(row.id, "failed", message);
      await deps.audit?.({
        ...scope,
        id: row.id,
        kind: "inbound",
        state: "failed",
      });
      return { kind: "failed", binding, inboxId: row.id, message };
    } finally {
      if (inline.get(binding.id) === extras) inline.delete(binding.id);
    }
  }
  async function deliver(
    item: WorkItem,
    signal: AbortSignal,
    owns: () => Promise<boolean>,
  ) {
    if (!(await owns())) return;
    if (item.kind === "delivery.inbound") {
      const row = await deps.store.inbox(item.key);
      if (
        !row ||
        row.state === "sent" ||
        row.state === "failed" ||
        row.state === "unknown"
      )
        return;
      if (row.state === "running") {
        await deps.store.setInbox(
          row.id,
          "unknown",
          "Previous agent turn stopped after execution began; inspect conversation before retrying.",
        );
        return;
      }
      if (!(await deps.authoriseScope(row))) {
        await deps.store.setInbox(
          row.id,
          "failed",
          "Conversation access has been revoked.",
        );
        return;
      }
      if (row.bindingId) {
        const binding = await deps.store.binding(row.bindingId);
        if (
          !binding?.enabled ||
          binding.ownerUserId !== row.ownerUserId ||
          binding.channelId !== row.channelId ||
          binding.agentId !== row.agentId ||
          binding.threadId !== row.threadId
        ) {
          await deps.store.setInbox(
            row.id,
            "failed",
            "The source connection changed or was disconnected.",
          );
          return;
        }
      }
      await deps.store.setInbox(row.id, "running");
      try {
        const result = await deps.runTurn({
          ownerUserId: row.ownerUserId,
          channelId: row.channelId,
          agentId: row.agentId,
          threadId: row.threadId,
          runId: row.id,
          text: row.text,
          signal,
        });
        if (!(await owns())) return;
        if (result.replyText)
          await notify(row, {
            id: row.id,
            text: result.replyText,
            kind: "reply",
          });
        await deps.store.setInbox(row.id, "sent");
        await deps.audit?.({
          ownerUserId: row.ownerUserId,
          channelId: row.channelId,
          id: row.id,
          kind: "inbound",
          state: "sent",
        });
      } catch (error) {
        if (!(await owns())) return;
        await deps.store.setInbox(
          row.id,
          "failed",
          error instanceof DeliveryRefusedError
            ? error.message
            : "The agent turn failed. Inspect the conversation before retrying.",
        );
        throw error;
      }
      return;
    }
    const current = await deps.store.outbox(item.key);
    if (!current) return;
    if (item.kind === "delivery.push-receipt") {
      if (
        current.transport !== "push" ||
        current.state !== "accepted" ||
        !current.providerId ||
        !deps.providers.push
      )
        return;
      const receipt = await deps.providers.push.receipt(current.providerId);
      if (!(await owns())) return;
      if (receipt.status === "pending") {
        await deps.store.setOutbox(
          current.id,
          "failed",
          "Expo did not provide a receipt after the receipt window.",
        );
        return;
      }
      await deps.store.setOutbox(
        current.id,
        receipt.status,
        receipt.error ?? null,
      );
      if (receipt.revokeDevice && current.deviceId)
        await deps.store.removeDevice(current.ownerUserId, current.deviceId);
      return;
    }
    if (current.state === "running") {
      await deps.store.setOutbox(
        current.id,
        "unknown",
        "Previous delivery stopped after sending began; inspect provider history before retrying.",
      );
      return;
    }
    if (current.state !== "queued") return;
    if (!(await deps.authoriseScope(current))) {
      await deps.store.setOutbox(
        current.id,
        "failed",
        "Conversation access has been revoked.",
      );
      return;
    }
    const row = await deps.store.startOutbox(current.id);
    if (!row || !(await owns())) return;
    try {
      let result: { id: string; status: "queued" | "sent" | "accepted" };
      if (row.transport === "push") {
        const device = row.deviceId
          ? await deps.store.device(row.deviceId)
          : null;
        if (
          !device?.enabled ||
          device.ownerUserId !== row.ownerUserId ||
          !deps.providers.push
        )
          throw new DeliveryRefusedError("Push device unavailable.");
        result = await deps.providers.push.send({
          token: device.token,
          title: "OpenBot",
          body: row.text,
          channelId: row.channelId,
          kind: row.kind,
          requestId: row.requestId,
        });
      } else {
        const binding = row.bindingId
          ? await deps.store.binding(row.bindingId)
          : null;
        if (
          !binding?.enabled ||
          binding.ownerUserId !== row.ownerUserId ||
          binding.channelId !== row.channelId ||
          binding.agentId !== row.agentId ||
          binding.threadId !== row.threadId
        )
          throw new DeliveryRefusedError(
            "Connection unavailable or moved to another conversation.",
          );
        if (row.transport === "sms" && binding.optedOutAt) {
          if (!(await owns())) return;
          await deps.store.setOutbox(
            row.id,
            "opted_out",
            "The recipient replied STOP. Nothing was sent; they can reply START to resume.",
          );
          return;
        }
        const provider = deps.providers[row.transport];
        if (!provider) throw new DeliveryRefusedError("Provider unavailable.");
        const sender =
          row.transport === "sms"
            ? undefined
            : ((await deps.store.botIdentity(row.agentId)) ?? undefined);
        result = await provider.send({
          id: row.id,
          address: binding.address,
          text: row.text,
          transport: row.transport,
          ...(sender ? { sender } : {}),
        });
      }
      if (!(await owns())) return;
      await deps.store.setOutbox(
        row.id,
        result.status === "queued" ? "accepted" : result.status,
        null,
        result.id,
      );
      if (row.transport === "push") await deps.store.offerReceipt(row.id);
      await deps.audit?.({
        ownerUserId: row.ownerUserId,
        channelId: row.channelId,
        id: row.id,
        kind: row.transport,
        state: result.status,
      });
    } catch (error) {
      if (!(await owns())) return;
      if (
        error instanceof DeliveryProviderError &&
        error.provider === "Twilio" &&
        error.code === TWILIO_UNSUBSCRIBED
      ) {
        const binding = row.bindingId
          ? await deps.store.binding(row.bindingId)
          : null;
        if (binding) await smsOptOut(binding.realm, binding.identity, true);
        await deps.store.setOutbox(
          row.id,
          "opted_out",
          "Twilio reports this number opted out (21610). Nothing was sent.",
        );
        return;
      }
      await deps.store.setOutbox(
        row.id,
        error instanceof DeliveryProviderError && error.uncertain
          ? "unknown"
          : "failed",
        error instanceof DeliveryRefusedError ||
          error instanceof DeliveryProviderError
          ? error.message
          : "Provider delivery failed.",
      );
      if (
        error instanceof DeliveryProviderError &&
        error.code === "DeviceNotRegistered" &&
        row.deviceId
      )
        await deps.store.removeDevice(row.ownerUserId, row.deviceId);
      await deps.audit?.({
        ownerUserId: row.ownerUserId,
        channelId: row.channelId,
        id: row.id,
        kind: row.transport,
        state: "failed",
      });
    }
  }
  /** Twilio STOP/START for one number: record it on every binding for that number, and audit it. */
  async function smsOptOut(realm: string, identity: string, optedOut: boolean) {
    const rows = await deps.store.setSmsOptOut(realm, identity, optedOut);
    for (const row of rows)
      await deps.audit?.({
        ownerUserId: row.ownerUserId,
        channelId: row.channelId,
        id: row.id,
        kind: "sms_opt_out",
        state: optedOut ? "opted_out" : "opted_in",
      });
    return rows.length;
  }
  return {
    receive,
    converse,
    notify,
    smsOptOut,
    async receiveNative(
      scope: DeliveryScope,
      text: string,
      externalId: string,
    ) {
      if (!(await deps.authoriseScope(scope)))
        throw new DeliveryRefusedError("Conversation unavailable.");
      return deps.store.offerInbox({
        ...scope,
        bindingId: null,
        source: "native",
        realm: scope.ownerUserId,
        externalId,
        text,
      });
    },
    async sweep(kind: DeliveryWorkKind) {
      for (const item of await deps.queue.claim({
        kind,
        owner: deps.owner,
        leaseMs,
        limit: 1,
        maxAttempts: 5,
      })) {
        const controller = new AbortController();
        let lost = false;
        let stopped = false;
        let timer: ReturnType<typeof setTimeout> | undefined;
        let heartbeat: Promise<void> = Promise.resolve();
        const owns = async () => {
          if (lost) return false;
          const held = await deps.queue.renew({
            kind,
            key: item.key,
            owner: deps.owner,
            leaseMs,
          });
          if (!held) {
            lost = true;
            controller.abort();
          }
          return held;
        };
        const schedule = () => {
          timer = setTimeout(() => {
            heartbeat = (async () => {
              try {
                if ((await owns()) && !stopped) schedule();
              } catch {
                console.error(
                  JSON.stringify({
                    type: "delivery-lease-renewal-failed",
                    kind,
                    id: item.key,
                  }),
                );
                lost = true;
                controller.abort();
              }
            })();
          }, leaseMs / 3);
          timer.unref?.();
        };
        schedule();
        try {
          await deliver(item, controller.signal, owns);
          if (!lost)
            await deps.queue.finish({ kind, key: item.key, owner: deps.owner });
        } catch (error) {
          if (!lost)
            await deps.queue.release({
              kind,
              key: item.key,
              owner: deps.owner,
              delayMs: 60_000,
              reason:
                error instanceof DeliveryProviderError
                  ? error.message
                  : "Delivery processing failed.",
            });
          throw error;
        } finally {
          stopped = true;
          if (timer) clearTimeout(timer);
          await heartbeat;
        }
      }
    },
  };
}
export type DeliveryRouter = ReturnType<typeof createDeliveryRouter>;