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 type { AbstractAgent, BaseEvent, Message } from "@ag-ui/client";
import { LockLapsedError } from "@openbot/toolkit/lease";
import { Observable } from "rxjs";
import { createHandoffDelivery } from "../src/agents/handoff-delivery";
import type { HandoffWork } from "../src/agents/handoff-runner";
import { serverTurnAdmission } from "../src/agents/turn-admission";
/**
* Turning a hop into a turn.
*
* The property that matters is that the addressed Bot joins a conversation rather than answering a
* question in the dark, and that a run which ended in an error is not mistaken for one that answered.
*/
const WORK: HandoffWork = {
fromBotId: "assistant",
toBotId: "researcher",
actorId: "user-1",
threadId: "thread-1",
runId: "run-1",
depth: 1,
task: "find the outage window",
};
const PRIOR: Message[] = [
{ id: "m1", role: "user", content: "we had an outage yesterday" },
{ id: "m2", role: "assistant", content: "I will find out when" },
];
const FINISHED = [{ type: "RUN_FINISHED" }] as unknown as BaseEvent[];
/** Enough of an agent for the delivery to hand a conversation to. */
function stubAgent(): AbstractAgent {
const agent = {
threadId: "",
messages: [] as unknown[],
setMessages(messages: unknown[]) {
agent.messages = messages;
},
};
return agent as unknown as AbstractAgent;
}
function delivery(
events: BaseEvent[],
agent: AbstractAgent | null = stubAgent(),
lockHeld = true,
options: { history?: readonly unknown[]; deadlineMs?: number } = {},
) {
const requests: Array<{
threadId: string;
input: Record<string, unknown>;
persistedInputMessages?: readonly unknown[];
}> = [];
const lockCalls: string[] = [];
const released: string[] = [];
const builtFor: { actorId: string; botId: string; fromBotId: string }[] = [];
return {
requests,
lockCalls,
released,
builtFor,
delivery: createHandoffDelivery({
admission: serverTurnAdmission,
...(options.deadlineMs === undefined
? {}
: { deadlineMs: options.deadlineMs }),
agentFor: async (input) => {
builtFor.push(input);
return agent;
},
history: async () => options.history ?? PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => {
lockCalls.push("acquire");
// The platform's own run id, not the one asked for.
return lockHeld ? { runId: "platform-run" } : null;
},
renew: async () => {
lockCalls.push("renew");
},
release: async (input) => {
lockCalls.push("release");
released.push(input.threadId);
},
},
runner: {
run: (request) => {
requests.push({
threadId: request.threadId,
input: request.input as Record<string, unknown>,
...(request.persistedInputMessages
? { persistedInputMessages: request.persistedInputMessages }
: {}),
});
return new Observable<BaseEvent>((subscriber) => {
for (const event of events) subscriber.next(event);
subscriber.complete();
});
},
},
}),
};
}
describe("turning a hop into a turn", () => {
test("the addressed Bot reads the conversation before the ask", async () => {
const { delivery: deliver, requests } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "assistant has asked you to help",
shown: "Assistant asked Researcher for this on your behalf: find it",
assertion: "signed",
});
const messages = requests[0]?.input.messages as Message[];
// The conversation, then the ask. A Bot handed only the task answers a question whose other half
// was settled three messages ago.
expect(messages.map((m) => m.id).slice(0, 2)).toEqual(["m1", "m2"]);
expect(messages.at(-1)).toMatchObject({
role: "user",
content: "assistant has asked you to help",
});
});
test("the run carries the deployment's signed statement of what it is", async () => {
const { delivery: deliver, requests } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "signed-assertion",
});
expect(requests[0]?.input.forwardedProps).toEqual({
openbotRun: "signed-assertion",
});
// The addressed Bot's own conversation, because a thread has exactly one agent.
expect(requests[0]?.threadId).toBe("scratch-thread");
});
/*
* A run that errored said nothing in the conversation. Treating it as delivered finishes the work
* and leaves the person waiting for an answer that will never come.
*/
test("a run that ended in an error is not a delivery", async () => {
const { delivery: deliver } = delivery([
{ type: "RUN_ERROR", message: "the model refused" },
] as unknown as BaseEvent[]);
await expect(
deliver.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toThrow("the model refused");
});
test("a Bot that cannot be built is worth another go rather than a silent drop", async () => {
const { delivery: deliver } = delivery(FINISHED, null);
await expect(
deliver.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toThrow("researcher");
});
});
/**
* The conversation's run lock.
*
* ONE RUN AT A TIME, and the gateway checks every streamed event against the run the lock names. A
* delivery that skips this is claiming to be a run nobody was told about, so every event is refused
* and the refusal reads like a platform limitation rather than a missing step. It was one.
*/
describe("holding the conversation while a Bot answers", () => {
test("the lock is taken before anything is streamed, and given back after", async () => {
const { delivery: deliver, lockCalls } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
expect(lockCalls[0]).toBe("acquire");
expect(lockCalls.at(-1)).toBe("release");
});
test("the run uses the platform's own run id", async () => {
const { delivery: deliver, requests } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
// The platform's id, not the one asked for: it is what the gateway checks every event against.
expect(requests[0]?.input.runId).toBe("platform-run");
});
/*
* A person mid-question, or the asking Bot still finishing its own sentence, is a wait rather than
* a failure. The hop goes back on the queue and is tried again.
*/
test("a conversation somebody else is running in is waited for, not failed", async () => {
const { delivery: deliver, requests } = delivery(
FINISHED,
stubAgent(),
false,
);
await expect(
deliver.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toThrow("busy");
expect(requests).toEqual([]);
});
/*
* Left held, the conversation is unusable by anybody until it expires: the person cannot ask a
* follow-up and the next hop is refused. One failed delivery would stop the conversation working.
*/
test("the lock is given back even when the run fails", async () => {
const { delivery: deliver, lockCalls } = delivery([
{ type: "RUN_ERROR", message: "the model refused" },
] as unknown as BaseEvent[]);
await expect(
deliver.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toThrow();
expect(lockCalls).toContain("release");
});
});
/**
* Where the turn can run, which the platform decides rather than this code.
*
* An Intelligence thread is owned by exactly one agent. A second Bot answering inside the first
* Bot's conversation is refused however it asks, so its turn runs in a scratch thread of its own
* and the words come home through the relay.
*/
describe("which conversation the turn runs in", () => {
test("a scratch thread of the addressed Bot's own, not the one that asked", async () => {
const { delivery: deliver, requests } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
expect(requests[0]?.threadId).toBe("scratch-thread");
expect(requests[0]?.input.threadId).toBe("scratch-thread");
});
test("but it reads the conversation that asked", async () => {
const { delivery: deliver, requests } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
// Its own conversation is new and empty; reading that would tell it nothing.
const messages = requests[0]?.input.messages as Array<{ id: string }>;
expect(messages.map((m) => m.id).slice(0, 2)).toEqual(["m1", "m2"]);
});
});
/**
* What crosses a hop.
*
* A thread's stored history is what a person is shown, not a prompt: the assistant message that made
* a tool call is not kept, so the result of that call is stored on its own with a `toolCallId`
* matching nothing. The asking Bot's last act is always the call that handed the work on, so every
* hop carried one of these and every delivery hung on it.
*/
describe("the conversation that crosses a hop", () => {
test("the asking Bot's tool traffic is left behind", async () => {
const { delivery: deliver, requests } = delivery(
FINISHED,
undefined,
true,
{
history: [
{ id: "m1", role: "user", content: "ask the researcher" },
// The orphan: a result whose call was never kept.
{
id: "m2",
role: "tool",
toolCallId: "call_1",
content: '"Handed to Researcher."',
},
// A tool call and nothing else, which is the other half of the same pair.
{ id: "m3", role: "assistant", content: "" },
{ id: "m4", role: "assistant", content: "I have asked them." },
],
},
);
await deliver.deliver({
work: WORK,
message: "the ask",
shown: "one line",
assertion: "s",
});
const messages = requests[0]?.input.messages as Message[];
expect(messages.map((message) => message.id)).toEqual([
"m1",
"m4",
`handoff-platform-run`,
]);
});
});
/**
* A hop nobody is watching.
*
* On a person's own run there is somebody who can reload the page. A hop that never finishes holds
* the conversation's lock and its place on the queue for as long as the process lives, and the
* person waits on an answer that is not coming.
*/
describe("a delivery that never finishes", () => {
test("is given up on, and says so", async () => {
const { delivery: deliver, lockCalls } = delivery([], stubAgent(), true, {
deadlineMs: 20,
});
// A run that emits nothing and never completes, which is what a stalled Bot looks like.
const stalled = createHandoffDelivery({
admission: serverTurnAdmission,
deadlineMs: 20,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: async () => {},
release: async () => {
lockCalls.push("release");
},
},
runner: { run: () => new Observable<BaseEvent>(() => {}) },
});
await expect(
stalled.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toThrow("did not finish within");
// Given back, or the conversation stays unusable until the lock expires.
expect(lockCalls).toContain("release");
void deliver;
});
/*
* A renewal that did not arrive is not a lock that was lost. Stopped here, the hop would be retried
* from the start, and a Bot that had already acted would act again.
*/
test("a renewal that merely failed does not stop the hop", async () => {
let renewals = 0;
const hop = createHandoffDelivery({
admission: serverTurnAdmission,
deadlineMs: 5_000,
renewEveryMs: 2,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: () => {
renewals += 1;
return Promise.reject(new TypeError("fetch failed"));
},
release: async () => {},
},
runner: {
run: () =>
new Observable<BaseEvent>((subscriber) => {
const finish = setTimeout(() => {
for (const event of FINISHED) subscriber.next(event);
subscriber.complete();
}, 30);
return () => clearTimeout(finish);
}),
},
});
await hop.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" });
expect(renewals).toBeGreaterThan(0);
});
/*
* A renewal refused as a conflict means somebody else holds the conversation now — on a relay,
* most likely the person, typing in their own channel. The hop stops rather than write its answer
* into their run, gives the lock back, and fails into a retry with the platform's reason.
*/
/*
* Renewals that never answer at all. No error ever arrives to say the lock was lost, so the only
* thing that can stop the hop is the lock's lifetime running out.
*/
test("renewals that never settle stop the hop once the lock's lifetime has passed", async () => {
const stopped: string[] = [];
const released: string[] = [];
const hop = createHandoffDelivery({
admission: serverTurnAdmission,
deadlineMs: 5_000,
renewEveryMs: 2,
lockLifetimeMs: 20,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: () => new Promise(() => {}),
release: async (input) => {
released.push(input.threadId);
},
},
runner: {
// A run that would go on for ever, so only the lapsed lock can end it.
run: () => new Observable<BaseEvent>(() => {}),
stop: async (input) => {
stopped.push(input.runId);
return true;
},
},
});
await expect(
hop.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toBeInstanceOf(LockLapsedError);
expect(stopped).toEqual(["platform-run"]);
expect(released).toEqual(["scratch-thread"]);
});
test("a renewal refused as a conflict stops the hop and gives the lock back", async () => {
const conflict = Object.assign(
new Error("Intelligence platform error 409: THREAD_LOCK_RENEWAL_FAILED"),
{ name: "PlatformRequestError", status: 409 },
);
const stopped: string[] = [];
const released: string[] = [];
const hop = createHandoffDelivery({
admission: serverTurnAdmission,
deadlineMs: 5_000,
renewEveryMs: 2,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: () => Promise.reject(conflict),
release: async (input) => {
released.push(input.threadId);
},
},
runner: {
// A run that would go on for ever, so only the lost lock can end it.
run: () => new Observable<BaseEvent>(() => {}),
stop: async (input) => {
stopped.push(input.runId);
return true;
},
},
});
await expect(
hop.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toBe(conflict);
expect(stopped).toEqual(["platform-run"]);
expect(released).toEqual(["scratch-thread"]);
});
test("the lock is given back on the conversation it was taken on", async () => {
const { delivery: deliver, released } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
// Not `thread-1`, which is the conversation that ASKED and whose lock this run never held.
expect(released).toEqual(["scratch-thread"]);
});
});
/**
* What the conversation keeps.
*
* The person did not send the ask and it is not addressed to them: their conversation with one Bot
* has a message in it because another Bot asked for something. Persisting the whole prompt puts the
* asking conversation's history into a second conversation, and a paragraph of instructions to a
* model into a bubble that looks like something they typed.
*/
describe("what a hop leaves in the transcript", () => {
test("is the one line, not the prompt", async () => {
const { delivery: deliver, requests } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "assistant has asked you to help\n\nTask: ...\nConstraints: ...",
shown: "Assistant asked Researcher for this on your behalf: find it",
assertion: "s",
});
expect(requests[0]?.persistedInputMessages).toEqual([
{
id: "handoff-platform-run",
role: "user",
content: "Assistant asked Researcher for this on your behalf: find it",
},
]);
// The model still gets the whole envelope, and the conversation that asked.
const messages = requests[0]?.input.messages as Message[];
expect(messages.at(-1)).toMatchObject({
content: expect.stringContaining("Task:"),
});
});
});
/**
* Where the conversation has to be put.
*
* `runAgent` takes `runId`, `tools`, `context` and `forwardedProps`. AG-UI keeps the messages and
* the thread on the agent, so a `messages` array passed as a run parameter is ignored in silence:
* the Bot runs, reads nothing, and answers "how can I help?" to a question printed directly above
* its reply. Nothing fails, which is why this is a test rather than a comment.
*/
describe("what the addressed Bot is actually given", () => {
test("the conversation is set on the agent, not only in the run", async () => {
const agent = stubAgent();
const { delivery: deliver } = delivery(FINISHED, agent);
await deliver.deliver({
work: WORK,
message: "the ask",
shown: "one line",
assertion: "s",
});
const given = (agent as unknown as { messages: Message[] }).messages;
expect(given.map((message) => message.id)).toEqual([
"m1",
"m2",
"handoff-platform-run",
]);
expect(given.at(-1)).toMatchObject({ role: "user", content: "the ask" });
// And it runs in its own conversation, which the agent also carries.
expect((agent as unknown as { threadId: string }).threadId).toBe(
"scratch-thread",
);
});
});
/**
* Lighting the asking channel while a hop runs.
*
* A forward hop runs in a scratch thread nobody watches, so it signals the asking channel itself. A
* backwards hop runs in the asking thread, whose lock the runtime already watches, so it must not
* signal again — that would double the indicator on and off.
*/
describe("the working indicator", () => {
function withBusy() {
const busy: Array<{ threadId: string; busy: boolean }> = [];
const deliver = createHandoffDelivery({
admission: serverTurnAdmission,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
setBusy: async (input) => {
busy.push(input);
},
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: async () => {},
release: async () => {},
},
runner: {
run: () =>
new Observable<BaseEvent>((subscriber) => {
for (const event of FINISHED) subscriber.next(event);
subscriber.complete();
}),
},
});
return { busy, deliver };
}
test("a forward hop lights the asking channel, on then off", async () => {
const { busy, deliver } = withBusy();
await deliver.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
// Keyed on the asking thread, not the scratch thread the run happens in.
expect(busy).toEqual([
{ threadId: "thread-1", busy: true },
{ threadId: "thread-1", busy: false },
]);
});
test("a backwards hop leaves the indicator to the runtime lock", async () => {
const { busy, deliver } = withBusy();
await deliver.deliver({
work: { ...WORK, answerIn: "thread-1" },
message: "m",
assertion: "s",
});
expect(busy).toEqual([]);
});
});
/**
* What the Bot said, gathered from the stream.
*
* The runner publishes the turn to the platform rather than back through the observable, and the
* scratch thread it lands in is never shown to anybody: the events going past are the one chance to
* hear the answer, and the resolved value is the only copy the relay — and therefore the person —
* will ever get.
*/
describe("what comes back for the relay", () => {
/** An agent whose run emits the given events through the delivery's own onEvent hook. */
function talkingAgent(
events: Array<{ type: string; delta?: string }>,
): AbstractAgent {
const agent = {
threadId: "",
messages: [] as unknown[],
setMessages(messages: unknown[]) {
agent.messages = messages;
},
runAgent: (
_input: unknown,
config?: { onEvent?: (emitted: unknown) => void },
) => {
for (const event of events) config?.onEvent?.({ event });
return Promise.resolve();
},
};
return agent as unknown as AbstractAgent;
}
/** A runner that drives the agent the way the real one does, then completes. */
function throughTheAgent(agent: AbstractAgent) {
return createHandoffDelivery({
admission: serverTurnAdmission,
agentFor: async () => agent,
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: async () => {},
release: async () => {},
},
runner: {
run: (request) => {
void (
request.agent as unknown as {
runAgent: (input: unknown, config?: unknown) => Promise<void>;
}
).runAgent({}, {});
return new Observable<BaseEvent>((subscriber) => {
for (const event of FINISHED) subscriber.next(event);
subscriber.complete();
});
},
},
});
}
test("the words the Bot said resolve out of the delivery", async () => {
const agent = talkingAgent([
{ type: "TEXT_MESSAGE_START" },
{ type: "TEXT_MESSAGE_CONTENT", delta: "The outage " },
{ type: "TEXT_MESSAGE_CONTENT", delta: "was Tuesday." },
{ type: "TEXT_MESSAGE_END" },
]);
const { answer } = await throughTheAgent(agent).deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
expect(answer).toBe("The outage was Tuesday.");
});
test("a turn that said several things carries all of them", async () => {
const agent = talkingAgent([
{ type: "TEXT_MESSAGE_START" },
{ type: "TEXT_MESSAGE_CONTENT", delta: "Looking now." },
{ type: "TEXT_MESSAGE_END" },
{ type: "TEXT_MESSAGE_START" },
{ type: "TEXT_MESSAGE_CONTENT", delta: "Found it: Tuesday." },
{ type: "TEXT_MESSAGE_END" },
]);
const { answer } = await throughTheAgent(agent).deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
expect(answer).toBe("Looking now.\n\nFound it: Tuesday.");
});
test("a turn that spoke announces itself, where the wiring can find a channel", async () => {
const announced: Array<{
threadId: string;
agentId: string;
text: string;
}> = [];
const agent = talkingAgent([
{ type: "TEXT_MESSAGE_START" },
{ type: "TEXT_MESSAGE_CONTENT", delta: "Tuesday." },
{ type: "TEXT_MESSAGE_END" },
]);
const deliver = createHandoffDelivery({
admission: serverTurnAdmission,
agentFor: async () => agent,
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
announce: async ({ threadId, agentId, text }) => {
announced.push({ threadId, agentId, text });
},
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: async () => {},
release: async () => {},
},
runner: {
run: (request) => {
void (
request.agent as unknown as {
runAgent: (input: unknown, config?: unknown) => Promise<void>;
}
).runAgent({}, {});
return new Observable<BaseEvent>((subscriber) => {
for (const event of FINISHED) subscriber.next(event);
subscriber.complete();
});
},
},
});
// A backwards hop: the relay, landing where the person is watching.
await deliver.deliver({
work: { ...WORK, answerIn: "thread-1" },
message: "m",
assertion: "s",
});
expect(announced).toEqual([
{ threadId: "thread-1", agentId: WORK.toBotId, text: "Tuesday." },
]);
});
test("a turn of nothing but tool calls has nothing to carry", async () => {
const agent = talkingAgent([
{ type: "TOOL_CALL_START" },
{ type: "TOOL_CALL_END" },
]);
const { answer } = await throughTheAgent(agent).deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
expect(answer).toBeNull();
});
});
/**
* A message is not always a string.
*
* AG-UI's user message takes `string | InputContent[]` and the platform types thread content as
* unknown. Nothing here writes an array yet, which is why a `typeof content === "string"` test
* looked complete — and why the day attachments ship, every message carrying one would vanish from
* the conversation handed across a hop with nothing recording it.
*/
describe("a conversation that is not all plain strings", () => {
test("a message made of parts is carried across, not dropped", async () => {
const { delivery: deliver, requests } = delivery(
FINISHED,
undefined,
true,
{
history: [
{
id: "m1",
role: "user",
content: [
{ type: "text", text: "here is the invoice" },
{ type: "image", url: "https://example.test/a.png" },
],
},
{ id: "m2", role: "assistant", content: "I will read it" },
],
},
);
await deliver.deliver({
work: WORK,
message: "the ask",
shown: "one line",
assertion: "s",
});
const messages = requests[0]?.input.messages as Message[];
expect(messages.map((message) => message.id)).toEqual([
"m1",
"m2",
"handoff-platform-run",
]);
});
/*
* Still dropped: a message whose only content is parts this does not understand says nothing, and
* an assistant message with nothing in it is a tool call whose other half was never kept.
*/
test("a message with no text in it at all is still left behind", async () => {
const { delivery: deliver, requests } = delivery(
FINISHED,
undefined,
true,
{
history: [
{ id: "m1", role: "user", content: [{ type: "image", url: "x" }] },
{ id: "m2", role: "assistant", content: [] },
{ id: "m3", role: "user", content: "what does it say?" },
],
},
);
await deliver.deliver({
work: WORK,
message: "the ask",
shown: "one line",
assertion: "s",
});
const messages = requests[0]?.input.messages as Message[];
expect(messages.map((message) => message.id)).toEqual([
"m3",
"handoff-platform-run",
]);
});
});
/*
* The one call that throws on a platform error is the history read, and on a relay the lock is the
* asking conversation itself. Read while holding it, a failed read leaked the lock until its TTL:
* the person could not type for two minutes, and the retry collided with the hop's own hold.
*/
describe("a history read that fails", () => {
test("takes no lock, so nothing is leaked for the retry to collide with", async () => {
const lockCalls: string[] = [];
const deliver = createHandoffDelivery({
admission: serverTurnAdmission,
agentFor: async () => stubAgent(),
history: async () => {
throw new Error("the platform answered 500");
},
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => {
lockCalls.push("acquire");
return { runId: "platform-run" };
},
renew: async () => {
lockCalls.push("renew");
},
release: async () => {
lockCalls.push("release");
},
},
runner: {
run: () =>
new Observable<BaseEvent>((subscriber) => {
subscriber.complete();
}),
},
});
await expect(
deliver.deliver({
work: { ...WORK, answerIn: WORK.threadId },
message: "you asked researcher; it answered",
assertion: "signed",
}),
).rejects.toThrow("the platform answered 500");
expect(lockCalls).toEqual([]);
});
});
describe("what the trail is told started the hop", () => {
test("the addressed Bot is built for the Bot that handed the work on", async () => {
const { delivery: deliver, builtFor } = delivery(FINISHED);
await deliver.deliver({
work: WORK,
message: "assistant has asked you to help",
shown: "Assistant asked Researcher for this on your behalf: find it",
assertion: "signed",
});
expect(builtFor).toEqual([
{ actorId: "user-1", botId: "researcher", fromBotId: "assistant" },
]);
});
});
/**
* A pause reaches a hop that is already running, as it reaches every other turn: on this replica at
* once and from any other through the watcher. Checked only before the hop started, a Bot paused
* mid-hop would keep working until its answer was in.
*/
describe("a hop to a Bot that is paused while it works", () => {
test("stops, gives the lock back and says the Bot is paused", async () => {
const {
BotPausedError,
checkRunningTurnsForTests,
configureBotLifecycle,
resetBotLifecycleForTests,
} = await import("../src/agents/lifecycle");
const pause = { at: null as Date | null };
const query = {
from: () => query,
where: () => query,
limit: async () => [{ pausedAt: pause.at }],
};
configureBotLifecycle({
database: { select: () => query } as unknown as Parameters<
typeof configureBotLifecycle
>[0]["database"],
});
const released: string[] = [];
const stopped: string[] = [];
let started: () => void = () => {};
const running = new Promise<void>((resolve) => {
started = resolve;
});
const hop = createHandoffDelivery({
admission: serverTurnAdmission,
deadlineMs: 5_000,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => ({ runId: "platform-run" }),
renew: async () => {},
release: async (input) => {
released.push(input.threadId);
},
},
runner: {
run: () =>
new Observable<BaseEvent>(() => {
started();
}),
stop: async (input) => {
stopped.push(input.runId);
return true;
},
},
});
try {
const delivered = hop.deliver({
work: WORK,
message: "m",
shown: "s",
assertion: "s",
});
await running;
pause.at = new Date();
await checkRunningTurnsForTests();
await expect(delivered).rejects.toBeInstanceOf(BotPausedError);
expect(stopped).toEqual(["platform-run"]);
expect(released).toEqual(["scratch-thread"]);
} finally {
resetBotLifecycleForTests();
}
});
/*
* Admitted before the lock, as every headless turn is. A hop used to take the conversation's lock
* first and only then find the Bot paused, so a paused Bot's relay held the person's own channel
* for a moment on every retry.
*/
test("a Bot paused before the hop never touches the lock and never runs", async () => {
const { BotPausedError, configureBotLifecycle, resetBotLifecycleForTests } =
await import("../src/agents/lifecycle");
const query = {
from: () => query,
where: () => query,
limit: async () => [{ pausedAt: new Date() }],
};
configureBotLifecycle({
database: { select: () => query } as unknown as Parameters<
typeof configureBotLifecycle
>[0]["database"],
});
const lockCalls: string[] = [];
let runs = 0;
const hop = createHandoffDelivery({
admission: serverTurnAdmission,
agentFor: async () => stubAgent(),
history: async () => PRIOR,
newRunId: () => "run-2",
mintThreadId: () => "scratch-thread",
lock: {
acquire: async () => {
lockCalls.push("acquire");
return { runId: "platform-run" };
},
renew: async () => {},
release: async () => {
lockCalls.push("release");
},
},
runner: {
run: () => {
runs += 1;
return new Observable<BaseEvent>(() => {});
},
},
});
try {
await expect(
hop.deliver({ work: WORK, message: "m", shown: "s", assertion: "s" }),
).rejects.toBeInstanceOf(BotPausedError);
expect(lockCalls).toEqual([]);
expect(runs).toBe(0);
} finally {
resetBotLifecycleForTests();
}
});
});