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.

18.8 KB
Raw Blame
/**
 * A Bot deciding to come back later, on its own: "I will check the build again in an hour."
 *
 * ONE-SHOT AND BOUNDED. A follow-up is one future turn with a stated reason, no sooner than a
 * minute and no later than a week away, and a Bot may hold only a few at once per person and start
 * only so many a day. A Bot that schedules a follow-up from inside a follow-up is still inside the
 * same caps, so it cannot build itself a loop.
 *
 * THE SAME QUEUE AND THE SAME TURN AS A ROUTINE. The follow-up is a `work_items` row of kind
 * `bot.wakeup`, claimed with a lease like every other durable job here, and it runs through the
 * headless turn runner, which is the normal AG-UI path: the Bot's own tools, its governance, its
 * approvals, and the pause guard at the top of every headless turn.
 *
 * Identities come from the run that scheduled it, never from model arguments: the person and the
 * Bot are bound when the tools are built.
 */
import { randomUUID } from "node:crypto";
import type { GrantedTool } from "@openbot/toolkit/granted-tool";
import { HeadlessToolSuspension } from "@openbot/toolkit/headless-tools";
import { and, asc, eq, isNull, sql } from "drizzle-orm";
import { z } from "zod";
import type { AuditInitiator, AuditStore } from "../audit";
import { recordAuditEvent } from "../audit";
import type { AgentChannel } from "../channels/routes";
import type { Database } from "../db/client";
import { workItems } from "../db/schema/work";
import { REFUSAL_MARKER } from "../plugins/tools";
import type { WorkQueue } from "../work/queue";
import { BotPausedError } from "./lifecycle";
import type { AgentActor } from "./profile-types";

export const WAKE_UP_KIND = "bot.wakeup";
export const WAKE_UP_MIN_DELAY_MS = 60_000;
export const WAKE_UP_MAX_DELAY_MS = 7 * 24 * 60 * 60_000;
/** Follow-ups one Bot may have waiting for one person at once. */
export const WAKE_UP_MAX_PENDING = 5;
/** Follow-ups one Bot may schedule for one person in a day, fired or not. */
export const WAKE_UP_MAX_PER_DAY = 20;

export type WakeUpPayload = {
  ownerUserId: string;
  agentId: string;
  reason: string;
  instruction?: string;
  /** Where to wake up. Absent means the person's own conversation with this Bot. */
  channelId?: string;
  dueAt: string;
  scheduledAt: string;
  /** Written when it has run, was cancelled, or was skipped. */
  outcome?: {
    status: "succeeded" | "failed" | "waiting" | "skipped" | "cancelled";
    at: string;
    detail?: string;
  };
};

export type WakeUpRecord = WakeUpPayload & {
  id: string;
  state: "scheduled" | "running" | "done";
};

export class WakeUpRefusedError extends Error {
  override name = "WakeUpRefusedError";
}

const scheduleSchema = z
  .object({
    reason: z.string().trim().min(1).max(500),
    in_minutes: z
      .number()
      .int()
      .min(WAKE_UP_MIN_DELAY_MS / 60_000)
      .max(WAKE_UP_MAX_DELAY_MS / 60_000)
      .optional(),
    at: z.string().datetime({ offset: true }).optional(),
    instruction: z.string().trim().max(2000).optional(),
  })
  .strict()
  .refine(
    (value) => (value.in_minutes === undefined) !== (value.at === undefined),
    {
      message: "Give exactly one of in_minutes or at.",
    },
  );

const keyPrefix = (ownerUserId: string, agentId: string) =>
  `wake:${JSON.stringify([ownerUserId, agentId])}:`;

const owned = (ownerUserId: string, agentId: string) =>
  and(
    eq(workItems.kind, WAKE_UP_KIND),
    sql`${workItems.payload}->>'ownerUserId' = ${ownerUserId}`,
    sql`${workItems.payload}->>'agentId' = ${agentId}`,
  );

function toRecord(row: typeof workItems.$inferSelect): WakeUpRecord {
  const payload = row.payload as WakeUpPayload;
  const running =
    !row.finishedAt &&
    row.claimedBy !== null &&
    row.leaseUntil !== null &&
    row.leaseUntil.getTime() > Date.now();
  return {
    ...payload,
    id: row.key,
    state: row.finishedAt ? "done" : running ? "running" : "scheduled",
  };
}

export type WakeUpStore = ReturnType<typeof createWakeUpStore>;

