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 { afterEach, describe, expect, test } from "bun:test";
import {
callTool,
listTools,
type RoutineTools,
useRoutineTools,
} from "../src/plugins/builtin-routines";
import { MAX_RESULT_CHARS } from "../src/plugins/mcp";
import {
type Routine,
RoutineNotFoundError,
type RoutinePatch,
RoutineRefusedError,
type RoutineSummary,
} from "../src/routines/store";
/**
* The builtin Routines transport, asserted without a database.
*
* What is under test is the boundary, not the store: which method a tool name reaches, whose id the
* call is attributed to, and what a refusal reads as. A recording stub is installed through
* {@link useRoutineTools}, which is the only seam the module has — `transportFor` resolves a kind to
* a MODULE, so there is no constructor to pass a store to.
*
* The security property this file exists for is the attribution one: the owner comes from the
* connection's actor and the Bot from the connection's Bot, never from the arguments a model
* produced. A model that could name an owner could schedule work as somebody else.
*/
const CONNECTION = {
url: "builtin://routines/",
actorId: "user_asker",
botId: "bot_helper",
};
const ROUTINE: Routine = {
id: "routine_1",
ownerUserId: "user_asker",
agentId: "bot_helper",
channelId: "channel_1",
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
timezone: "Europe/Madrid",
enabled: true,
nextRunAt: new Date("2026-01-05T08:00:00.000Z"),
lastRunAt: null,
createdAt: new Date("2026-01-01T00:00:00.000Z"),
};
const SUMMARY: RoutineSummary = {
id: "routine_1",
agentId: "bot_helper",
instruction: "Post the standup summary.",
schedule: "Weekdays at 09:00",
timezone: "Europe/Madrid",
enabled: true,
nextRunAt: new Date("2026-01-05T08:00:00.000Z"),
channelId: "channel_1",
channelName: "Standup",
channelDeleted: false,
lastRun: {
status: "succeeded",
finishedAt: new Date("2026-01-02T08:00:03.000Z"),
},
};
type Recorded =
| { method: "create"; input: Parameters<RoutineTools["create"]>[0] }
| { method: "listFor"; ownerUserId: string }
| {
method: "update";
ownerUserId: string;
id: string;
patch: RoutinePatch;
}
| { method: "remove"; ownerUserId: string; id: string };
/** Installs a stub that records every call, and answers with the fixtures above. */
function recordingTools(overrides: Partial<RoutineTools> = {}): Recorded[] {
const calls: Recorded[] = [];
useRoutineTools({
async create(input) {
calls.push({ method: "create", input });
return ROUTINE;
},
async listFor(ownerUserId) {
calls.push({ method: "listFor", ownerUserId });
return [SUMMARY];
},
async update(ownerUserId, id, patch) {
calls.push({ method: "update", ownerUserId, id, patch });
return ROUTINE;
},
async remove(ownerUserId, id) {
calls.push({ method: "remove", ownerUserId, id });
},
...overrides,
});
return calls;
}
// The binding is module-level and the suite is one process, so a stub left installed here would be
// the store some other file's test unexpectedly reaches.
afterEach(() => {
useRoutineTools(null);
});
describe("a list too long for one result", () => {
test("is cut between characters, never through one", async () => {
const listing = (instruction: string) =>
recordingTools({
async listFor() {
return [{ ...SUMMARY, instruction }];
},
});
// Where the instruction starts in a listing, measured rather than assumed, so the emoji's high
// half lands on the last code unit the limit keeps whatever words surround it.
listing("MARKER");
const probe = await callTool(CONNECTION, "list_routines", {});
const before = probe.text.indexOf("MARKER");
expect(before).toBeGreaterThan(-1);
const filler = "a".repeat(MAX_RESULT_CHARS - 1 - before);
listing(`${filler}😀tail`);
const result = await callTool(CONNECTION, "list_routines", {});
expect(result.truncated).toBe(true);
expect(result.text.split("\n\n[truncated")[0]).toBe(
`${probe.text.slice(0, before)}${filler}`,
);
});
});
describe("the tool list", () => {
test("is the four routine tools and the five trigger tools, named exactly", async () => {
const tools = await listTools();
expect(tools.map((tool) => tool.name)).toEqual([
"create_routine",
"list_routines",
"update_routine",
"delete_routine",
"create_trigger",
"list_triggers",
"pause_trigger",
"resume_trigger",
"delete_trigger",
]);
for (const tool of tools) {
expect(tool.description.length).toBeGreaterThan(0);
expect(tool.inputSchema).toBeDefined();
}
});
test("carries the cron contract in create_routine's description", async () => {
const tools = await listTools();
const create = tools.find((tool) => tool.name === "create_routine");
expect(create).toBeDefined();
const description = create?.description ?? "";
expect(description).toContain("15");
expect(description).toContain("timezone");
expect(description).toContain("minute hour day-of-month month day-of-week");
expect(description).toContain("0 9 * * 1-5");
});
test("tells the model how to phrase the instruction itself", async () => {
// A live firing did nothing and reported success because its instruction was written in
// schedule-speak ("Every run, append …"): the model read it as a question about scheduling,
// checked that the routine existed, and answered "already configured". The firing turn now says
// it is a firing (`toolkit/run-turn.ts`), and this is the other half — the authoring side, so
// the instruction is written as work in the first place.
const tools = await listTools();
const create = tools.find((tool) => tool.name === "create_routine");
const description = create?.description ?? "";
expect(description).toContain("restate the schedule");
const update = tools.find((tool) => tool.name === "update_routine");
expect(update?.description ?? "").toContain("restate the schedule");
});
test("needs no actor, no arguments and no store", async () => {
// The only call site is `refreshTools`, which passes `{url, token}` and never an actor. A list
// that refused without one would store zero tools and Routines would advertise nothing.
useRoutineTools(null);
const tools = await listTools();
expect(tools).toHaveLength(9);
});
});
describe("dispatch", () => {
test("create_routine reaches create, attributed to the connection", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "create_routine", {
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
timezone: "Europe/Madrid",
channelId: "channel_1",
});
expect(result.isError).toBe(false);
const created = calls.find((call) => call.method === "create");
expect(created).toBeDefined();
expect(created).toMatchObject({
method: "create",
input: {
ownerUserId: "user_asker",
agentId: "bot_helper",
channelId: "channel_1",
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
timezone: "Europe/Madrid",
},
});
});
test("create_routine answers in words, not in cron", async () => {
recordingTools();
const result = await callTool(CONNECTION, "create_routine", {
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
});
expect(result.isError).toBe(false);
expect(result.text).toContain("Weekdays at 09:00");
expect(result.text).toContain("Europe/Madrid");
expect(result.text).toContain("Standup");
expect(result.text).toContain("routine_1");
expect(result.text).not.toContain("0 9 * * 1-5");
});
test("create_routine without a timezone passes none, inventing nothing", async () => {
const calls = recordingTools();
await callTool(CONNECTION, "create_routine", {
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
});
const created = calls.find((call) => call.method === "create");
// The STORE owns the UTC default. A zone guessed here would be a zone nobody chose.
expect(created?.method === "create" && created.input.timezone).toBe(
undefined,
);
});
test("list_routines reaches listFor, and renders id, words, channel and last run", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "list_routines", {});
expect(result.isError).toBe(false);
expect(calls).toContainEqual({
method: "listFor",
ownerUserId: "user_asker",
});
expect(result.text).toContain("routine_1");
expect(result.text).toContain("Weekdays at 09:00");
expect(result.text).toContain("Standup");
expect(result.text).toContain("succeeded");
});
test("update_routine reaches update with only the fields given", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "update_routine", {
id: "routine_1",
cron: "30 18 * * *",
enabled: false,
});
expect(result.isError).toBe(false);
expect(calls).toContainEqual({
method: "update",
ownerUserId: "user_asker",
id: "routine_1",
patch: { cron: "30 18 * * *", enabled: false },
});
});
test("delete_routine reaches remove", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "delete_routine", {
id: "routine_1",
});
expect(result.isError).toBe(false);
expect(calls).toContainEqual({
method: "remove",
ownerUserId: "user_asker",
id: "routine_1",
});
});
test("an unknown tool refuses without touching the store", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "pause_routine", {
id: "routine_1",
});
expect(result.isError).toBe(true);
expect(result.text).toContain("pause_routine");
expect(calls).toHaveLength(0);
});
});
describe("attribution", () => {
test("an owner named in the arguments is ignored", async () => {
const calls = recordingTools();
await callTool(CONNECTION, "create_routine", {
ownerUserId: "someone-else",
agentId: "another-bot",
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
});
const created = calls.find((call) => call.method === "create");
expect(created?.method === "create" && created.input.ownerUserId).toBe(
"user_asker",
);
expect(created?.method === "create" && created.input.agentId).toBe(
"bot_helper",
);
});
test("an owner named in the arguments is ignored by list, update and delete", async () => {
const calls = recordingTools();
const spoofed = { ownerUserId: "someone-else", agentId: "another-bot" };
await callTool(CONNECTION, "list_routines", { ...spoofed });
await callTool(CONNECTION, "update_routine", {
...spoofed,
id: "routine_1",
instruction: "Something else.",
});
await callTool(CONNECTION, "delete_routine", {
...spoofed,
id: "routine_1",
});
for (const call of calls) {
expect(call).toMatchObject({ ownerUserId: "user_asker" });
}
});
test("a run attributed to nobody is refused", async () => {
const calls = recordingTools();
const result = await callTool(
{ url: CONNECTION.url, botId: "bot_helper" },
"list_routines",
{},
);
expect(result.isError).toBe(true);
expect(result.text).toBe(
"A routine belongs to somebody, and this run is not attributed to anybody.",
);
expect(calls).toHaveLength(0);
});
test("an empty actor is not an actor", async () => {
const calls = recordingTools();
const result = await callTool(
{ url: CONNECTION.url, actorId: " ", botId: "bot_helper" },
"list_routines",
{},
);
expect(result.isError).toBe(true);
expect(result.text).toBe(
"A routine belongs to somebody, and this run is not attributed to anybody.",
);
expect(calls).toHaveLength(0);
});
test("a run that names no Bot is refused", async () => {
const calls = recordingTools();
const result = await callTool(
{ url: CONNECTION.url, actorId: "user_asker" },
"create_routine",
{ instruction: "Post it.", cron: "0 9 * * 1-5" },
);
expect(result.isError).toBe(true);
expect(result.text).toBe(
"A routine runs as a Bot, and this run does not name one.",
);
expect(calls).toHaveLength(0);
});
test("a deployment with no routine store refuses", async () => {
useRoutineTools(null);
const result = await callTool(CONNECTION, "list_routines", {});
expect(result.isError).toBe(true);
expect(result.text).toBe("Routines is not available in this deployment.");
});
});
describe("a write that landed but could not be read back", () => {
test("create: a listFor that throws after a successful write is not reported as a failure", async () => {
recordingTools({
async listFor() {
throw new Error("connection reset");
},
});
const result = await callTool(CONNECTION, "create_routine", {
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
});
expect(result.isError).toBe(false);
expect(result.text).toBe("That routine is set. Its id is routine_1.");
});
test("update: a listFor that throws after a successful write is not reported as a failure", async () => {
recordingTools({
async listFor() {
throw new Error("connection reset");
},
});
const result = await callTool(CONNECTION, "update_routine", {
id: "routine_1",
instruction: "Something else.",
});
expect(result.isError).toBe(false);
expect(result.text).toBe("That routine is updated. Its id is routine_1.");
});
test("create: the vanished-routine fallback reads as a sentence and names the id", async () => {
recordingTools({
async listFor() {
return [];
},
});
const result = await callTool(CONNECTION, "create_routine", {
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
});
expect(result.isError).toBe(false);
expect(result.text).toBe("That routine is set. Its id is routine_1.");
});
test("update: the vanished-routine fallback reads as a sentence and names the id", async () => {
recordingTools({
async listFor() {
return [];
},
});
const result = await callTool(CONNECTION, "update_routine", {
id: "routine_1",
instruction: "Something else.",
});
expect(result.isError).toBe(false);
expect(result.text).toBe("That routine is updated. Its id is routine_1.");
});
test("the confirmation read is attributed to the connection's actor, not the routine's owner", async () => {
const calls = recordingTools();
await callTool(CONNECTION, "create_routine", {
instruction: "Post the standup summary.",
cron: "0 9 * * 1-5",
});
const reads = calls.filter((call) => call.method === "listFor");
expect(reads).toContainEqual({
method: "listFor",
ownerUserId: "user_asker",
});
});
});
describe("a disabled routine's rendered next-run", () => {
test('omits an ISO timestamp after "next" and keeps the switched-off wording', async () => {
recordingTools({
async listFor() {
return [{ ...SUMMARY, enabled: false }];
},
});
const result = await callTool(CONNECTION, "list_routines", {});
expect(result.isError).toBe(false);
expect(result.text).not.toContain(SUMMARY.nextRunAt.toISOString());
expect(result.text).toContain("switched off");
expect(result.text).toMatch(/next when switched back on/);
});
});
describe("beyond-spec validation refusals", () => {
test("create_routine without an instruction refuses without touching the store", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "create_routine", {
cron: "0 9 * * 1-5",
});
expect(result.isError).toBe(true);
expect(result.text).toBe("A routine needs an instruction to carry out.");
expect(calls).toHaveLength(0);
});
test("create_routine without a cron refuses without touching the store", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "create_routine", {
instruction: "Post it.",
});
expect(result.isError).toBe(true);
expect(result.text).toBe(
"A routine needs a schedule: five cron fields, `minute hour day-of-month month day-of-week`.",
);
expect(calls).toHaveLength(0);
});
test("update_routine without an id refuses without touching the store", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "update_routine", {
instruction: "Something else.",
});
expect(result.isError).toBe(true);
expect(result.text).toBe(
"Say which routine to change, by the id from list_routines.",
);
expect(calls).toHaveLength(0);
});
test("update_routine with an empty patch refuses without touching the store", async () => {
const calls = recordingTools();
const result = await callTool(CONNECTION, "update_routine", {
id: "routine_1",
});
expect(result.isError).toBe(true);
expect(result.text).toBe("Say what to change about that routine.");
expect(calls).toHaveLength(0);
});
});
describe("what the store said", () => {
test("a refusal is carried through verbatim", async () => {
recordingTools({
async create() {
throw new RoutineRefusedError(
"Routines may run at most every 15 minutes.",
);
},
});
const result = await callTool(CONNECTION, "create_routine", {
instruction: "Post it.",
cron: "* * * * *",
});
expect(result.isError).toBe(true);
expect(result.text).toBe("Routines may run at most every 15 minutes.");
});
test("a missing routine is a sentence about ownership", async () => {
recordingTools({
async remove() {
throw new RoutineNotFoundError();
},
});
const result = await callTool(CONNECTION, "delete_routine", {
id: "routine_nope",
});
expect(result.isError).toBe(true);
expect(result.text).toBe("There is no routine of yours with that id.");
});
test("anything else is capped in code points and never escapes", async () => {
recordingTools({
async listFor() {
throw new Error(`${"é".repeat(600)}!`);
},
});
const result = await callTool(CONNECTION, "list_routines", {});
expect(result.isError).toBe(true);
expect(Array.from(result.text)).toHaveLength(400);
expect(result.text).toBe("é".repeat(400));
});
});