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.

5.0 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import type { HandoffDesk, HandoffOutcome } from "../src/agents/handoff";
import {
  HANDED_OVER,
  HANDOFF_TOOL,
  handoffTool,
} from "../src/agents/handoff-tool";

/**
 * What the model is offered, and what it is told when it is refused.
 *
 * A tool a Bot may never successfully use is worse than no tool: the model spends attention on it,
 * calls it, and tells the person it tried and could not, which reads as the deployment being broken
 * rather than as it working correctly.
 */

const FROM = {
  botId: "assistant",
  actorId: "user-1",
  runId: "run-1",
  threadId: "thread-1",
  depth: 0,
};

function deskReturning(outcome: HandoffOutcome): HandoffDesk {
  return { send: async () => outcome };
}

const ALLOWED: HandoffOutcome = {
  ok: true,
  to: "researcher",
  toName: "Researcher",
};

describe("the handoff tool", () => {
  test("is offered to a Bot that has somebody to ask", () => {
    const tool = handoffTool({
      desk: deskReturning(ALLOWED),
      from: FROM,
      hasSomebodyToAsk: true,
      maxDepth: 1,
      maxPerRun: 3,
    });

    expect(tool?.name).toBe(HANDOFF_TOOL);
  });

  test("is not offered to a Bot nobody granted", () => {
    expect(
      handoffTool({
        desk: deskReturning(ALLOWED),
        from: FROM,
        hasSomebodyToAsk: false,
        maxDepth: 1,
        maxPerRun: 3,
      }),
    ).toBe(null);
  });

  test("is not offered where the deployment has switched handoff off", () => {
    expect(
      handoffTool({
        desk: deskReturning(ALLOWED),
        from: FROM,
        hasSomebodyToAsk: true,
        maxDepth: 0,
        maxPerRun: 3,
      }),
    ).toBe(null);
  });

  /*
   * The desk would refuse it anyway. This is about what the model is shown: one at the cap reaches
   * for the tool, is told no, and often reports that failure to the person.
   */
  test("is not offered to a run already at the cap", () => {
    expect(
      handoffTool({
        desk: deskReturning(ALLOWED),
        from: { ...FROM, depth: 1 },
        hasSomebodyToAsk: true,
        maxDepth: 1,
      }),
    ).toBe(null);
  });

  test("tells the model not to answer on the other Bot's behalf", async () => {
    const tool = handoffTool({
      desk: deskReturning(ALLOWED),
      from: FROM,
      hasSomebodyToAsk: true,
      maxDepth: 1,
      maxPerRun: 3,
    });

    const said = await tool?.execute({
      bot: "Researcher",
      task: "find the outage window",
    });

    expect(said).toContain("Researcher");
    expect(said).toContain("do not answer on its behalf");
  });

  /* A throw would end the run with nothing said, which reads as the Bot ignoring the person. */
  test("hands a refusal back as something the Bot can say", async () => {
    const tool = handoffTool({
      desk: deskReturning({
        ok: false,
        refusal: "You have not been given that Bot.",
      }),
      from: FROM,
      hasSomebodyToAsk: true,
      maxDepth: 1,
    });

    await expect(tool?.execute({ bot: "payroll", task: "t" })).resolves.toBe(
      "You have not been given that Bot.",
    );
  });

  test("a call missing the task is answered rather than thrown", async () => {
    const tool = handoffTool({
      desk: deskReturning(ALLOWED),
      from: FROM,
      hasSomebodyToAsk: true,
      maxDepth: 1,
      maxPerRun: 3,
    });

    await expect(tool?.execute({ bot: "researcher" })).resolves.toContain(
      "say what you are asking it to do",
    );
  });
});

/**
 * The other zero.
 *
 * A run allowed to go no Bots deep and a run allowed to address no Bots are the same deployment
 * decision from two directions, and only one of them was closing the door. With a fan-out cap of
 * zero the tool was offered, every call was refused, and the model told the person it had tried and
 * failed — which reads as the deployment being broken rather than as it being switched off.
 */
describe("a deployment that allows no hops at all", () => {
  test("offers nothing when the fan-out cap is zero", () => {
    expect(
      handoffTool({
        desk: deskReturning(ALLOWED),
        from: FROM,
        hasSomebodyToAsk: true,
        maxDepth: 1,
        maxPerRun: 0,
      }),
    ).toBeNull();
  });
});

/**
 * The sentence and the marker, held together.
 *
 * The transcript decides whether to draw a hop or a boundary by reading the first words of this
 * result. With one declaration the two sides cannot disagree about the PHRASE; what they can still
 * disagree about is whether the sentence actually starts with it, which is what shipped once and
 * drew every accepted hop as Blocked.
 */
describe("what an accepted hop answers with", () => {
  test("starts with the marker the transcript matches on", async () => {
    const tool = handoffTool({
      desk: deskReturning(ALLOWED),
      from: FROM,
      hasSomebodyToAsk: true,
      maxDepth: 1,
      maxPerRun: 3,
    });

    const said = await tool?.execute({ bot: "researcher", task: "find it" });

    expect(typeof said).toBe("string");
    expect(said as string).toStartWith(HANDED_OVER);
  });
});