export function createWakeUpStore(
  database: Database,
  options: { auditStore?: AuditStore; now?: () => Date } = {},
) {
  const now = options.now ?? (() => new Date());

  async function audit(
    eventType: "bot.follow_up_scheduled" | "bot.follow_up_cancelled",
    payload: WakeUpPayload & { id: string },
    initiator?: AuditInitiator,
  ) {
    if (!options.auditStore) return;
    try {
      await recordAuditEvent(options.auditStore, {
        eventType,
        targetType: "agent",
        targetId: payload.agentId,
        actorUserId: payload.ownerUserId,
        ...(initiator ? { initiator } : {}),
        payload: {
          bot: payload.agentId,
          followUp: payload.id,
          reason: payload.reason.slice(0, 500),
          dueAt: payload.dueAt,
        },
      });
    } catch (error) {
      console.error(
        JSON.stringify({
          type: "follow-up-audit-write-failed",
          eventType,
          error: String(error),
        }),
      );
    }
  }

  return {
    /**
     * Schedule one follow-up, inside the caps, as one serialised step per person and Bot so a
     * model asking five times at once cannot pass a cap of five with six.
     */
    async schedule(input: {
      ownerUserId: string;
      agentId: string;
      reason: string;
      dueAt: Date;
      instruction?: string;
      channelId?: string;
      initiator?: AuditInitiator;
    }): Promise<WakeUpRecord> {
      const delay = input.dueAt.getTime() - now().getTime();
      if (!Number.isFinite(delay) || delay < WAKE_UP_MIN_DELAY_MS - 1_000)
        throw new WakeUpRefusedError(
          "A follow-up has to be at least a minute away.",
        );
      if (delay > WAKE_UP_MAX_DELAY_MS)
        throw new WakeUpRefusedError(
          "A follow-up can be at most seven days away.",
        );
      const id = `${keyPrefix(input.ownerUserId, input.agentId)}${randomUUID()}`;
      const payload: WakeUpPayload = {
        ownerUserId: input.ownerUserId,
        agentId: input.agentId,
        reason: input.reason,
        ...(input.instruction ? { instruction: input.instruction } : {}),
        ...(input.channelId ? { channelId: input.channelId } : {}),
        dueAt: input.dueAt.toISOString(),
        scheduledAt: now().toISOString(),
      };
      await database.transaction(async (transaction) => {
        await transaction.execute(
          sql`select pg_advisory_xact_lock(hashtext(${`${WAKE_UP_KIND}:${input.ownerUserId}:${input.agentId}`}))`,
        );
        const [counts] = await transaction
          .select({
            pending: sql<number>`count(*) filter (where ${workItems.finishedAt} is null)::int`,
            today: sql<number>`count(*) filter (where ${workItems.createdAt} > now() - interval '1 day')::int`,
          })
          .from(workItems)
          .where(owned(input.ownerUserId, input.agentId));
        if ((counts?.pending ?? 0) >= WAKE_UP_MAX_PENDING)
          throw new WakeUpRefusedError(
            `This Bot already has ${WAKE_UP_MAX_PENDING} follow-ups waiting. Cancel one first.`,
          );
        if ((counts?.today ?? 0) >= WAKE_UP_MAX_PER_DAY)
          throw new WakeUpRefusedError(
            `This Bot has scheduled ${WAKE_UP_MAX_PER_DAY} follow-ups today, which is the most it may.`,
          );
        await transaction.insert(workItems).values({
          kind: WAKE_UP_KIND,
          key: id,
          runAt: input.dueAt,
          payload,
        });
      });
      await audit(
        "bot.follow_up_scheduled",
        { ...payload, id },
        input.initiator,
      );
      return { ...payload, id, state: "scheduled" };
    },

    /** This person's follow-ups with this Bot: waiting, running, and the last few that are done. */
    async list(ownerUserId: string, agentId: string): Promise<WakeUpRecord[]> {
      const rows = await database
        .select()
        .from(workItems)
        .where(owned(ownerUserId, agentId))
        .orderBy(asc(workItems.runAt))
        .limit(100);
      return rows.map(toRecord);
    },

    /** Cancel one that has not started. False when it is not theirs, not there, or already over. */
    async cancel(
      ownerUserId: string,
      agentId: string,
      id: string,
      initiator?: AuditInitiator,
    ): Promise<boolean> {
      const [row] = await database
        .select()
        .from(workItems)
        .where(and(owned(ownerUserId, agentId), eq(workItems.key, id)))
        .limit(1);
      if (!row || row.finishedAt) return false;
      const payload = row.payload as WakeUpPayload;
      const cancelled: WakeUpPayload = {
        ...payload,
        outcome: { status: "cancelled", at: now().toISOString() },
      };
      const [updated] = await database
        .update(workItems)
        .set({
          finishedAt: sql`now()`,
          claimedBy: null,
          leaseUntil: null,
          lastError: "Cancelled",
          payload: cancelled,
          updatedAt: sql`now()`,
        })
        .where(
          and(
            owned(ownerUserId, agentId),
            eq(workItems.key, id),
            isNull(workItems.finishedAt),
          ),
        )
        .returning({ key: workItems.key });
      if (!updated) return false;
      await audit("bot.follow_up_cancelled", { ...payload, id }, initiator);
      return true;
    },

    /** Cancel every waiting follow-up for the pair. Used by reset. Returns how many. */
    async cancelAll(ownerUserId: string, agentId: string): Promise<number> {
      const cancelled = await database
        .update(workItems)
        .set({
          finishedAt: sql`now()`,
          claimedBy: null,
          leaseUntil: null,
          lastError: "Cancelled by reset",
          updatedAt: sql`now()`,
        })
        .where(and(owned(ownerUserId, agentId), isNull(workItems.finishedAt)))
        .returning({ key: workItems.key });
      return cancelled.length;
    },

    /** Record how a follow-up ended, on its own row. */
    async settle(id: string, outcome: NonNullable<WakeUpPayload["outcome"]>) {
      await database
        .update(workItems)
        .set({
          payload: sql`${workItems.payload} || ${JSON.stringify({ outcome })}::jsonb`,
          updatedAt: sql`now()`,
        })
        .where(and(eq(workItems.kind, WAKE_UP_KIND), eq(workItems.key, id)));
    },
  };
}

