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 { AuditEventInput, AuditStore } from "../src/audit";
import { StaleSnapshotError } from "../src/computer/client";
import {
botSeat,
computerKeyText,
personSeat,
} from "../src/computer/computer-key";
import {
ActionRefusedError,
createComputerGateway,
WorkspaceNotFoundError,
WorkspaceRefusedError,
WorkspaceTooLargeError,
} from "../src/computer/gateway";
import type { ActionPolicy } from "../src/computer/policy";
import {
type ComputerLocation,
type ComputerProvider,
createSharedComputerProvider,
} from "../src/computer/provider";
import type { SnapshotResult } from "../src/computer/schema";
import {
createInMemorySnapshotStore,
type SnapshotStore,
} from "../src/computer/snapshot-store";
/**
* What the gateway must guarantee, tested as properties rather than as call sequences.
*
* The four that matter, and none of them are visible from a green typecheck:
* - a refused action does NOT reach the computer
* - a row is written either way, so the trail cannot only contain successes
* - the policy decides on the element the SERVER resolved, never on a label the caller supplied
* - the text typed into a field never enters the audit payload
*/
const SNAPSHOT: SnapshotResult = {
snapshotId: 7,
url: "https://example.com/order",
title: "Order",
truncated: false,
elements: [
{ ref: "e1", role: "input", name: "Customer name:", type: "text" },
{ ref: "e9", role: "button", name: "Submit order" },
],
};
/** A computer that records which HTTP actions reached it. */
function fakeComputer(options?: {
stopResult?: { wasRunning: boolean };
resetResult?: { cleared: boolean };
locations?: ComputerLocation[];
routes?: Record<string, (init?: RequestInit) => Response | Promise<Response>>;
/** Which run of the computer this stands for. Absent means a provider that cannot say. */
session?: () => string | undefined;
}) {
const calls: string[] = [];
const addressedAs: string[] = [];
const requests: Array<{ url: string; init?: RequestInit }> = [];
const stopResult = options?.stopResult ?? { wasRunning: true };
const resetResult = options?.resetResult ?? { cleared: true };
const locations = options?.locations ?? [];
const result = (action: string) => ({
action,
url: SNAPSHOT.url,
elapsedMs: 1,
});
const provider: ComputerProvider = {
name: "test",
isolation: "per-person",
locate: async (seat) => {
addressedAs.push(seat.botId);
return "http://agent-computer:4100";
},
...(options?.session ? { sessionOf: async () => options.session?.() } : {}),
status: async (seat) => ({ botId: seat.botId, state: "ready" }),
stop: async (target) => {
calls.push(`stop:${target.botId ?? computerKeyText(target.key)}`);
return stopResult;
},
reset: async (target) => {
calls.push(`reset:${target.botId ?? computerKeyText(target.key)}`);
return resetResult;
},
list: async () => locations,
};
const fetchImpl = (async (url: string, init?: RequestInit) => {
requests.push({ url, init });
const path = new URL(url).pathname;
if (options?.routes && path in options.routes) {
return options.routes[path](init);
}
switch (path) {
case "/snapshot":
return Response.json(SNAPSHOT);
case "/read":
return Response.json({
url: SNAPSHOT.url,
title: "Order",
text: "",
truncated: false,
});
case "/screenshot":
calls.push("screenshot");
return Response.json({
image: "aGVsbG8=",
mimeType: "image/png",
});
case "/files/download":
calls.push("downloadFile");
return new Response(Uint8Array.from([0, 1, 2, 255]), {
headers: { "content-length": "4" },
});
case "/files/read":
calls.push("readFile");
return Response.json({
path: "notes.md",
text: "kept",
truncated: false,
bytes: 4,
});
case "/files/write":
calls.push("writeFile");
return Response.json({
path: "notes.md",
bytes: 4,
appended: false,
});
case "/files/list":
calls.push("listFiles");
return Response.json({
path: "notes",
entries: [],
});
case "/exec":
calls.push("runCommand");
return Response.json({
command: "cat secrets.txt",
exitCode: 0,
output: "the customer's card number is 4111-1111-1111-1111",
truncated: false,
timedOut: false,
});
case "/navigate":
calls.push("navigate");
return Response.json({
url: "https://example.com/",
title: "Example",
elapsedMs: 1,
});
case "/click":
calls.push("click");
return Response.json(result("click"));
case "/type":
calls.push("type");
return Response.json(result("type"));
case "/key":
calls.push("key");
return Response.json(result("key"));
case "/scroll":
calls.push("scroll");
return Response.json(result("scroll"));
case "/control":
calls.push("control");
return Response.json({ mode: "bot" });
case "/control/request":
calls.push("requestHelp");
return Response.json({ mode: "human", reason: "Sign in" });
case "/control/take":
calls.push("takeControl");
return Response.json({ mode: "human" });
case "/control/release":
calls.push("releaseControl");
return Response.json({ mode: "bot" });
case "/control/secret":
calls.push("requestSecret");
return Response.json({ mode: "secret", ref: "e1" });
case "/human/secret":
calls.push("supplySecret");
return Response.json({ supplied: true });
case "/human/click":
case "/human/type":
case "/human/key":
case "/human/scroll":
case "/human/move":
case "/human/button":
case "/human/wheel":
calls.push(path.slice(1));
return Response.json({ ok: true });
default:
return Response.json(
{ error: `Unknown endpoint: ${path}` },
{ status: 404 },
);
}
}) as unknown as typeof fetch;
return { provider, fetchImpl, calls, addressedAs, requests };
}
function fakeAudit() {
const rows: AuditEventInput[] = [];
const store: AuditStore = { insert: async (event) => void rows.push(event) };
return { store, rows };
}
const ACTOR = { id: "dev-local-user" };
const PERMISSIVE: ActionPolicy = { mode: "enforce", deny: [], allow: ["true"] };
async function gatewayWith(
policy: ActionPolicy | undefined,
options?: {
stopResult?: { wasRunning: boolean };
resetResult?: { cleared: boolean };
locations?: ComputerLocation[];
token?: string;
/** Endpoints the computer answers differently, for the calls that have to fail. */
routes?: Record<
string,
(init?: RequestInit) => Response | Promise<Response>
>;
},
) {
const { provider, fetchImpl, calls, addressedAs, requests } =
fakeComputer(options);
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => policy,
token: options?.token,
});
// Every test acts on refs, so the server must hold a snapshot first, exactly as the real flow does.
await gateway.snapshot(botSeat("bot-1"));
return { gateway, calls, rows, addressedAs, requests, provider };
}
describe("the computer gateway", () => {
test("carries out an allowed action and records it", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE);
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(calls).toEqual(["click"]);
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[0]?.targetId).toBe("bot-1");
});
test("a refused action never reaches the computer", async () => {
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
deny: ['contains(element.name, "submit")'],
});
await expect(
gateway.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 7 }),
).rejects.toThrow(ActionRefusedError);
// The decision happens before the effect.
expect(calls).toEqual([]);
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.action_refused");
expect(rows[0]?.targetId).toBe("bot-1");
});
test("a rule about MCP does not refuse a browser action", async () => {
// An operator blocking MCP writes must not thereby block every click. The gateway carries a
// neutral `mcp`, so `mcp.effect == "write"` names a bound field and evaluates to false rather
// than throwing, which fails closed and would refuse the click.
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
deny: ['mcp.effect == "write"'],
});
await gateway.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 7 });
expect(calls).toEqual(["click"]);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
});
test("the refusal names the rule, so an operator can find it", async () => {
const { gateway } = await gatewayWith({
...PERMISSIVE,
deny: ['contains(element.name, "submit")'],
});
const error = await gateway
.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 7 })
.catch((caught: unknown) => caught);
expect(error).toBeInstanceOf(ActionRefusedError);
expect((error as ActionRefusedError).rule).toBe(
'contains(element.name, "submit")',
);
});
test("the policy sees the element the SERVER resolved, not what the caller claimed", async () => {
// The evasion this prevents: calling the Submit button something harmless in the request. The
// caller only ever sends a ref, and the gateway looks it up in the snapshot it fetched itself.
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['contains(element.name, "submit")'],
});
await expect(
gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
// Not part of the input contract, and must not influence anything even when supplied.
...({ name: "Continue", element: { name: "Continue" } } as object),
}),
).rejects.toThrow(ActionRefusedError);
expect(calls).toEqual([]);
});
test("an allowed action reports the element's label for the transcript", async () => {
const { gateway } = await gatewayWith(PERMISSIVE);
const result = await gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Grace Hopper",
});
expect(result.element?.name).toBe("Customer name:");
});
test("the typed text never enters the audit payload", async () => {
const { gateway, rows } = await gatewayWith(PERMISSIVE);
await gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "hunter2-not-a-real-password",
});
// Serialized and searched, rather than checking known keys: the guarantee is that the value is
// nowhere in the row, not that one particular field omits it.
expect(JSON.stringify(rows[0]?.payload)).not.toContain("hunter2");
expect(rows[0]?.payload.element).toEqual({
role: "input",
name: "Customer name:",
// The control's type is recorded too: knowing a value went into a `password` field rather than
// a `text` one is exactly the distinction an investigator needs, and it is not the value.
type: "text",
});
});
test("an absent policy refuses every action", async () => {
const { gateway, calls, rows } = await gatewayWith(undefined);
await expect(
gateway.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 7 }),
).rejects.toThrow(ActionRefusedError);
expect(calls).toEqual([]);
expect(rows[0]?.eventType).toBe("computer.action_refused");
});
test("dry-run records the refusal and still carries the action out", async () => {
const { gateway, calls, rows } = await gatewayWith({
mode: "dry-run",
deny: ['contains(element.name, "submit")'],
allow: ["true"],
});
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(calls).toEqual(["click"]);
const decision = rows[0]?.payload.decision as { carriedOut?: boolean };
expect(rows[0]?.eventType).toBe("computer.action_refused");
// Without this flag the row reads as a contradiction: refused, yet the work happened.
expect(decision.carriedOut).toBe(true);
});
test("the local development actor is kept out of the audit foreign key", async () => {
// Writing an id with no `users` row fails the constraint and loses the row entirely, so who it
// was is carried in the payload instead. The route decides this; the gateway must honour it.
const { gateway, rows } = await gatewayWith(PERMISSIVE);
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(rows[0]?.actorUserId).toBeUndefined();
expect(rows[0]?.payload.actor).toBe("dev-local-user");
});
test("a file read is governed, not passed through", async () => {
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
deny: ['contains(file.path, "credentials")'],
});
await expect(
gateway.readFile(botSeat("bot-1"), ACTOR, {
path: "credentials/aws.txt",
}),
).rejects.toThrow(ActionRefusedError);
expect(calls).toEqual([]);
expect(rows[0]?.eventType).toBe("computer.action_refused");
expect(rows[0]?.payload.file).toBe("credentials/aws.txt");
});
test("a rule can be written against a file's extension", async () => {
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['file.extension == "env"'],
});
await expect(
gateway.readFile(botSeat("bot-1"), ACTOR, { path: "config/prod.env" }),
).rejects.toThrow(ActionRefusedError);
// A different extension in the same folder is untouched by that rule.
await gateway.readFile(botSeat("bot-1"), ACTOR, {
path: "config/prod.json",
});
expect(calls).toEqual(["readFile"]);
});
test("a permitted write happens and is recorded by path, never by contents", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE);
await gateway.writeFile(botSeat("bot-1"), ACTOR, {
path: "notes.md",
contents: "the customer's card number is 4111-1111-1111-1111",
});
expect(calls).toEqual(["writeFile"]);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[0]?.payload.file).toBe("notes.md");
// The same guarantee as typed text: a Bot writes down what it was told, so a file body is exactly
// as sensitive and is never put in the row.
expect(JSON.stringify(rows[0]?.payload)).not.toContain("4111");
});
test("a permitted command runs and is recorded by command, never by output", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE);
await gateway.runCommand(botSeat("bot-1"), ACTOR, {
command: "cat secrets.txt",
});
expect(calls).toEqual(["runCommand"]);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[0]?.payload.command).toBe("cat secrets.txt");
// The command IS the action, so it is recorded in full. Its output is the file body of this
// pair: whatever the command read off a page or out of a file, and never in the row.
expect(JSON.stringify(rows[0]?.payload)).not.toContain("4111");
// A command has no page element, so the row says nothing about a snapshot it was never part of.
expect(rows[0]?.payload.element).toBeUndefined();
});
test("a permitted action stopped mid-flight is recorded as a stop, not a failure", async () => {
// A person pressing Stop is not the computer failing. The row still says so in its message, but
// its TYPE is `computer.action_stopped`, so a count of `action_failed` rows — the natural way to
// measure outages — does not read every Stop as one.
const { gateway, rows } = await gatewayWith(PERMISSIVE);
const stop = new AbortController();
stop.abort();
await expect(
gateway.runCommand(
botSeat("bot-1"),
ACTOR,
{ command: "cat secrets.txt" },
stop.signal,
),
).rejects.toThrow(/stopped/);
// The decision that permitted it, then the outcome — a stop, not a failure.
expect(rows).toHaveLength(2);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[1]?.eventType).toBe("computer.action_stopped");
expect(rows[1]?.payload.failure).toContain("stopped");
});
test("a command the policy refuses is recorded and never reaches the computer", async () => {
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
deny: ['intent == "run_command"'],
});
await expect(
gateway.runCommand(botSeat("bot-1"), ACTOR, {
command: "cat secrets.txt",
}),
).rejects.toThrow(ActionRefusedError);
expect(calls).toEqual([]);
expect(rows[0]?.eventType).toBe("computer.action_refused");
expect(rows[0]?.payload.command).toBe("cat secrets.txt");
});
/**
* The two rows describe one action, so they have to describe the same one.
*
* Asserted as agreement rather than field by field on purpose: the failure row is a second
* hand-maintained argument list, and what goes wrong with one of those is not a particular field
* being wrong, it is a field being added to one and not the other. Comparing the payloads catches
* the next one too.
*/
test("a permitted action that fails is recorded the same way it was decided", async () => {
const failing = () =>
Response.json({ error: "device or resource busy" }, { status: 500 });
for (const action of [
{
what: "a command",
route: "/exec",
run: (gateway: Awaited<ReturnType<typeof gatewayWith>>["gateway"]) =>
gateway.runCommand(botSeat("bot-1"), ACTOR, {
command: "rm -rf /workspace/build",
}),
},
{
what: "a keypress",
route: "/key",
run: (gateway: Awaited<ReturnType<typeof gatewayWith>>["gateway"]) =>
gateway.key(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
key: "Enter",
}),
},
{
what: "a file write",
route: "/files/write",
run: (gateway: Awaited<ReturnType<typeof gatewayWith>>["gateway"]) =>
gateway.writeFile(botSeat("bot-1"), ACTOR, {
path: "notes.md",
text: "kept",
}),
},
]) {
const { gateway, rows } = await gatewayWith(PERMISSIVE, {
routes: { [action.route]: failing },
});
rows.length = 0;
await expect(action.run(gateway)).rejects.toThrow();
const allowed = rows.find(
(row) => row.eventType === "computer.action_allowed",
);
const failed = rows.find(
(row) => row.eventType === "computer.action_failed",
);
expect(allowed, action.what).toBeDefined();
expect(failed, action.what).toBeDefined();
// The outcome is the only thing the failure row adds. Everything describing what was attempted
// is the same action and reads the same on both rows.
const { failure, ...attempted } = failed?.payload ?? {};
expect(failure, action.what).toBeString();
expect(attempted, action.what).toEqual(allowed?.payload ?? {});
}
});
test("the computer is told WHICH Bot is asking", async () => {
// Every per-Bot behaviour on the computer keys off this id: the profile it opens, the logins it
// has, the proxy its traffic leaves through, and who holds its wheel.
const { provider, fetchImpl, addressedAs } = fakeComputer();
const { store } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
});
await gateway.snapshot(botSeat("sales-bot"));
await gateway.click(botSeat("sales-bot"), ACTOR, {
ref: "e1",
snapshotId: 7,
});
await gateway.read(botSeat("research-bot"));
expect(addressedAs).toContain("sales-bot");
expect(addressedAs).toContain("research-bot");
// A call must never reach a different Bot's computer.
expect(
addressedAs.every((id) => id === "sales-bot" || id === "research-bot"),
).toBe(true);
});
test("a permitted action that FAILS gets its own row, not an allowed one", async () => {
// A permitted read that later fails path confinement records both the decision and the failed
// outcome, so the trail does not imply the Bot received the file.
const { provider, fetchImpl, calls } = fakeComputer({
routes: {
"/files/read": () => {
calls.push("readFile");
return Response.json(
{ error: "that path is outside your workspace" },
{ status: 403 },
);
},
},
});
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
});
await expect(
gateway.readFile(botSeat("bot-1"), ACTOR, { path: "../../etc/passwd" }),
).rejects.toThrow(WorkspaceRefusedError);
expect(rows).toHaveLength(2);
// The decision, then the outcome. Both are needed: the first says it was permitted, the second
// says it did not happen, and neither on its own is the truth.
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[1]?.eventType).toBe("computer.action_failed");
expect(rows[1]?.payload.failure).toContain("outside your workspace");
});
test("opening a page is recorded, with the address it was opening", async () => {
// The target guard refuses forbidden addresses before the request leaves.
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE);
await gateway.navigate(botSeat("bot-1"), ACTOR, "https://example.com/");
expect(calls).toEqual(["navigate"]);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[0]?.payload.action).toBe("computer_navigate");
expect(rows[0]?.payload.page).toBe("https://example.com/");
});
test("a rule can refuse a navigation by its DESTINATION host", async () => {
// The destination, not the page already loaded. Deciding on the current URL would make a rule
// about where a Bot may go structurally unable to say anything about where it is going.
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['page.host == "intranet.example.com"'],
});
await expect(
gateway.navigate(
botSeat("bot-1"),
ACTOR,
"https://intranet.example.com/hr",
),
).rejects.toThrow(ActionRefusedError);
expect(calls).toEqual([]);
await gateway.navigate(botSeat("bot-1"), ACTOR, "https://example.com/");
expect(calls).toEqual(["navigate"]);
});
/*
* "not in the current snapshot" is a statement about a ref that could not be resolved, and it used
* to be written on every action that never named an element at all. A reader looking at a
* navigation row went hunting for a snapshot that was never taken.
*/
test("an action that never named an element records no element", async () => {
const { gateway, rows } = await gatewayWith(PERMISSIVE);
await gateway.navigate(botSeat("bot-1"), ACTOR, "https://example.com/");
expect(rows.at(-1)?.payload.action).toBe("computer_navigate");
expect(rows.at(-1)?.payload.element).toBeUndefined();
});
test("an action on an unresolvable ref is still decided and still recorded", async () => {
const { gateway, rows } = await gatewayWith(PERMISSIVE);
// The assertion this test was written for is unchanged: the decision is taken and the row says
// plainly that the server could not identify what was touched, rather than omitting the field.
// What changed is what happens after the row: the action used to be forwarded, so an
// element-keyed deny rule could not match and the click landed anyway. It is now refused. The
// row is still written first, which is what keeps the attempt on the trail.
const refusal = await gateway
.click(botSeat("bot-1"), ACTOR, { ref: "e404", snapshotId: 7 })
.catch((error: unknown) => error);
expect(refusal).toBeInstanceOf(StaleSnapshotError);
expect(rows[0]?.payload.element).toBe("not in the current snapshot");
});
test("stopComputer returns true when the computer was running and audits with the bot id as target", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE, {
stopResult: { wasRunning: true },
});
const result = await gateway.stopComputer(botSeat("bot-1"), ACTOR);
expect(result).toEqual({ wasRunning: true });
expect(calls).toContain("stop:bot-1");
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.stopped");
expect(rows[0]?.targetId).toBe("bot-1");
expect(rows[0]?.targetType).toBe("computer");
});
test("stopComputer preserves wasRunning=false when the computer was already stopped", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE, {
stopResult: { wasRunning: false },
});
const result = await gateway.stopComputer(botSeat("bot-2"), ACTOR);
expect(result).toEqual({ wasRunning: false });
expect(calls).toContain("stop:bot-2");
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.stopped");
expect(rows[0]?.targetId).toBe("bot-2");
});
test("resetComputer returns true when state was cleared and audits with the bot id as target", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE, {
resetResult: { cleared: true },
});
const result = await gateway.resetComputer(botSeat("bot-1"), ACTOR);
expect(result).toEqual({ cleared: true });
expect(calls).toContain("reset:bot-1");
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.reset");
expect(rows[0]?.targetId).toBe("bot-1");
expect(rows[0]?.targetType).toBe("computer");
});
test("resetComputer preserves cleared=false when provider could not clear state and audits the bot id", async () => {
const { gateway, calls, rows } = await gatewayWith(PERMISSIVE, {
resetResult: { cleared: false },
});
const result = await gateway.resetComputer(botSeat("bot-2"), ACTOR);
expect(result).toEqual({ cleared: false });
expect(calls).toContain("reset:bot-2");
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.reset");
expect(rows[0]?.targetId).toBe("bot-2");
});
/*
* "The most destructive button we have. Every login the Bot had is gone and no undo exists, so the
* row is written whatever happens next."
*
* The profile is destroyed by `provider.reset` before either of the two Postgres deletes runs, so
* a delete that fails cannot put it back -- it can only take the row with it, which is the one
* thing that note rules out.
*/
test("resetComputer records the reset even when clearing the stored page fails", async () => {
const { provider, fetchImpl } = fakeComputer({
resetResult: { cleared: true },
});
const { store, rows } = fakeAudit();
const snapshots: SnapshotStore = {
...createInMemorySnapshotStore(),
clear: async () => {
throw new Error("connection reset by peer");
},
};
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
snapshots,
});
await expect(
gateway.resetComputer(botSeat("bot-1"), ACTOR),
).rejects.toThrow("connection reset by peer");
expect(rows.map((row) => row.eventType)).toContain("computer.reset");
expect(rows[0]?.targetId).toBe("bot-1");
});
test("resetComputer records the reset even when clearing the screenshots fails", async () => {
const { provider, fetchImpl } = fakeComputer({
resetResult: { cleared: true },
});
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
pageFrames: {
clear: async () => {
throw new Error("statement timeout");
},
} as unknown as NonNullable<
Parameters<typeof createComputerGateway>[0]["pageFrames"]
>,
});
await expect(
gateway.resetComputer(botSeat("bot-1"), ACTOR),
).rejects.toThrow("statement timeout");
expect(rows.map((row) => row.eventType)).toContain("computer.reset");
});
test("computers maps provider status 'running' and 'stopped' directly and preserves egress distinctions", async () => {
const locations: ComputerLocation[] = [
{
key: { kind: "bot", botId: "bot-proxied" },
status: "running",
startedAt: "2026-08-20T12:00:00.000Z",
egress: "198.51.100.42",
},
{
key: { kind: "bot", botId: "bot-direct" },
status: "stopped",
startedAt: "2026-08-20T11:00:00.000Z",
egress: null,
},
{
key: { kind: "bot", botId: "bot-unknown-egress" },
status: "stopped",
startedAt: "2026-08-20T10:00:00.000Z",
egress: undefined,
},
];
const { gateway } = await gatewayWith(PERMISSIVE, { locations });
const result = await gateway.computers();
expect(result).toEqual({
isolation: "per-person",
computers: [
{
computer: "bot:bot-proxied",
kind: "bot",
botId: "bot-proxied",
running: true,
startedAt: "2026-08-20T12:00:00.000Z",
egress: "198.51.100.42",
},
{
computer: "bot:bot-direct",
kind: "bot",
botId: "bot-direct",
running: false,
startedAt: "2026-08-20T11:00:00.000Z",
egress: null,
},
{
computer: "bot:bot-unknown-egress",
kind: "bot",
botId: "bot-unknown-egress",
running: false,
startedAt: "2026-08-20T10:00:00.000Z",
egress: undefined,
},
],
});
});
test("takes a screenshot through the located computer with its identity and token", async () => {
const { gateway, requests } = await gatewayWith(PERMISSIVE, {
token: "computer-secret",
});
const result = await gateway.screenshot(botSeat("bot-1"));
expect(result).toEqual({
image: "aGVsbG8=",
mimeType: "image/png",
});
const screenshotReq = requests.find((r) => r.url.endsWith("/screenshot"));
expect(screenshotReq).toBeDefined();
expect(screenshotReq?.url).toBe("http://agent-computer:4100/screenshot");
expect(screenshotReq?.init?.headers).toMatchObject({
"x-openbot-bot-id": "bot-1",
"x-openbot-computer-token": "computer-secret",
});
});
test("downloads raw bytes through the separate download intent and records it", async () => {
const { gateway, calls, rows, requests } = await gatewayWith(PERMISSIVE, {
token: "computer-secret",
});
const download = await gateway.downloadFile(botSeat("bot-1"), ACTOR, {
path: "reports/Q3 file.pdf",
});
expect(download.name).toBe("Q3 file.pdf");
expect(download.bytes).toBe(4);
expect(
new Uint8Array(await new Response(download.body).arrayBuffer()),
).toEqual(Uint8Array.from([0, 1, 2, 255]));
expect(calls).toContain("downloadFile");
expect(rows[0]?.eventType).toBe("computer.action_allowed");
expect(rows[0]?.payload).toMatchObject({
action: "computer_download_file",
bot: "bot-1",
file: "reports/Q3 file.pdf",
});
const request = requests.find(({ url }) => url.includes("/files/download"));
expect(request?.init?.method).toBe("GET");
expect(request?.init?.headers).toMatchObject({
"x-openbot-bot-id": "bot-1",
"x-openbot-computer-token": "computer-secret",
});
expect(new URL(request?.url ?? "").searchParams.get("path")).toBe(
"reports/Q3 file.pdf",
);
});
test("an absent policy refuses a download before the computer is asked", async () => {
const { gateway, calls, rows } = await gatewayWith(undefined);
await expect(
gateway.downloadFile(botSeat("bot-1"), ACTOR, { path: "report.pdf" }),
).rejects.toThrow(ActionRefusedError);
expect(calls).not.toContain("downloadFile");
expect(rows[0]?.eventType).toBe("computer.action_refused");
expect(rows[0]?.payload.action).toBe("computer_download_file");
});
test("a download rule does not reuse the read-file permission", async () => {
const separate = await gatewayWith({
...PERMISSIVE,
deny: ['tool.name == "computer_read_file"'],
});
await expect(
separate.gateway.downloadFile(botSeat("bot-1"), ACTOR, {
path: "report.pdf",
}),
).resolves.toMatchObject({ name: "report.pdf" });
expect(separate.calls).toContain("downloadFile");
const denied = await gatewayWith({
...PERMISSIVE,
deny: ['intent == "download_file"'],
});
await expect(
denied.gateway.downloadFile(botSeat("bot-1"), ACTOR, {
path: "report.pdf",
}),
).rejects.toThrow(ActionRefusedError);
expect(denied.calls).not.toContain("downloadFile");
expect(denied.rows[0]?.eventType).toBe("computer.action_refused");
});
test("records a failed download attempt after the allowed decision", async () => {
const { gateway, rows } = await gatewayWith(PERMISSIVE, {
routes: {
"/files/download": () =>
Response.json({ error: "No such file." }, { status: 404 }),
},
});
await expect(
gateway.downloadFile(botSeat("bot-1"), ACTOR, { path: "missing.pdf" }),
).rejects.toThrow(WorkspaceNotFoundError);
expect(rows.map(({ eventType }) => eventType)).toEqual([
"computer.action_allowed",
"computer.action_failed",
]);
});
test("maps an oversized computer response to a 413-equivalent error", async () => {
const { gateway } = await gatewayWith(PERMISSIVE, {
routes: {
"/files/download": () =>
Response.json({ error: "Too large." }, { status: 413 }),
},
});
await expect(
gateway.downloadFile(botSeat("bot-1"), ACTOR, { path: "big.zip" }),
).rejects.toThrow(WorkspaceTooLargeError);
});
test("routes acting, control, file, secret, and human input calls to the correct endpoint paths", async () => {
const { gateway, requests } = await gatewayWith(PERMISSIVE);
await gateway.key(botSeat("bot-1"), ACTOR, { key: "Tab" });
await gateway.scroll(botSeat("bot-1"), ACTOR, { deltaY: 400 });
await gateway.listFiles(botSeat("bot-1"), ACTOR, { path: "notes" });
await gateway.control(botSeat("bot-1"));
await gateway.requestHelp(botSeat("bot-1"), ACTOR, "Sign in");
await gateway.takeControl(botSeat("bot-1"), ACTOR, "request-1");
await gateway.releaseControl(botSeat("bot-1"), ACTOR, "request-1");
await gateway.requestSecret(botSeat("bot-1"), ACTOR, {
label: "Password",
ref: "e1",
snapshotId: 7,
});
await gateway.supplySecret(botSeat("bot-1"), ACTOR, "secret");
await gateway.humanInput(botSeat("bot-1"), { kind: "click", x: 10, y: 20 });
const paths = requests.map(({ url }) => new URL(url).pathname);
expect(paths).toEqual([
"/snapshot",
"/key",
"/scroll",
"/files/list",
"/control",
"/control/request",
"/control/take",
"/control/release",
"/control/secret",
"/human/secret",
"/human/click",
]);
});
/*
* Through `gatewayWith`, deliberately, rather than by handing `evaluateActionPolicy` a context
* written here. The bug these cover was that the context the gateway builds and the context the
* policy tests built were different shapes, so a policy test asserting a browser rule does not
* refuse a command passed while production refused every click. A test that builds its own context
* can only ever check the context it built.
*/
describe("a deny rule that names a field this action does not have", () => {
test("a command rule does not refuse a click", async () => {
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
// The rule the documentation gives as the example.
deny: ['contains(command, "rm -rf")'],
});
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(calls).toEqual(["click"]);
expect(rows[0]?.eventType).toBe("computer.action_allowed");
});
test("a key rule does not refuse a click", async () => {
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['key == "Enter"'],
});
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(calls).toEqual(["click"]);
});
test("a file rule does not refuse a click", async () => {
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['contains(file.path, "secret")'],
});
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(calls).toEqual(["click"]);
});
test("a submit typed into a field is the same Enter, and the rule catches it", async () => {
/*
* The second door, reached through the first tool.
*
* `computer_type` takes `submit`, which presses Enter when the text is in. A rule written
* about Enter saw a keypress and a click and not this, so an agent refused at both doors
* typed into the field with `submit: true` and the form went through. The preset shipped in
* `.env.example` and on the Boundaries page is exactly this rule, so the deployment that
* followed the product's own advice was the one with the hole in it.
*/
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
deny: ['key == "Enter"'],
});
await expect(
gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Ada",
submit: true,
}),
).rejects.toThrow();
expect(calls).toEqual([]);
expect(rows[0]?.eventType).toBe("computer.action_refused");
// The key belongs in the trail for the same reason it belongs in the decision: without it the
// row says somebody filled in a field, and not that they submitted the form.
expect((rows[0]?.payload as { key?: string } | undefined)?.key).toBe(
"Enter",
);
});
test("typing without a submit is still typing", async () => {
// The other direction. A rule about Enter must not start refusing ordinary text, which is what
// a fix that simply reported every type as a keypress would do.
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['key == "Enter"'],
});
await gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Ada",
});
expect(calls).toEqual(["type"]);
});
test("a submit is an activation, so an intent rule catches it too", async () => {
// `intent` is the other way an operator writes this, and it is the one the preset leads with.
// Enter pressed in a field presses whatever the form activates, the same as Space or a click.
const { gateway, calls } = await gatewayWith({
...PERMISSIVE,
deny: ['intent == "activate"'],
});
await expect(
gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Ada",
submit: true,
}),
).rejects.toThrow();
expect(calls).toEqual([]);
});
/*
* The rule the product ships, run against every door it claims to close.
*
* Written out here rather than imported because the two places it lives, `.env.example` and the
* Boundaries preset list, are a string in a comment and a string in the browser bundle. What
* this pins is the behaviour an operator gets by taking the product's own advice, so a change to
* either copy that reopens a door fails here.
*/
const SHIPPED_NEVER_SUBMIT =
'(intent == "activate" && contains(element.name, "submit")) || ((tool.name == "computer_key" || tool.name == "computer_type") && key == "Enter")';
test("the shipped preset closes the button, the keypress and the submit flag", async () => {
const shipped = { ...PERMISSIVE, deny: [SHIPPED_NEVER_SUBMIT] };
const click = await gatewayWith(shipped);
await expect(
click.gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
}),
).rejects.toThrow();
expect(click.calls).toEqual([]);
const enter = await gatewayWith(shipped);
await expect(
enter.gateway.key(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
key: "Enter",
}),
).rejects.toThrow();
expect(enter.calls).toEqual([]);
const submit = await gatewayWith(shipped);
await expect(
submit.gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Ada",
submit: true,
}),
).rejects.toThrow();
expect(submit.calls).toEqual([]);
});
test("the shipped preset still lets the Bot fill the form in", async () => {
// A boundary that stopped a Bot typing its way through a form would be refused by the first
// deployment to try it, and an operator would take the whole rule off rather than narrow it.
const shipped = { ...PERMISSIVE, deny: [SHIPPED_NEVER_SUBMIT] };
const typing = await gatewayWith(shipped);
await typing.gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Ada",
});
expect(typing.calls).toEqual(["type"]);
const looking = await gatewayWith(shipped);
await looking.gateway.screenshot(botSeat("bot-1"));
expect(looking.calls).toEqual(["screenshot"]);
});
test("but the rule still refuses the action it is about", async () => {
// The point is not that these rules stop working. A neutral value answers honestly; it does
// not answer no.
const { gateway, calls, rows } = await gatewayWith({
...PERMISSIVE,
deny: ['key == "Enter"'],
});
await expect(
gateway.key(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
key: "Enter",
}),
).rejects.toThrow();
expect(calls).toEqual([]);
expect(rows[0]?.eventType).toBe("computer.action_refused");
});
});
});
/**
* The gateway builds the computer path from `kind`, so `kind` cannot be a caller's string.
*
* The route ahead of it checks the four gestures, and this is the layer that holds when something
* gets past that: a value reaching here decides which endpoint of the computer's API the deployment
* calls, with its computer token attached. `humanInput` is also the one acting method that writes no
* audit row, by design, so a redirected call leaves nothing behind to read afterwards.
*/
describe("human input names a gesture, not a path", () => {
test.each([
["../computers/reset", "another endpoint of the computer's API"],
["../exec", "the shell"],
["click/../../health", "a traversal in the middle"],
["", "nothing at all"],
])("refuses %s (%s), and sends nothing", async (kind) => {
const { gateway, requests } = await gatewayWith(PERMISSIVE);
const before = requests.length;
await expect(
gateway.humanInput(botSeat("bot-1"), { kind, x: 1, y: 1 } as never),
).rejects.toThrow();
// Nothing left this process. Asserting only that it threw would pass just as well when the
// request went out and the far side answered 404, which is the failure being fixed.
expect(requests.slice(before)).toEqual([]);
});
test.each(["click", "type", "key", "scroll"])(
"carries %s through, because that is what a person's hands do",
async (kind) => {
const { gateway, requests } = await gatewayWith(PERMISSIVE);
await gateway.humanInput(botSeat("bot-1"), { kind, x: 1, y: 1 } as never);
expect(
requests.some(
(request) => new URL(request.url).pathname === `/human/${kind}`,
),
).toBe(true);
},
);
});
describe("resolving a computer's address", () => {
test("a foreign address is refused, so nothing is sent to it", async () => {
/*
* The guard exists because the address decides where the deployment's computer token goes. Every
* acting path resolved through here already; the live-screen socket resolved through the provider
* directly and skipped it, while putting the token in a query string.
*/
const { provider, fetchImpl, requests } = fakeComputer();
const { store } = fakeAudit();
const gateway = createComputerGateway({
// The cloud metadata address, which is the answer this guard was written for.
provider: { ...provider, locate: async () => "http://169.254.169.254" },
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
token: "deployment-token",
});
await expect(gateway.locate(botSeat("bot-1"))).rejects.toThrow();
// Refused before anything was sent, so the token never left.
expect(requests).toEqual([]);
});
test("an address the guard allows is returned", async () => {
const { provider, fetchImpl } = fakeComputer();
const { store } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
});
await expect(gateway.locate(botSeat("bot-1"))).resolves.toContain("http");
});
});
/**
* The snapshot a ref resolves against is shared between servers, not held in one process.
*
* OpenBot runs several server processes behind a load balancer, and the process that answers a
* snapshot is rarely the one that answers the click that uses its refs. If the mapping from ref to
* element lives in a `Map`, it is missing on every replica but the one that snapshotted: the policy
* decides with no element in front of it, and the deny rule the deployment is relying on does not
* fire. These prove the resolution survives the hop to another replica, which is the whole point of
* moving it to a store.
*
* Two gateways sharing one store stand in for two replicas sharing one database. The store is the
* only thing they have in common, exactly as Postgres is the only thing two real replicas share.
*/
describe("resolving a ref across replicas", () => {
function replica(policy: ActionPolicy, snapshots: SnapshotStore) {
const { provider, fetchImpl, calls } = fakeComputer();
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => policy,
snapshots,
});
return { gateway, calls, rows };
}
const DENY_SUBMIT: ActionPolicy = {
...PERMISSIVE,
deny: ['contains(element.name, "submit")'],
};
test("a click is resolved and refused on a replica that never took the snapshot", async () => {
const snapshots = createInMemorySnapshotStore();
const tookSnapshot = replica(DENY_SUBMIT, snapshots);
const handlesClick = replica(DENY_SUBMIT, snapshots);
await tookSnapshot.gateway.snapshot(botSeat("bot-1"));
// e9 is the Submit button. The replica that never snapshotted still resolves it from the store and
// refuses it. Held in a Map, this gateway's snapshot would be empty, the rule would have no element
// to match, and the Submit click would go straight through: the boundary silently off on every
// server but the one that happened to snapshot.
await expect(
handlesClick.gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
}),
).rejects.toThrow(ActionRefusedError);
expect(handlesClick.calls).toEqual([]);
expect(handlesClick.rows[0]?.eventType).toBe("computer.action_refused");
});
test("the resolved element label comes from the store, so any replica can name it", async () => {
const snapshots = createInMemorySnapshotStore();
const tookSnapshot = replica(PERMISSIVE, snapshots);
const handlesClick = replica(PERMISSIVE, snapshots);
await tookSnapshot.gateway.snapshot(botSeat("bot-1"));
const result = await handlesClick.gateway.type(botSeat("bot-1"), ACTOR, {
ref: "e1",
snapshotId: 7,
text: "Grace Hopper",
});
// The label is resolved on the replica that never saw the page, so the transcript and the trail
// say what was acted on instead of quoting a ref.
expect(result.element?.name).toBe("Customer name:");
expect(handlesClick.rows[0]?.payload.element).toEqual({
role: "input",
name: "Customer name:",
type: "text",
});
});
test("a ref only resolves against the generation it came from", async () => {
// The store holds snapshot 7, where e9 is Submit. The same ref cited against snapshot 7 resolves;
// cited against an older snapshot 6 it does not, because the caller is looking at a page that has
// since moved on and its e9 may be a different control now. Resolving it anyway is the "decide on
// fiction" a persisted snapshot is rightly warned about; matching the generation is the answer.
// The computer makes the same check when the action reaches it and refuses a superseded ref there.
const snapshots = createInMemorySnapshotStore();
const tookSnapshot = replica(PERMISSIVE, snapshots);
const handlesClick = replica(PERMISSIVE, snapshots);
await tookSnapshot.gateway.snapshot(botSeat("bot-1"));
const current = await handlesClick.gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: 7,
});
expect(current.element?.name).toBe("Submit order");
// Not resolved to snapshot 7's Submit button: the ref carried an older generation. The claim is
// unchanged; the assertion moved because a citation that cannot be resolved is now refused rather
// than forwarded with an empty element, which is what let an element-keyed deny rule go inert.
const superseded = await handlesClick.gateway
.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 6 })
.catch((error: unknown) => error);
expect(superseded).toBeInstanceOf(StaleSnapshotError);
expect(handlesClick.rows[1]?.payload.element).toBe(
"not in the current snapshot",
);
});
test("wiping a computer forgets the snapshot, so a reused generation cannot resolve", async () => {
// A fresh computer counts generations from one again. If a reset left the row behind, a ref the
// model was still holding from the previous session would match the new session's first
// generation and the policy would decide against an element from a page that no longer exists.
const snapshots = createInMemorySnapshotStore();
const tookSnapshot = replica(PERMISSIVE, snapshots);
const handlesClick = replica(PERMISSIVE, snapshots);
await tookSnapshot.gateway.snapshot(botSeat("bot-1"));
await tookSnapshot.gateway.resetComputer(botSeat("bot-1"), ACTOR);
// Still forwarded with the element unresolved, and deliberately so. A reset deletes the row, so
// this server holds no snapshot for the computer at all and has nothing to judge the citation
// against; the refusal added for a stale citation fires only where there is a stored page to see
// that it is stale. The computer is the party that can answer here, and taking its answer away
// would also take away the one that says a person has the wheel.
const afterReset = await handlesClick.gateway.click(
botSeat("bot-1"),
ACTOR,
{
ref: "e9",
snapshotId: 7,
},
);
expect(afterReset.element).toBeUndefined();
});
});
/**
* A ref from a computer that has since been replaced.
*
* The generation a computer stamps on a snapshot is unique only within one run of it. A replaced
* container counts from one again, so a ref the model is still holding from the run before matches
* a row nothing has overwritten, and the element handed to the policy belongs to a page that no
* longer exists: a deny rule about "Confirm transfer" fires on a click that is nowhere near it, or
* worse, does not fire on one that is.
*
* `resetComputer` clears the row for exactly that reason and is the only thing that does. The
* supervisor replaces a computer whose image has changed without telling the server, so the row
* outlives the run that wrote it and nothing notices.
*/
describe("a ref that outlived its computer", () => {
test("does not resolve against the dead run's page", async () => {
const snapshots = createInMemorySnapshotStore();
let run = "run-1";
const { provider, fetchImpl } = fakeComputer({ session: () => run });
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
snapshots,
});
const taken = await gateway.snapshot(botSeat("bot-1"));
// The computer is replaced. Its generation counter starts again, and nothing clears the row.
run = "run-2";
/*
* The same generation the model is still holding, now belonging to a different run. Resolving it
* would hand the policy an element from the dead page.
*
* This comment used to say that refusing to resolve leaves the boundary deciding with no element,
* "which is the honest answer and the one a deny rule treats as a match". The first half is right
* and the second was not: an all-empty element is what a deny rule keyed on `element.name` fails
* to match, so the action was permitted by the shipped default and carried out. The citation is
* refused now, which is what makes the sentence true.
*/
const refusal = await gateway
.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: taken.snapshotId,
})
.catch((error: unknown) => error);
expect(refusal).toBeInstanceOf(StaleSnapshotError);
// Recorded as unresolved rather than as the dead page's button, which is what the audit row
// said before: `element: { name: "Confirm transfer" }` on a click nowhere near it.
expect(rows.at(-1)?.payload.element).toBe("not in the current snapshot");
});
test("still resolves while the computer is the same one", async () => {
// The control. A session check that refused everything would look identical in the test above.
const snapshots = createInMemorySnapshotStore();
const { provider, fetchImpl } = fakeComputer({ session: () => "run-1" });
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
snapshots,
});
const taken = await gateway.snapshot(botSeat("bot-1"));
await gateway.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: taken.snapshotId,
});
expect(rows.at(-1)?.payload.element).toMatchObject({
name: "Submit order",
});
});
});
describe("acting on a ref the server cannot resolve", () => {
const DENY_SUBMIT: ActionPolicy = {
...PERMISSIVE,
deny: ['contains(element.name, "submit")'],
};
test("the rule refuses the click while it can see the element", async () => {
// The control. Without it a fix that refused everything would look identical to a fix that
// works, and the rule below would prove nothing about the element being visible to the policy.
const { gateway, calls } = await gatewayWith(DENY_SUBMIT);
const refusal = await gateway
.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 7 })
.catch((error: unknown) => error);
expect(refusal).toBeInstanceOf(ActionRefusedError);
expect(calls).toEqual([]);
});
test("a cited ref that does not resolve is refused, not carried out with the rule blind", async () => {
// The same rule, the same button, and a citation the server cannot resolve. The element half of
// the policy context is then all-empty, so `contains(element.name, "submit")` is false and the
// shipped default permits: the click was forwarded and performed while the rule that exists to
// stop it never saw what it was about to touch. The audit row was honest about not identifying
// the element, which is what makes this a prevention failure rather than a detection one.
const { gateway, calls, rows } = await gatewayWith(DENY_SUBMIT);
const refusal = await gateway
.click(botSeat("bot-1"), ACTOR, { ref: "e9", snapshotId: 2 })
.catch((error: unknown) => error);
expect(refusal).toBeInstanceOf(StaleSnapshotError);
expect(calls).toEqual([]);
// Still recorded. An action whose ref resolves to nothing is an action somebody tried to take,
// and refusing it before the row is written would be a way to act without appearing on the trail.
expect(rows.map((row) => row.eventType)).toEqual([
"computer.action_allowed",
"computer.action_failed",
]);
expect(rows[0]?.payload.element).toBe("not in the current snapshot");
});
test("an action that names no ref is untouched, because it has nothing to have failed to resolve", async () => {
// The boundary. A scroll, a page-level keypress, a shell call and a file read legitimately carry
// no element, and the neutral empty element is the right answer for them: it is what keeps a rule
// about one action surface from throwing on another. Only a citation that was made and could not
// be honoured is refused here.
const { gateway, calls } = await gatewayWith(PERMISSIVE);
await gateway.scroll(botSeat("bot-1"), ACTOR, { deltaY: 200 });
expect(calls).toEqual(["scroll"]);
});
});
/**
* The deployment with one computer for every Bot.
*
* Every session case above supplies a provider that reports a run, and the shared computer is the one
* that had nothing to report it from: no supervisor, no container per Bot, one process that outlives
* every reset. The ordering the rest of this file exercises was therefore inert exactly there, and
* the two failures it exists to stop were both reachable. These go through the real provider rather
* than a fake, because the fake is what hid it.
*/
describe("a Bot on the one shared computer", () => {
const FRESH = {
snapshotId: 1,
url: "https://fresh.example/start",
title: "Start",
truncated: false,
elements: [{ ref: "e1", role: "link", name: "Sign in" }],
} satisfies SnapshotResult;
/** A shared computer that answers which run each Bot's browser is on, as the real one does. */
function sharedComputer() {
let run = "run-1";
let live: SnapshotResult = SNAPSHOT;
let afterSnapshot: (() => void) | undefined;
const server = Bun.serve({
port: 0,
fetch: async (request) => {
const path = new URL(request.url).pathname;
if (path === "/run") return Response.json({ run });
if (path === "/snapshot") {
const answer = Response.json(live);
// A computer that goes away as it answers, which is the window the run has to be read before.
afterSnapshot?.();
return answer;
}
if (path === "/computers/reset") return Response.json({ reset: true });
if (path === "/click")
return Response.json({
action: "click",
url: live.url,
elapsedMs: 1,
});
return Response.json({ error: path }, { status: 404 });
},
});
return {
baseUrl: `http://127.0.0.1:${server.port}`,
stop: () => server.stop(true),
/** A new browser session: a restart, an eviction, a redeploy, or a reset. */
replaceRun: (next: string) => {
run = next;
},
showing: (next: SnapshotResult) => {
live = next;
},
/** Something that happens the instant the snapshot is answered, and before anything else is asked. */
onSnapshot: (effect: () => void) => {
afterSnapshot = effect;
},
};
}
function gatewayOn(computer: ReturnType<typeof sharedComputer>) {
const snapshots = createInMemorySnapshotStore();
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider: createSharedComputerProvider({ baseUrl: computer.baseUrl }),
auditStore: store,
policy: () => PERMISSIVE,
snapshots,
});
return { gateway, rows, snapshots };
}
test("a save still in flight when the wipe landed cannot resurrect the page", async () => {
/*
* `clear` deletes the row, so a save that was already on its way finds nothing to conflict with
* and inserts unconditionally. The row is back, describing a page the reset destroyed, and the
* policy decides about its elements: a deny rule on "Submit order" fires on a click nowhere near
* one, or a rule written for the new page does not fire on one that is.
*
* The write cannot tell the two apart, and does not have to. The resurrected row carries the run
* that took it, the reset gave the Bot a new one, and the read refuses the citation.
*/
const computer = sharedComputer();
try {
const { gateway, rows, snapshots } = gatewayOn(computer);
const taken = await gateway.snapshot(botSeat("bot-1"));
await gateway.resetComputer(botSeat("bot-1"), ACTOR);
expect(await snapshots.load("bot:bot-1")).toBeUndefined();
// The reset closed that browser, so the next one is a different run.
computer.replaceRun("run-2");
// And now the save that was in flight when it landed, carrying the run it was taken on.
await snapshots.save("bot:bot-1", {
snapshotId: taken.snapshotId,
url: taken.url,
elements: new Map(
taken.elements.map((element) => [element.ref, element]),
),
session: "run-1",
});
const refusal = await gateway
.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: taken.snapshotId,
})
.catch((error: unknown) => error);
expect(refusal).toBeInstanceOf(StaleSnapshotError);
expect(rows.at(-1)?.payload.element).toBe("not in the current snapshot");
} finally {
computer.stop();
}
});
test("a restarted computer's first snapshot lands instead of being read as stale", async () => {
/*
* The generation lives in a map in the computer's process, and a restart, a redeploy, or the idle
* sweep dropping the session all mint it at zero again. Nothing clears the server's row, so with
* the generation as the only ordering the fresh page looks older than the dead one and every
* snapshot is dropped until the counter climbs back past it. Refs then resolve against a page
* nobody is on.
*/
const computer = sharedComputer();
try {
const { gateway, snapshots } = gatewayOn(computer);
await gateway.snapshot(botSeat("bot-1"));
expect((await snapshots.load("bot:bot-1"))?.snapshotId).toBe(7);
computer.replaceRun("run-2");
computer.showing(FRESH);
await gateway.snapshot(botSeat("bot-1"));
const held = await snapshots.load("bot:bot-1");
expect(held?.snapshotId).toBe(1);
expect(held?.url).toBe(FRESH.url);
} finally {
computer.stop();
}
});
test("a computer replaced while a snapshot was being taken does not stamp the page with the new run", async () => {
/*
* The run is asked for on the same path as the snapshot, and the two answers have to describe the
* same browser. Asked afterwards, they need not: a container that goes away between answering
* `/snapshot` and answering this one stamps the page it drew with the run of the browser that
* replaced it, and the row then claims the live run is showing a page from the dead one. Every
* ref on it resolves, and the fresh browser's own snapshots are refused for being older, which is
* both halves of the bug back inside a smaller window.
*
* Asked first, the stamp is the run that was live when we asked. A computer replaced underneath
* leaves a row nothing will match until the next snapshot lands, which is the direction this is
* allowed to fail in.
*/
const computer = sharedComputer();
try {
const { gateway, rows, snapshots } = gatewayOn(computer);
computer.onSnapshot(() => computer.replaceRun("run-2"));
const taken = await gateway.snapshot(botSeat("bot-1"));
expect((await snapshots.load("bot:bot-1"))?.session).toBe("run-1");
const refusal = await gateway
.click(botSeat("bot-1"), ACTOR, {
ref: "e9",
snapshotId: taken.snapshotId,
})
.catch((error: unknown) => error);
expect(refusal).toBeInstanceOf(StaleSnapshotError);
expect(rows.at(-1)?.payload.element).toBe("not in the current snapshot");
} finally {
computer.stop();
}
});
test("within one run an older snapshot still does not overwrite a newer one", async () => {
// The control. Ordering across runs that also stopped ordering within one would let two replicas
// snapshotting the same computer land in whichever order Postgres saw them.
const computer = sharedComputer();
try {
const { gateway, snapshots } = gatewayOn(computer);
await gateway.snapshot(botSeat("bot-1"));
computer.showing(FRESH);
await gateway.snapshot(botSeat("bot-1"));
expect((await snapshots.load("bot:bot-1"))?.snapshotId).toBe(7);
} finally {
computer.stop();
}
});
});
describe("updating a computer's image", () => {
test("audits who moved the computer onto the new image", async () => {
const { provider, fetchImpl } = fakeComputer();
const { store, rows } = fakeAudit();
const asked: string[] = [];
provider.update = async (key) => {
asked.push(computerKeyText(key));
return { updated: true, wasRunning: true, from: "old", to: "new" };
};
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
});
expect(await gateway.updateComputer(botSeat("bot-1"), ACTOR)).toMatchObject(
{
updated: true,
},
);
expect(asked).toEqual(["bot:bot-1"]);
expect(rows).toHaveLength(1);
expect(rows[0]?.eventType).toBe("computer.updated");
expect(rows[0]?.targetId).toBe("bot-1");
expect(String(rows[0]?.payload.reason)).toContain("new");
});
test("a provider with no image of its own says so rather than pretending", async () => {
const { provider, fetchImpl } = fakeComputer();
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider,
fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
});
await expect(
gateway.updateComputer(botSeat("bot-1"), ACTOR),
).rejects.toThrow(/no computer image/);
expect(rows).toHaveLength(0);
});
});
/**
* One computer per person, with a seat per Bot inside it.
*
* Every layer used to key a computer by the Bot alone, so a public Bot had one computer and one
* set of logins that everybody shared. These pin the gateway's half: which computer a seat reaches,
* what the computer is told about whose seat it is, and where the server files what it remembers.
*/
describe("seats on a person's computer", () => {
function onePerPerson() {
const computer = fakeComputer({
routes: {
"/computers/reset": () => Response.json({ reset: true }),
"/computers/stop": () => Response.json({ wasRunning: true }),
},
});
const located: string[] = [];
const locate = computer.provider.locate;
computer.provider.locate = async (seat) => {
located.push(computerKeyText(seat.key));
return locate(seat);
};
const snapshots = createInMemorySnapshotStore();
const { store, rows } = fakeAudit();
const gateway = createComputerGateway({
provider: computer.provider,
fetchImpl: computer.fetchImpl,
auditStore: store,
policy: () => PERMISSIVE,
snapshots,
});
return { ...computer, gateway, located, snapshots, rows };
}
const headersOf = (request: { init?: RequestInit }) =>
request.init?.headers as Record<string, string>;
test("two people on one public Bot reach two computers and keep two snapshots", async () => {
const { gateway, located, snapshots } = onePerPerson();
await gateway.snapshot(personSeat("ada", "pub-bot"));
await gateway.snapshot(personSeat("bo", "pub-bot"));
expect(located).toEqual(["person:ada", "person:bo"]);
expect(await snapshots.load("person:ada/pub-bot")).toBeDefined();
expect(await snapshots.load("person:bo/pub-bot")).toBeDefined();
expect(await snapshots.load("pub-bot")).toBeUndefined();
});
test("one person's two Bots share the computer but not a profile or folder", async () => {
const { gateway, located, requests } = onePerPerson();
await gateway.snapshot(personSeat("ada", "sales"));
await gateway.snapshot(personSeat("ada", "notes"));
expect(located).toEqual(["person:ada", "person:ada"]);
// Inside the computer the Bot picks the profile and folder; the person is the computer itself,
// so it is not sent, and each Bot keeps the profile it has always had there.
expect(
requests.map((request) => headersOf(request)["x-openbot-bot-id"]),
).toEqual(["sales", "notes"]);
expect(
requests.every(
(request) => headersOf(request)["x-openbot-person-id"] === undefined,
),
).toBe(true);
});
test("an isolated Bot reaches a computer of its own", async () => {
const { gateway, located } = onePerPerson();
await gateway.snapshot(botSeat("sales"));
expect(located).toEqual(["bot:sales"]);
});
test("resetting one Bot on a person's computer clears that Bot's profile and nothing else", async () => {
const { gateway, calls, requests, snapshots, rows } = onePerPerson();
await gateway.snapshot(personSeat("ada", "sales"));
await gateway.snapshot(personSeat("ada", "notes"));
expect(
await gateway.resetComputer(personSeat("ada", "sales"), ACTOR),
).toEqual({ cleared: true });
// The computer was asked about one seat, not thrown away with the person's other Bots on it.
expect(calls.filter((call) => call.startsWith("reset:"))).toEqual([]);
const reset = requests.find((request) =>
request.url.endsWith("/computers/reset"),
);
expect(reset && headersOf(reset)["x-openbot-bot-id"]).toBe("sales");
expect(await snapshots.load("person:ada/sales")).toBeUndefined();
expect(await snapshots.load("person:ada/notes")).toBeDefined();
expect(rows.at(-1)?.payload).toMatchObject({
bot: "sales",
computer: "person:ada",
});
});
test("a reset also forgets what was filed under the Bot alone, before computers were per person", async () => {
const { gateway, snapshots } = onePerPerson();
await gateway.snapshot(personSeat("ada", "sales"));
const taken = await snapshots.load("person:ada/sales");
if (!taken) throw new Error("No snapshot was taken.");
// Filed as every snapshot and picture of a page was before: under the Bot, for everybody who used it.
await snapshots.save("sales", taken);
await gateway.resetComputer(personSeat("ada", "sales"), ACTOR);
expect(await snapshots.load("sales")).toBeUndefined();
// An administrator resetting an isolated Bot's computer from the list does the same.
await snapshots.save("notes", taken);
await gateway.resetTarget({ key: { kind: "bot", botId: "notes" } }, ACTOR);
expect(await snapshots.load("notes")).toBeUndefined();
});
test("an administrator resetting a person's whole computer clears every seat on it, and only theirs", async () => {
const { gateway, calls, snapshots } = onePerPerson();
await gateway.snapshot(personSeat("ada", "sales"));
await gateway.snapshot(personSeat("ada", "notes"));
await gateway.snapshot(personSeat("bo", "sales"));
await gateway.resetTarget(
{ key: { kind: "person", personId: "ada" } },
ACTOR,
);
expect(calls).toContain("reset:person:ada");
expect(await snapshots.load("person:ada/sales")).toBeUndefined();
expect(await snapshots.load("person:ada/notes")).toBeUndefined();
expect(await snapshots.load("person:bo/sales")).toBeDefined();
});
test("every action's row names the computer it ran on, for the idle culler", async () => {
const { gateway, rows } = onePerPerson();
await gateway.snapshot(personSeat("ada", "sales"));
await gateway.scroll(personSeat("ada", "sales"), ACTOR, {});
expect(rows.at(-1)?.payload).toMatchObject({
bot: "sales",
computer: "person:ada",
});
});
test("the admin list says whose each computer is", async () => {
const computer = fakeComputer({
locations: [
{ key: { kind: "person", personId: "ada" }, status: "running" },
{ key: { kind: "bot", botId: "sales" }, status: "stopped" },
],
});
const gateway = createComputerGateway({
provider: computer.provider,
fetchImpl: computer.fetchImpl,
auditStore: fakeAudit().store,
policy: () => PERMISSIVE,
people: async () =>
new Map([["ada", { name: "Ada", email: "[email protected]" }]]),
});
expect((await gateway.computers()).computers).toEqual([
expect.objectContaining({
computer: "person:ada",
kind: "person",
personId: "ada",
person: { name: "Ada", email: "[email protected]" },
running: true,
}),
expect.objectContaining({
computer: "bot:sales",
kind: "bot",
botId: "sales",
running: false,
}),
]);
});
});
/**
* The same seats on the one computer everybody shares, where the person has to travel with the Bot
* because the computer cannot tell them apart any other way.
*/
describe("seats on the shared computer", () => {
test("every call names the person as well as the Bot", async () => {
const requests: Headers[] = [];
const gateway = createComputerGateway({
provider: createSharedComputerProvider({
baseUrl: "http://agent-computer:4100",
fetchImpl: (async () => Response.json({ run: "r" })) as never,
}),
fetchImpl: (async (_url: string, init?: RequestInit) => {
requests.push(new Headers(init?.headers));
return Response.json(SNAPSHOT);
}) as unknown as typeof fetch,
auditStore: fakeAudit().store,
policy: () => PERMISSIVE,
});
await gateway.snapshot(personSeat("ada", "pub-bot"));
await gateway.snapshot(personSeat("bo", "pub-bot"));
expect(
requests.map((headers) => [
headers.get("x-openbot-person-id"),
headers.get("x-openbot-bot-id"),
]),
).toEqual([
["ada", "pub-bot"],
["bo", "pub-bot"],
]);
});
});