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.1 KB
Raw Blame
/**
 * Asking a person, as a first-class answer.
 *
 * A Bot that needs judgement has three things it can do: guess, ask another Bot, or ask the person.
 * Only the first two were ever offered, and a model with no named way to stop will take one of them:
 * it guesses confidently, or it hands the work sideways to a Bot that cannot settle it either and
 * spends a run finding that out. The caps in `handoff.ts` then become the only exit from a chain
 * that should never have started.
 *
 * So this is a tool, sitting beside the one for handing work to another Bot and competing with it
 * for the same decision. It ends the Bot's turn by putting the question to whoever this deployment
 * says stands behind the work, and it says who that was, so the Bot can tell the person what it has
 * done rather than falling silent.
 *
 * WHO "A PERSON" IS, IS A SEAM. In this template it is the person in the conversation, which is the
 * only answer a template can give honestly. A company running this has a different one: an on-call
 * rota, a duty desk, a queue somebody works through in the morning. That is a route this deployment
 * hands in, not a channel post written into the tool.
 */

import { PUT_TO } from "@openbot/shared/handoff-markers";
import type { GrantedTool } from "@openbot/toolkit/granted-tool";
import { z } from "zod";
import {
  type AuditInitiator,
  type AuditStore,
  recordAuditEvent,
} from "../audit";
import type { RunAssertion } from "./callback-token";

/** What the model is offered. One name, so a transcript can find every escalation by searching. */
export const ESCALATE_TOOL = "ask_person";

/**
 * Where a question for a person goes.
 *
 * Returns who was reached, in words a Bot can say out loud: "the person in this conversation", "the
 * on-call engineer". It is the sentence the model repeats, so it is written for the person reading
 * the transcript rather than for a log.
 *
 * A route that cannot reach anybody should say so rather than throw. A Bot mid-run with a person
 * waiting gets nothing from an exception: the run ends with nothing said, which reads as the Bot
 * ignoring them.
 */
export type EscalationRoute = (input: {
  actorId: string;
  botId: string;
  threadId?: string;
  runId: string;
  /** Preserved for a durable question routed from an unattended routine or delegated run. */
  initiator?: AuditInitiator;
  question: string;
  why?: string;
}) => Promise<{ reached: string } | { refusal: string }>;

/**
 * The route this template ships with: the person who is already here.
 *
 * It sends nothing anywhere, and that is the whole point. The Bot is in a conversation with the
 * person who asked; the honest thing is for it to put the question to them in its own next sentence,
 * which is a thing it can already do and was not doing. What this adds is that the model now has a
 * named way to choose it, and that the choice is on the record.
 */
export const askTheirOwnPerson: EscalationRoute = async () => ({
  reached: "the person in this conversation",
});

const parameters = z.object({
  question: z
    .string()
    .describe("The question you need a person to answer, in one sentence"),
  why: z
    .string()
    .optional()
    .describe(
      "Why this needs a person rather than you: what you cannot settle on your own",
    ),
});

/**
 * The tool, for any run at all.
 *
 * NOT GATED ON A GRANT, unlike handing work to another Bot. Reaching a second Bot spends a model
 * call, may wake a computer and can fan out; asking the person who is already in the conversation
 * costs nothing and cannot be aimed anywhere they cannot see. Making it a grant would mean a
 * deployment could switch off the safe exit and leave the expensive one, which is backwards.
 */