/** The Bot's own tools for this, bound to the person and the Bot of the run that is offered them. */
export function wakeUpTools(options: {
  store: WakeUpStore;
  ownerUserId: string;
  agentId: string;
  initiator?: AuditInitiator;
  now?: () => Date;
}): GrantedTool[] {
  const { store, ownerUserId, agentId, initiator } = options;
  const now = options.now ?? (() => new Date());
  function tool<T>(
    name: string,
    description: string,
    parameters: z.ZodType<T>,
    execute: (value: T) => Promise<unknown>,
  ): GrantedTool {
    return {
      name,
      ref: `lifecycle/${name}`,
      description,
      parameters,
      async execute(args) {
        const value = parameters.safeParse(args);
        if (!value.success)
          return `${REFUSAL_MARKER} ${value.error.issues[0]?.message ?? "Invalid follow-up arguments."}`;
        try {
          return JSON.stringify(await execute(value.data));
        } catch (error) {
          if (error instanceof WakeUpRefusedError)
            return `${REFUSAL_MARKER} ${error.message}`;
          throw error;
        }
      },
    };
  }
  return [
    tool(
      "schedule_follow_up",
      `Wake yourself up later to continue this work without the person asking: once, at one moment between 1 minute and 7 days from now. Give the reason (shown to the person) and either in_minutes or an ISO-8601 time in at. At most ${WAKE_UP_MAX_PENDING} may be waiting at once. Use it when something needs checking again later, not to repeat on a schedule (that is a routine).`,
      scheduleSchema,
      async (value) => {
        const dueAt =
          value.at !== undefined
            ? new Date(value.at)
            : new Date(now().getTime() + (value.in_minutes ?? 0) * 60_000);
        const record = await store.schedule({
          ownerUserId,
          agentId,
          reason: value.reason,
          dueAt,
          ...(value.instruction ? { instruction: value.instruction } : {}),
          ...(initiator ? { initiator } : {}),
        });
        return { scheduled: record.id, dueAt: record.dueAt };
      },
    ),
    tool(
      "list_follow_ups",
      "List the follow-ups you have scheduled for yourself with this person.",
      z.object({}).strict(),
      async () =>
        (await store.list(ownerUserId, agentId))
          .filter((record) => record.state !== "done")
          .map(({ id, reason, dueAt, state }) => ({
            id,
            reason,
            dueAt,
            state,
          })),
    ),
    tool(
      "cancel_follow_up",
      "Cancel a follow-up you scheduled that has not started yet.",
      z.object({ id: z.string().min(1).max(400) }).strict(),
      async ({ id }) => ({
        cancelled: await store.cancel(ownerUserId, agentId, id, initiator),
      }),
    ),
  ];
}

/** The message the Bot wakes up to. The reason is its own words, quoted back to it. */
export function wakeUpInstruction(payload: WakeUpPayload): string {
  const lines = [
    `You scheduled this follow-up for yourself on ${payload.scheduledAt}. Your reason: ${payload.reason}`,
  ];
  if (payload.instruction)
    lines.push(`What you meant to do: ${payload.instruction}`);
  lines.push(
    "Pick it up now. Tell the person what you found or did, in a sentence or two.",
  );
  return lines.join("\n");
}

export type WakeUpTurn = (input: {
  ownerUserId: string;
  routineId: string;
  agentId: string;
  threadId: string;
  instruction: string;
  initiator: AuditInitiator;
}) => Promise<{ replyText: string }>;

