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.

10.1 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import type { Page } from "playwright";
import { detectChallenge } from "../src/challenge";
import {
  createControl,
  HELP_REQUEST_TTL_MS,
  pageWorthKeeping,
} from "../src/control";
import type { StoredControl } from "../src/control-store";
import { createSessions } from "../src/sessions";

/** A store that survives "restarts": a new control built on it is the computer coming back up. */
function memoryStore() {
  let saved: StoredControl | undefined;
  return {
    load: () => (saved ? structuredClone(saved) : undefined),
    save: (state: StoredControl) => {
      saved = structuredClone(state);
    },
  };
}

function clock(start = "2026-10-12T17:00:00Z") {
  let tick = Date.parse(start);
  return {
    now: () => new Date(tick).toISOString(),
    advance: (ms: number) => {
      tick += ms;
    },
  };
}

const CHALLENGE = "https://chatgpt.com/share/abc";

describe("a handoff remembers the page it is about", () => {
  test("a challenge request records the page it was raised on", () => {
    const time = clock();
    const control = createControl(time.now, { store: memoryStore() });
    const state = control.requestHelp(
      "Complete the challenge.",
      "call-1",
      "cloudflare",
      CHALLENGE,
    );
    expect(state.request?.url).toBe(CHALLENGE);
    expect(control.pageToRestore()).toBe(CHALLENGE);
  });

  test("after the computer restarts, asking again from a blank browser brings the lost page back", () => {
    const time = clock();
    const store = memoryStore();
    createControl(time.now, { store }).requestHelp(
      "Complete the challenge.",
      "call-1",
      "cloudflare",
      CHALLENGE,
    );

    // The process restarts: the waiting request is interrupted, and the browser comes back blank.
    time.advance(20_000);
    const restarted = createControl(time.now, { store });
    expect(restarted.get().request?.status).toBe("interrupted");
    expect(restarted.pageToRestore()).toBeUndefined();

    time.advance(5_000);
    const again = restarted.requestHelp(
      "The browser restarted; please complete the challenge.",
      "call-2",
      "model",
      "about:blank",
    );
    expect(again.request?.url).toBe(CHALLENGE);
    expect(restarted.pageToRestore()).toBe(CHALLENGE);
  });

  test("the page is restorable while a person holds control, and not after they hand back", async () => {
    const time = clock();
    const control = createControl(time.now, { store: memoryStore() });
    const id = control.requestHelp(
      "Solve it.",
      "call-1",
      "cloudflare",
      CHALLENGE,
    ).request!.id;
    await control.take(id);
    expect(control.pageToRestore()).toBe(CHALLENGE);
    control.release(id);
    expect(control.pageToRestore()).toBeUndefined();
  });

  test("an interruption long ago, or one somebody moved on from, does not bring an old page back", () => {
    const time = clock();
    const store = memoryStore();
    createControl(time.now, { store }).requestHelp(
      "Solve it.",
      "call-1",
      "cloudflare",
      CHALLENGE,
    );
    time.advance(1_000);
    const restarted = createControl(time.now, { store });

    time.advance(HELP_REQUEST_TTL_MS + 1_000);
    expect(
      restarted.requestHelp("Something else.", "call-2", "model", "about:blank")
        .request?.url,
    ).toBeUndefined();

    // Cancelled, then asked again: the cancelled request is the latest, so nothing is inherited.
    const latest = restarted.get().request!;
    restarted.cancel(latest.id);
    expect(
      restarted.requestHelp("Another thing.", "call-3", "model", "about:blank")
        .request?.url,
    ).toBeUndefined();
  });
});

const RESET_LINK = "https://bank.example/reset?token=secret";

describe("a stop or reset forgets the page", () => {
  test("a help request after a reset does not reopen the page the reset left", () => {
    const control = createControl(clock().now, { store: memoryStore() });
    control.requestHelp("Reset the password.", "a", "model", RESET_LINK);
    control.interrupt(
      "The computer was reset; the previous task was interrupted.",
    );
    expect(
      control.requestHelp("other", "b", "model", "about:blank").request?.url,
    ).toBeUndefined();
  });

  // The routes close the browser before they interrupt, and a closing browser reaches `renewRun` as
  // a restart that keeps the page. The route's own interrupt has to win; reset renews once more after.
  test("a stop or reset that closes the browser first still forgets it", () => {
    for (const route of ["stop", "reset"] as const) {
      const sessions = createSessions({ isLive: () => false });
      const control = sessions.for("bot").control;
      control.requestHelp("Reset the password.", "a", "model", RESET_LINK);
      sessions.renewRun("bot");
      control.interrupt(
        route === "stop"
          ? "The computer stopped; the previous task was interrupted."
          : "The computer was reset; the previous task was interrupted.",
      );
      if (route === "reset") sessions.renewRun("bot");
      expect(
        control.requestHelp("other", "b", "model", "about:blank").request?.url,
      ).toBeUndefined();
    }
  });

  test("a browser that closes underneath the request still hands its page on", () => {
    const sessions = createSessions({ isLive: () => false });
    const control = sessions.for("bot").control;
    control.requestHelp("Solve it.", "a", "cloudflare", CHALLENGE);
    sessions.renewRun("bot");
    expect(
      control.requestHelp("Again.", "b", "model", "about:blank").request?.url,
    ).toBe(CHALLENGE);
  });
});