export function escalationTool(options: {
  /** The run doing the asking, as this deployment signed it. */
  from: RunAssertion;
  route: EscalationRoute;
  auditStore?: AuditStore;
}): GrantedTool {
  const { from, route, auditStore } = options;

  return {
    name: ESCALATE_TOOL,
    ref: `bot/${ESCALATE_TOOL}`,
    description:
      "Put a question to a person when the work needs judgement you do not have: a decision only " +
      "they can make, a fact only they know, permission you do not hold. Prefer this to guessing, " +
      "and prefer it to asking another Bot when no other Bot could settle it either. Say what you " +
      "need and why, then stop and wait for their answer.",
    parameters,
    execute: async (args: unknown) => {
      const parsed = parameters.safeParse(args);
      if (!parsed.success) {
        return "That was not put to anybody: say what you need a person to answer.";
      }

      /*
       * A question field that is present and empty is a call with nothing in it.
       *
       * `z.string()` accepts "" and a run of spaces, so the refusal above — which is the sentence
       * written for exactly this — only ever fired when the field was missing altogether. Spelled
       * the other way it went straight through: the Bot was told its question had been put to
       * somebody, the turn ended on that, and the trail took an `agent.escalated` row with nothing
       * in its question, which is the row an operator counts escalations by. Where a route is a duty
       * desk rather than the person already here, it is a page to somebody with no question on it.
       *
       * `message_bot`, which this competes with for the same decision, refuses a blank task and says
       * so. This is the other half of that, and the trimmed text is what travels, for the same
       * reason a handoff sends the trimmed task: what was recorded should be what was asked.
       */
      const question = parsed.data.question.trim();
      if (!question) {
        return "That was not put to anybody: say what you need a person to answer.";
      }

      /*
       * A route that throws is a route that refused, and the run has to survive it.
       *
       * `handoff.ts` says the rule for both of these tools at the top of its module: every refusal is
       * an answer, not an error, because the asking Bot is mid-run with a person waiting and a thrown
       * error ends the run with nothing said. This tool competes with that one for the same decision
       * and did not follow it — the throw came straight back out of `execute`, which is the failure
       * that reads to the person as the Bot ignoring them, on the tool whose entire job is to stop
       * ignoring them.
       *
       * It looks unreachable and is not. `askTheirOwnPerson` is a pure function that cannot throw, so
       * nothing in this repo or its tests ever takes this path — but the module comment above says
       * WHO "A PERSON" IS, IS A SEAM, and every route a company actually hands in is a duty desk, a
       * rota, a queue: a network call that times out, 502s, or resolves DNS to nothing. The one route
       * that cannot fail is the one that ships, so the guard was missing exactly where the
       * documentation invites a deployment to go.
       *
       * Recorded as `agent.escalation_failed`, which is what the comment below already promises for
       * an escalation that could not be delivered and previously only delivered for a route polite
       * enough to return its refusal.
       */
      /** What the route threw, if it did, for the row and never for the answer. */
      let thrown: string | undefined;
      let outcome: { reached: string } | { refusal: string };
      try {
        outcome = await route({
          actorId: from.actorId,
          botId: from.botId,
          ...(from.threadId ? { threadId: from.threadId } : {}),
          runId: from.runId,
          ...(from.initiator ? { initiator: from.initiator } : {}),
          question,
          ...(parsed.data.why ? { why: parsed.data.why } : {}),
        });
      } catch (error) {
        /*
         * The thrown text goes in the trail and not into the answer.
         *
         * What a route throws is written for whoever operates the rota — a connection reset, a status
         * line, a stack — and the answer here is paraphrased to the person who asked the question.
         * `handoff-runner.ts` keeps the two apart for the same reason; this keeps the whole thing on
         * the row, capped, and gives the Bot a sentence that is true whatever went wrong.
         */
        thrown = (error instanceof Error ? error.message : String(error)).slice(
          0,
          400,
        );
        outcome = {
          refusal:
            "That did not reach anybody: nobody could be asked just now. Say so plainly, answer " +
            "only what you can settle yourself, and do not tell them a person has been asked.",
        };
      }

      /*
       * Recorded either way. An escalation that could not be delivered is the one worth finding
       * later: the Bot stopped, the person was never asked, and without a row nothing says so.
       */
      if (auditStore) {
        await recordAuditEvent(auditStore, {
          eventType:
            "reached" in outcome
              ? "agent.escalated"
              : "agent.escalation_failed",
          targetType: "agent",
          targetId: from.botId,
          ...(from.actorId ? { actorUserId: from.actorId } : {}),
          ...(from.initiator ? { initiator: from.initiator } : {}),
          payload: {
            bot: from.botId,
            run: from.runId,
            question,
            ...(parsed.data.why ? { why: parsed.data.why } : {}),
            ...("reached" in outcome
              ? { reached: outcome.reached }
              : { reason: outcome.refusal }),
            // The route's own words, only when it threw them. `reason` above is the sentence the Bot
            // was given; this is what actually went wrong, which is the pair `store.ts` keeps too.
            ...(thrown ? { failure: thrown } : {}),
          },
        });
      }

      return "reached" in outcome
        ? `${PUT_TO}${outcome.reached}. Ask it in your own words now, plainly, and stop there: do not answer it yourself and do not hand it to another Bot.`
        : outcome.refusal;
    },
  };
}

/** Re-exported so callers of this module do not need to know where it is declared. */
export { PUT_TO };