/**
 * Run the follow-ups that are due, one claim at a time.
 *
 * NO RETRY. A follow-up whose turn failed is recorded as failed rather than handed out again: the
 * failed turn may already have called a tool, and a Bot waking twice for one reason is the kind of
 * surprise this feature must not produce.
 */
export function createWakeUpRunner(options: {
  queue: Pick<WorkQueue, "claim" | "finish" | "purge">;
  store: WakeUpStore;
  owner: string;
  actorFor: (ownerUserId: string) => Promise<AgentActor>;
  channels: {
    get(actor: AgentActor, channelId: string): Promise<AgentChannel | null>;
    direct(actor: AgentActor, agentId: string): Promise<AgentChannel>;
    recordActivity(
      actor: AgentActor,
      channelId: string,
      activity: { text: string; agentId: string | null; at: Date },
      source?: { id: string },
    ): Promise<void>;
  };
  runTurn: WakeUpTurn;
  /** Tell the person off the web (push, Slack, SMS), subject to their routing. Best effort. */
  notify?: (
    scope: {
      ownerUserId: string;
      channelId: string;
      agentId: string;
      threadId: string;
    },
    input: { id: string; text: string; kind: "reply" },
  ) => Promise<void>;
  leaseMs?: number;
}) {
  const { queue, store, owner, actorFor, channels, runTurn, notify } = options;
  const leaseMs = options.leaseMs ?? 15 * 60_000;
  return {
    async sweep(): Promise<{ ran: string[]; skipped: string[] }> {
      const report = { ran: [] as string[], skipped: [] as string[] };
      const claimed = await queue.claim({
        kind: WAKE_UP_KIND,
        owner,
        leaseMs,
        limit: 1,
        maxAttempts: 1,
      });
      for (const item of claimed) {
        const payload = item.payload as unknown as WakeUpPayload;
        const at = () => new Date().toISOString();
        const done = async (
          outcome: NonNullable<WakeUpPayload["outcome"]>["status"],
          detail?: string,
        ) => {
          await store.settle(item.key, {
            status: outcome,
            at: at(),
            ...(detail ? { detail: detail.slice(0, 500) } : {}),
          });
          await queue.finish({ kind: WAKE_UP_KIND, key: item.key, owner });
        };
        try {
          if (!payload?.ownerUserId || !payload.agentId) {
            await done("skipped", "not a follow-up");
            report.skipped.push(item.key);
            continue;
          }
          const actor = await actorFor(payload.ownerUserId);
          const channel =
            (payload.channelId
              ? await channels.get(actor, payload.channelId)
              : null) ?? (await channels.direct(actor, payload.agentId));
          const initiator: AuditInitiator = {
            kind: "routine",
            id: `follow-up:${item.key}`,
          };
          try {
            const { replyText } = await runTurn({
              ownerUserId: payload.ownerUserId,
              routineId: `follow-up:${item.key}`,
              agentId: payload.agentId,
              threadId: channel.threadId,
              instruction: wakeUpInstruction(payload),
              initiator,
            });
            await channels.recordActivity(
              actor,
              channel.id,
              { text: replyText, agentId: payload.agentId, at: new Date() },
              { id: `follow-up:${item.key}` },
            );
            await done("succeeded");
            report.ran.push(item.key);
            await notify?.(
              {
                ownerUserId: payload.ownerUserId,
                channelId: channel.id,
                agentId: payload.agentId,
                threadId: channel.threadId,
              },
              { id: `follow-up:${item.key}`, text: replyText, kind: "reply" },
            ).catch((error: unknown) =>
              console.warn("Could not notify about a follow-up.", error),
            );
          } catch (error) {
            if (error instanceof BotPausedError) {
              await done("skipped", error.message);
              report.skipped.push(item.key);
            } else if (error instanceof HeadlessToolSuspension) {
              await channels
                .recordActivity(
                  actor,
                  channel.id,
                  {
                    text: error.message,
                    agentId: payload.agentId,
                    at: new Date(),
                  },
                  { id: `follow-up:${item.key}` },
                )
                .catch(() => {});
              await done("waiting", error.message);
              report.ran.push(item.key);
            } else {
              await done(
                "failed",
                error instanceof Error ? error.message : String(error),
              );
              report.skipped.push(item.key);
            }
          }
        } catch (error) {
          // The channel or the person could not be resolved: over, and said on the row.
          await done(
            "failed",
            error instanceof Error ? error.message : String(error),
          ).catch(() => {});
          report.skipped.push(item.key);
        }
      }
      return report;
    },
    /** Drop follow-ups that ended more than a week ago. */
    reap: () =>
      queue.purge({
        kind: WAKE_UP_KIND,
        olderThanMs: 7 * 24 * 60 * 60_000,
        maxAttempts: 1,
      }),
  };
}