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 {
createHostAccessBroker,
HostAccessRefusedError,
} from "../src/host-access/broker";
import type { HostAccessDesktopOperation } from "../src/host-access/schema";
describe("host access broker", () => {
test("a folder grant request queues a native picker operation and stores only the returned opaque grant", async () => {
const broker = createHostAccessBroker();
const pending = broker.requestFolderGrant({
botId: "bot-a",
botName: "Research Bot",
actorId: "user-a",
});
const lease = broker.nextDesktopOperation();
expect(lease?.operations[0]).toMatchObject({
kind: "choose_folder",
botId: "bot-a",
botName: "Research Bot",
actorId: "user-a",
writable: false,
});
broker.resolveDesktopOperation({
operationId: lease!.operations[0]!.operationId,
ok: true,
grant: {
grantId: "native-grant-1",
displayName: "Project",
},
});
await expect(pending).resolves.toEqual({
id: "native-grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
expect(broker.statusFor("user-a").grants).toEqual([
{
id: "native-grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
},
]);
});
test("host operations are tied to the selected Bot and actor", async () => {
const broker = createHostAccessBroker();
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
await expect(
broker.callHost({
kind: "list_files",
botId: "bot-b",
actorId: "user-a",
grantId: "grant-1",
relativePath: ".",
}),
).rejects.toBeInstanceOf(HostAccessRefusedError);
await expect(
broker.callHost({
kind: "list_files",
botId: "bot-a",
actorId: "user-b",
grantId: "grant-1",
relativePath: ".",
}),
).rejects.toBeInstanceOf(HostAccessRefusedError);
});
test("read-only folder grants still dispatch writes and commands for native per-operation confirmation", async () => {
const broker = createHostAccessBroker();
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const write = broker.callHost({
kind: "write_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
content: "draft",
});
const writeLease = broker.nextDesktopOperation();
expect(writeLease?.operations[0]).toMatchObject({
kind: "write_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
content: "draft",
});
broker.resolveDesktopOperation({
operationId: writeLease!.operations[0]!.operationId,
ok: true,
result: { written: true },
});
await expect(write).resolves.toEqual({ written: true });
const command = broker.callHost({
kind: "run_command",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
command: "pwd",
});
const commandLease = broker.nextDesktopOperation();
expect(commandLease?.operations[0]).toMatchObject({
kind: "run_command",
command: "pwd",
});
broker.resolveDesktopOperation({
operationId: commandLease!.operations[0]!.operationId,
ok: true,
result: { stdout: "/workspace" },
});
await expect(command).resolves.toEqual({ stdout: "/workspace" });
});
test("revoking a grant rejects queued and inflight calls and queues native cancellation", async () => {
const broker = createHostAccessBroker();
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const queued = broker.callHost({
kind: "list_files",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: ".",
});
const inflight = broker.callHost({
kind: "read_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
});
const lease = broker.nextDesktopOperation();
expect(lease?.operations[0]).toMatchObject({
kind: "list_files",
} satisfies Partial<HostAccessDesktopOperation>);
broker.revokeGrant("grant-1", "user-a");
const rejected = await Promise.allSettled([queued, inflight]);
expect(rejected.map((entry) => entry.status)).toEqual([
"rejected",
"rejected",
]);
expect(
rejected.map((entry) =>
entry.status === "rejected" && entry.reason instanceof Error
? entry.reason.message
: "",
),
).toEqual([
"That folder grant was revoked before the operation finished.",
"That folder grant was revoked before the operation finished.",
]);
const firstCancel = broker.nextDesktopOperation()?.operations[0];
const secondCancel = broker.nextDesktopOperation()?.operations[0];
expect([firstCancel?.kind, secondCancel?.kind]).toEqual([
"cancel",
"cancel",
]);
expect(broker.statusFor("user-a").grants[0]?.revoked).toBe(true);
});
test("stale or replayed desktop results cannot recreate grants or finish cancelled operations", async () => {
const broker = createHostAccessBroker();
const pending = broker.requestFolderGrant({
botId: "bot-a",
botName: "Bot A",
actorId: "user-a",
});
const lease = broker.nextDesktopOperation();
broker.resolveDesktopOperation({
operationId: lease!.operations[0]!.operationId,
ok: false,
error: "cancelled",
});
await expect(pending).rejects.toThrow("cancelled");
broker.resolveDesktopOperation({
operationId: lease!.operations[0]!.operationId,
ok: true,
grant: { grantId: "grant-late", displayName: "Late" },
});
expect(broker.statusFor("user-a").grants).toEqual([]);
});
test("desktop lease expiry marks offline, revokes grants, rejects operations, and returns cancellation on reconnect", async () => {
let clock = 1_000;
const broker = createHostAccessBroker(() => clock);
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const running = broker.callHost({
kind: "read_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
});
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "read_file",
});
expect(broker.statusFor("user-a").connected).toBe(true);
clock += 15_001;
expect(broker.statusFor("user-a").connected).toBe(false);
const disconnected = await Promise.allSettled([running]);
expect(disconnected[0]?.status).toBe("rejected");
expect(
disconnected[0]?.status === "rejected" &&
disconnected[0].reason instanceof Error
? disconnected[0].reason.message
: "",
).toContain("disconnected");
expect(broker.statusFor("user-a").grants[0]?.revoked).toBe(true);
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "cancel",
grantId: "grant-1",
});
});
test("desktop lease expiry autonomously rejects inflight calls without another broker read", async () => {
const broker = createHostAccessBroker(Date.now, {
desktopLeaseMs: 10,
operationTtlMs: 1_000,
});
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const running = broker.callHost({
kind: "read_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
});
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "read_file",
});
await expect(running).rejects.toThrow("disconnected");
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "cancel",
grantId: "grant-1",
});
});
test("host approval operations expire autonomously and cannot execute stale native results", async () => {
const broker = createHostAccessBroker(Date.now, {
desktopLeaseMs: 1_000,
operationTtlMs: 10,
});
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const pending = broker.callHost({
kind: "write_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
content: "draft",
});
const lease = broker.nextDesktopOperation();
const operation = lease!.operations[0]!;
expect(operation).toMatchObject({
kind: "write_file",
grantId: "grant-1",
});
expect(typeof operation.expiresAt).toBe("number");
expect(operation.expiresAt! - Date.now()).toBeLessThanOrEqual(10);
await expect(pending).rejects.toThrow("expired");
broker.resolveDesktopOperation({
operationId: operation.operationId,
ok: true,
result: { written: true },
});
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "cancel",
grantId: "grant-1",
});
});
test("Stop revokes all owner grants, cancels outstanding calls, and queues native stop", async () => {
const broker = createHostAccessBroker();
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const running = broker.callHost({
kind: "read_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
});
broker.stop("user-a");
const stopped = await Promise.allSettled([running]);
expect(stopped[0]?.status).toBe("rejected");
expect(
stopped[0]?.status === "rejected" && stopped[0].reason instanceof Error
? stopped[0].reason.message
: "",
).toContain("stopped");
expect(broker.statusFor("user-a").grants[0]?.revoked).toBe(true);
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "cancel",
});
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "stop",
actorId: "user-a",
});
});
test("a cancel nobody collects does not stay pending for the life of the process", async () => {
const broker = createHostAccessBroker(Date.now, {
// Long enough that the lease is not what ends the operation, so this is the operation's
// own timeout queuing the cancel.
desktopLeaseMs: 60_000,
operationTtlMs: 40,
});
broker.rememberGrant({
id: "grant-1",
botId: "bot-a",
actorId: "user-a",
displayName: "Project",
revoked: false,
});
const running = broker.callHost({
kind: "read_file",
botId: "bot-a",
actorId: "user-a",
grantId: "grant-1",
relativePath: "notes.txt",
});
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "read_file",
});
// It runs out its own time, which queues a cancel for the desktop that has to stop
// working on it.
await Promise.allSettled([running]);
await new Promise((resolve) => setTimeout(resolve, 10));
expect(broker.statusFor("user-a").pending).toHaveLength(1);
expect(broker.statusFor("user-a").pending[0]?.kind).toBe("cancel");
// That desktop never comes back for it. The cancel cannot outlive the chance to deliver
// it: nothing else ever removes this entry, so `operations` grew by one per abandoned
// operation and `statusFor` kept reporting it to the person as pending.
await new Promise((resolve) => setTimeout(resolve, 150));
expect(broker.statusFor("user-a").pending).toEqual([]);
}, 10_000);
test("a stop nobody collects does not stay pending for the life of the process", async () => {
const broker = createHostAccessBroker(Date.now, {
// Long enough that the lease is not what ends the operation, so this is the operation's
// own timeout giving up on the stop.
desktopLeaseMs: 60_000,
operationTtlMs: 40,
});
broker.stop("user-a");
expect(broker.nextDesktopOperation()?.operations[0]).toMatchObject({
kind: "stop",
actorId: "user-a",
});
// That desktop never comes back for it. A stop is addressed to a worker that may never
// answer, exactly as a cancel is, so it cannot outlive the chance to deliver it: nothing else
// ever removed this entry, so `operations` grew by one per press of Stop and `statusFor` kept
// reporting it to the person as pending.
await new Promise((resolve) => setTimeout(resolve, 150));
expect(broker.statusFor("user-a").pending).toEqual([]);
}, 10_000);
test("a second Stop neither drops the queued stop nor rejects a promise nobody holds", async () => {
const broker = createHostAccessBroker(Date.now, {
desktopLeaseMs: 60_000,
operationTtlMs: 1_000,
});
const unhandled: unknown[] = [];
const onUnhandled = (reason: unknown) => {
unhandled.push(reason);
};
process.on("unhandledRejection", onUnhandled);
try {
broker.stop("user-a");
broker.stop("user-a");
// Both stops are still queued for a desktop that has not collected either. The second must
// not fail the first: a stop is the instruction that makes the desktop stop, so failing it
// would withdraw the instruction the person just asked for.
const pending = broker.statusFor("user-a").pending;
expect(pending).toHaveLength(2);
expect(pending.every((operation) => operation.kind === "stop")).toBe(
true,
);
// And nothing rejects. The stop used to be built by `enqueue` and discarded with `void`, so
// the promise behind it had no handler attached, and failing it rejected that promise into
// the void -- which this process treats as fatal.
await new Promise((resolve) => setTimeout(resolve, 50));
expect(unhandled).toEqual([]);
} finally {
process.off("unhandledRejection", onUnhandled);
}
}, 10_000);
});