describe("a finished request does not keep its page on disk", () => {
  const CODE = "https://example.com/callback?code=abc";

  test("cancelled, completed and expired requests drop the page, in memory and in the store", async () => {
    const time = clock();
    const store = memoryStore();
    const control = createControl(time.now, { store });
    control.cancel(
      control.requestHelp("One.", "c1", "model", CODE).request!.id,
    );
    const completed = control.requestHelp("Two.", "c2", "model", CODE).request!
      .id;
    await control.take(completed);
    control.release(completed);
    control.requestHelp("Three.", "c3", "model", CODE);
    time.advance(HELP_REQUEST_TTL_MS + 1_000);
    expect(control.get().request?.status).toBe("expired");

    const saved = store.load()!;
    expect(saved.requests.map((request) => request.status)).toEqual([
      "cancelled",
      "completed",
      "expired",
    ]);
    expect(saved.requests.map((request) => request.url)).toEqual([
      undefined,
      undefined,
      undefined,
    ]);
    expect(JSON.stringify(saved)).not.toContain("code=abc");
  });

  test("a restart's page leaves the store once the help TTL has passed", () => {
    const time = clock();
    const store = memoryStore();
    createControl(time.now, { store }).requestHelp(
      "Solve it.",
      "c1",
      "cloudflare",
      CHALLENGE,
    );
    time.advance(1_000);
    const restarted = createControl(time.now, { store });
    expect(store.load()!.requests.at(-1)?.url).toBe(CHALLENGE);

    time.advance(HELP_REQUEST_TTL_MS + 1_000);
    restarted.get();
    expect(store.load()!.requests.at(-1)?.url).toBeUndefined();
  });

  test("a record saved before pages were dropped is cleaned when it is read", () => {
    const time = clock();
    const store = memoryStore();
    const at = time.now();
    store.save({
      version: 1,
      holder: "bot",
      since: at,
      resumeSnapshotRequired: false,
      recoveryRequired: false,
      currentRequestId: "old-2",
      requests: [
        {
          id: "old-1",
          reason: "One.",
          source: "model",
          status: "cancelled",
          createdAt: at,
          updatedAt: at,
          finishedAt: at,
          url: CODE,
        },
        {
          id: "old-2",
          reason: "Two.",
          source: "model",
          status: "interrupted",
          createdAt: at,
          updatedAt: at,
          finishedAt: at,
          interruption:
            "The computer was reset; the previous task was interrupted.",
          url: RESET_LINK,
        },
      ],
      aliases: {},
    });

    time.advance(1_000);
    const control = createControl(time.now, { store });
    const saved = JSON.stringify(store.load());
    expect(saved).not.toContain("code=abc");
    expect(saved).not.toContain("token=secret");
    expect(
      control.requestHelp("other", "b", "model", "about:blank").request?.url,
    ).toBeUndefined();
  });
});

describe("only a real page is worth keeping", () => {
  test("http and https are kept; blank, browser and script pages are not", () => {
    expect(pageWorthKeeping(CHALLENGE)).toBe(CHALLENGE);
    expect(pageWorthKeeping("http://example.com/a")).toBe(
      "http://example.com/a",
    );
    expect(pageWorthKeeping("about:blank")).toBeUndefined();
    expect(pageWorthKeeping("chrome://newtab/")).toBeUndefined();
    expect(pageWorthKeeping("javascript:alert(1)")).toBeUndefined();
    expect(
      pageWorthKeeping(`https://example.com/${"a".repeat(3000)}`),
    ).toBeUndefined();
    expect(pageWorthKeeping(undefined)).toBeUndefined();
  });

  test("a spent Cloudflare challenge token is not kept, the rest of the address is", () => {
    expect(
      pageWorthKeeping("https://chatgpt.com/?__cf_chl_rt_tk=spent-1.0.1.1-abc"),
    ).toBe("https://chatgpt.com/");
    expect(
      pageWorthKeeping(
        "https://chatgpt.com/share/abc?__cf_chl_tk=x&ref=mail&__cf_chl_f_tk=y",
      ),
    ).toBe("https://chatgpt.com/share/abc?ref=mail");
  });
});

describe("a detected challenge remembers its page", () => {
  test("the handoff a Cloudflare challenge raises carries the challenge's address", async () => {
    const control = createControl();
    const page = {
      url: () => "https://chatgpt.com/share/abc",
    } as unknown as Page;
    const challenge = await detectChallenge(page, control, {
      cfMitigated: "challenge",
      toolCallId: "call-1",
    });
    expect(challenge?.kind).toBe("cloudflare");
    expect(control.get().request?.url).toBe("https://chatgpt.com/share/abc");
    expect(control.pageToRestore()).toBe("https://chatgpt.com/share/abc");
  });
});