Skip to content

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.

14.3 KB
Raw Blame
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);
});