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.
import { describe, expect, test } from "bun:test";
import {
mintRunAssertion,
type RunAssertion,
} from "../src/agents/callback-token";
import type { HandoffWork } from "../src/agents/handoff-runner";
import {
authoriseCoordinationRun,
createCoordinationTools,
} from "../src/agents/handoff-tool";
import { createApp, type DeploymentToolCaller } from "../src/app";
import type { AuditStore } from "../src/audit";
import { loadConfig } from "../src/config";
import { testEnvironment } from "./support/environment";
const KEY = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
const TOKEN = "remote-coordination-test-token";
const RUN: RunAssertion = {
botId: "remote-researcher",
actorId: "person-1",
threadId: "source-thread",
runId: "delivery-run",
depth: 1,
initiator: { kind: "routine", id: "routine-1" },
};
function callbackApp(caller: DeploymentToolCaller) {
const parameters: Parameters<typeof createApp> = [
loadConfig(
testEnvironment({ AGENT_TOOL_TOKEN: TOKEN, KEY_ENCRYPTION_KEY: KEY }),
),
];
parameters[28] = caller;
return createApp(...parameters);
}
describe("remote coordination on the signed tool callback", () => {
test("carries the entire signed run instead of caller supplied scope", async () => {
const captured: Parameters<DeploymentToolCaller>[0][] = [];
const app = callbackApp(async (input) => {
captured.push(input);
return { text: "queued", isError: false };
});
const response = await app.request("/api/agent-tools/call", {
method: "POST",
headers: {
"content-type": "application/json",
"x-openbot-agent-token": TOKEN,
},
body: JSON.stringify({
name: "message_bot",
args: { bot: "knowledge", task: "Find the incident" },
botId: "another-bot",
actorId: "another-person",
threadId: "another-thread",
depth: 0,
initiator: { kind: "person" },
run: mintRunAssertion(DELEGATED, KEY),
}),
});
expect(response.status).toBe(200);
expect(captured).toHaveLength(1);
expect(captured[0]).toMatchObject({
name: "message_bot",
botId: RUN.botId,
actorId: RUN.actorId,
initiator: RUN.initiator,
run: DELEGATED,
});
});
test.each([
["an unknown token", "unknown-token", mintRunAssertion(RUN, KEY)],
["an expired run", TOKEN, mintRunAssertion(RUN, KEY, 0)],
["a forged run", TOKEN, mintRunAssertion(RUN, "another-key")],
])("refuses %s before dispatch", async (_label, presented, run) => {
let dispatched = false;
const app = callbackApp(async () => {
dispatched = true;
return { text: "queued", isError: false };
});
const response = await app.request("/api/agent-tools/call", {
method: "POST",
headers: {
"content-type": "application/json",
"x-openbot-agent-token": presented,
},
body: JSON.stringify({
name: "ask_person",
args: { question: "Which team?" },
run,
}),
});
expect(response.status).toBe(401);
expect(dispatched).toBe(false);
});
});
const WORK: HandoffWork = {
fromBotId: "source-bot",
toBotId: RUN.botId,
actorId: RUN.actorId,
threadId: RUN.threadId!,
runId: "original-run",
depth: 1,
initiator: RUN.initiator,
task: "Investigate the incident",
};
const DELEGATED: RunAssertion = {
...RUN,
handoff: { key: "hop-key", owner: "pod-1" },
};
function authority(
over: {
canUseBot?: boolean;
thread?: { botId: string } | null;
work?: HandoffWork;
owner?: string;
active?: boolean;
} = {},
) {
return {
canUseBot: async () => over.canUseBot ?? true,
sourceThread: async () =>
over.thread === undefined ? { botId: "source-bot" } : over.thread,
delegationFor: async () => ({
work: over.work ?? WORK,
owner: over.owner ?? "pod-1",
active: over.active ?? true,
}),
};
}
describe("coordination run authority", () => {
test("a signed delivery keeps its source thread and current lease owner", async () => {
expect(await authoriseCoordinationRun(DELEGATED, authority())).toBe(true);
expect(
await authoriseCoordinationRun(
{ ...RUN, depth: 0, botId: "source-bot" },
authority(),
),
).toBe(true);
});
test.each([
["missing delegation", RUN, authority()],
["another lease owner", DELEGATED, authority({ owner: "pod-2" })],
["an expired lease", DELEGATED, authority({ active: false })],
[
"another source thread",
{ ...DELEGATED, threadId: "unrelated-thread" },
authority(),
],
["another actor", { ...DELEGATED, actorId: "another-person" }, authority()],
["another target", { ...DELEGATED, botId: "another-bot" }, authority()],
["another depth", { ...DELEGATED, depth: 2 }, authority()],
[
"another initiator",
{ ...DELEGATED, initiator: { kind: "person" } },
authority(),
],
["lost source membership", DELEGATED, authority({ thread: null })],
["lost Bot access", DELEGATED, authority({ canUseBot: false })],
["wrong direct Bot", { ...RUN, depth: 0 }, authority()],
])("refuses %s", async (_label, run, dependencies) => {
expect(
await authoriseCoordinationRun(run as RunAssertion, dependencies),
).toBe(false);
});
});
describe("the common coordination tools", () => {
function tools(
options: {
granted?: boolean;
authorised?: boolean;
authoriseRun?: (run: RunAssertion) => Promise<boolean>;
depth?: number;
} = {},
) {
const sent: RunAssertion[] = [];
const questions: {
actorId: string;
botId: string;
threadId?: string;
runId: string;
question: string;
}[] = [];
const audit: Parameters<AuditStore["insert"]>[0][] = [];
const coordinator = createCoordinationTools({
desk: {
send: async ({ from }) => {
sent.push(from);
if ((from.depth ?? 0) >= 2)
return { ok: false, refusal: "At the depth cap." };
if (options.granted === false)
return { ok: false, refusal: "The grant was revoked." };
return { ok: true, to: "knowledge", toName: "Knowledge" };
},
},
caps: { maxDepth: 2, maxPerRun: 1 },
botsReachableFrom: async () =>
options.granted === false ? [] : ["knowledge"],
route: async (question) => {
questions.push(question);
return { reached: "the source conversation's person" };
},
auditStore: {
insert: async (event) => {
audit.push(event);
},
},
authoriseRun:
options.authoriseRun ?? (async () => options.authorised ?? true),
});
return { coordinator, sent, questions, audit };
}
test("offers both schemas for remote runs and keeps ask_person at the handoff cap", async () => {
const { coordinator } = tools();
const offered = await coordinator.toolsForRun(DELEGATED);
expect(offered.map((tool) => tool.name)).toEqual([
"message_bot",
"ask_person",
]);
expect(
offered[0]?.parameters.safeParse({
bot: "Knowledge",
task: "Investigate",
}).success,
).toBe(true);
expect(
(await coordinator.toolsForRun({ ...DELEGATED, depth: 2 })).map(
(tool) => tool.name,
),
).toEqual(["ask_person"]);
});
test("executes a handoff with the signed context and reports a revoked grant as an error", async () => {
const { coordinator, sent } = tools({ granted: false });
const result = await coordinator.call({
name: "message_bot",
args: { bot: "Knowledge", task: "Investigate" },
run: DELEGATED,
});
expect(result?.isError).toBe(true);
expect(result?.text).toContain("The grant was revoked");
expect(sent).toEqual([DELEGATED]);
});
test("asks the canonical source person and preserves the routine initiator in audit", async () => {
const { coordinator, questions, audit } = tools();
const result = await coordinator.call({
name: "ask_person",
args: { question: "Which team owns this?" },
run: DELEGATED,
});
expect(result?.isError).toBe(false);
expect(questions[0]).toMatchObject({
actorId: RUN.actorId,
botId: RUN.botId,
threadId: "source-thread",
runId: RUN.runId,
});
expect(audit[0]).toMatchObject({
eventType: "agent.escalated",
initiator: RUN.initiator,
});
});
test("an unrelated source thread is refused before either tool executes and is audited", async () => {
const { coordinator, sent, questions, audit } = tools({
authorised: false,
});
for (const name of ["message_bot", "ask_person"]) {
expect(
(await coordinator.call({ name, args: {}, run: DELEGATED }))?.isError,
).toBe(true);
}
expect(sent).toEqual([]);
expect(questions).toEqual([]);
expect(audit).toHaveLength(2);
expect(audit[0]?.initiator).toEqual(RUN.initiator);
});
test("offers no coordination tool to a run that may not coordinate", async () => {
const { coordinator } = tools({ authorised: false });
expect(await coordinator.toolsForRun(DELEGATED)).toEqual([]);
});
// A group peer turn is relayed at depth 1 with no handoff claim, the shape of RUN.
test.each([
["a leased delivery", DELEGATED, ["message_bot", "ask_person"]],
[
"a direct run",
{ ...RUN, depth: 0, botId: "source-bot" },
["message_bot", "ask_person"],
],
["a group peer turn", RUN, []],
])(
"every tool offered to %s is callable by it",
async (_label, run, names) => {
const { coordinator } = tools({
authoriseRun: (asserted) =>
authoriseCoordinationRun(asserted, authority()),
});
const offered = await coordinator.toolsForRun(run);
expect(offered.map((tool) => tool.name)).toEqual(names);
for (const tool of offered) {
const result = await coordinator.call({
name: tool.name,
args: {},
run,
});
expect(result?.text).not.toContain("no longer has permission");
}
},
);
});