@aloud/runner 0.2.0

package/src/protocol/client.ts

@@ -0,0 +1,170 @@
+import { scrubToken } from "../config/credentials";
+
+/**
+ * The runner's only route to the server.
+ *
+ * Two properties matter more than anything else here.
+ *
+ * The origin is pinned and every request sets `redirect: "error"`, so a server that answers with a
+ * 302 cannot walk the runner's token to somewhere else.
+ *
+ * And transport failures are retried for up to sixty seconds, deliberately under the server's
+ * ninety-second heartbeat grace. Beyond that the lease is gone and has probably been handed to
+ * another runner, so continuing would mean finishing a study into a void.
+ */
+export class LeaseLostError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LeaseLostError";
+  }
+}
+
+export class ServerError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly body: unknown,
+  ) {
+    super(message);
+    this.name = "ServerError";
+  }
+}
+
+export class OfflineError extends Error {
+  constructor(readonly seconds: number) {
+    super(`No connection to the server after ${seconds} seconds.`);
+    this.name = "OfflineError";
+  }
+}
+
+export interface RunnerClientOptions {
+  server: string;
+  token: string;
+  fetchImpl?: typeof fetch;
+  /** How long to keep retrying a transport failure. Must stay under the server's lease grace. */
+  offlineHorizonMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+  /** Called when a request starts failing and again when it recovers, so the terminal can say so. */
+  onConnectionChange?: (state: "lost" | "restored", detail: string) => void;
+}
+
+export const DEFAULT_OFFLINE_HORIZON_MS = 60_000;
+
+export interface RequestOptions {
+  method?: "GET" | "POST" | "PUT";
+  body?: unknown;
+  raw?: { bytes: Uint8Array; contentType: string };
+  signal?: AbortSignal;
+  /** A poll should fail fast and try again later rather than blocking for a minute. */
+  retry?: boolean;
+}
+
+export class RunnerClient {
+  private readonly fetchImpl: typeof fetch;
+  private readonly horizonMs: number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private offline = false;
+
+  constructor(private readonly options: RunnerClientOptions) {
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.horizonMs = options.offlineHorizonMs ?? DEFAULT_OFFLINE_HORIZON_MS;
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+
+  get server(): string {
+    return this.options.server;
+  }
+
+  /**
+   * One request, with transport retries.
+   *
+   * HTTP status codes are *not* retried here: they are turned into errors and handed up, because
+   * the model gateway already has its own backoff for rate limits and the run loop needs to see a
+   * 401 immediately rather than nine times.
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<{ status: number; body: T }> {
+    const url = new URL(path, this.options.server + "/").toString();
+    if (!url.startsWith(this.options.server + "/")) {
+      throw new Error(`Refusing to send credentials to ${url}: this runner is pinned to ${this.options.server}.`);
+    }
+
+    const started = Date.now();
+    let attempt = 0;
+
+    for (;;) {
+      try {
+        const response = await this.fetchImpl(url, {
+          method: options.method ?? "GET",
+          // A redirect is how a token walks off its origin. There is no legitimate one here.
+          redirect: "error",
+          headers: {
+            authorization: `Bearer ${this.options.token}`,
+            accept: "application/json",
+            ...(options.raw
+              ? { "content-type": options.raw.contentType }
+              : options.body !== undefined
+                ? { "content-type": "application/json" }
+                : {}),
+          },
+          ...(options.raw
+            ? { body: options.raw.bytes as unknown as BodyInit }
+            : options.body !== undefined
+              ? { body: JSON.stringify(options.body) }
+              : {}),
+          ...(options.signal ? { signal: options.signal } : {}),
+        });
+
+        if (this.offline) {
+          this.offline = false;
+          this.options.onConnectionChange?.("restored", "Connection is back.");
+        }
+
+        const body = await parseBody<T>(response);
+
+        if (response.status === 401) {
+          throw new LeaseLostError("This runner is no longer authorised. Run `aloud login` again.");
+        }
+        if (response.status >= 400) {
+          throw new ServerError(messageFrom(body, response.status), response.status, body);
+        }
+        return { status: response.status, body };
+      } catch (error) {
+        if (error instanceof LeaseLostError || error instanceof ServerError) throw error;
+        if (options.signal?.aborted) throw error;
+        if (options.retry === false) throw error;
+
+        const elapsed = Date.now() - started;
+        if (elapsed >= this.horizonMs) {
+          this.offline = true;
+          throw new OfflineError(Math.round(this.horizonMs / 1000));
+        }
+
+        if (!this.offline) {
+          this.offline = true;
+          this.options.onConnectionChange?.("lost", scrubToken(String(error), this.options.token));
+        }
+
+        // 500ms, 1s, 2s, 4s, capped at 8s. Under the horizon this is about a dozen attempts.
+        await this.sleep(Math.min(8_000, 500 * 2 ** attempt));
+        attempt += 1;
+      }
+    }
+  }
+}
+
+async function parseBody<T>(response: Response): Promise<T> {
+  const type = response.headers.get("content-type") ?? "";
+  if (type.includes("application/json")) {
+    return (await response.json().catch(() => null)) as T;
+  }
+  return (await response.text().catch(() => "")) as unknown as T;
+}
+
+function messageFrom(body: unknown, status: number): string {
+  if (body && typeof body === "object" && "error" in body) {
+    const message = (body as { error?: unknown }).error;
+    if (typeof message === "string" && message.length > 0) return message;
+  }
+  if (typeof body === "string" && body.length > 0 && body.length < 400) return body;
+  return `The server answered ${status}.`;
+}

package/src/run/event-shipper.ts

@@ -0,0 +1,132 @@
+import type { RunEvent } from "@aloud/core";
+import { LeaseLostError, type RunnerClient } from "../protocol/client";
+
+/**
+ * Ships run events to the server, so the study room in the browser can show progress.
+ *
+ * The response to an event batch carries the heartbeat payload, which means a run that is producing
+ * events heartbeats implicitly about once a second. That drops cancellation latency from ten
+ * seconds to roughly one and halves the request count, which on a serverless platform is money.
+ * The dedicated heartbeat then only fires when nothing has flowed for a while, such as during a
+ * long synthesis call.
+ */
+export interface HeartbeatState {
+  leaseStatus: string;
+  cancelRequested: boolean;
+  spentCents: number;
+}
+
+export interface EventShipperDeps {
+  client: RunnerClient;
+  leaseId: string;
+  onState: (state: HeartbeatState) => void;
+  onLeaseLost: (reason: string) => void;
+  flushIntervalMs?: number;
+  batchSize?: number;
+  /** Beyond this the oldest non-terminal events are dropped rather than growing without bound. */
+  bufferLimit?: number;
+}
+
+/** These say the run finished. Losing one leaves a study room spinning forever. */
+const TERMINAL = new Set(["run.status_changed", "run.failed", "report.version_created"]);
+
+export class EventShipper {
+  private buffer: RunEvent[] = [];
+  private timer: NodeJS.Timeout | null = null;
+  private sending: Promise<void> | null = null;
+  private dropped = 0;
+  private lastContactMs = Date.now();
+  private stopped = false;
+
+  constructor(private readonly deps: EventShipperDeps) {}
+
+  get millisecondsSinceContact(): number {
+    return Date.now() - this.lastContactMs;
+  }
+
+  push(event: RunEvent): void {
+    if (this.stopped) return;
+    this.buffer.push(event);
+
+    if (this.buffer.length > (this.deps.bufferLimit ?? 5_000)) {
+      const index = this.buffer.findIndex((candidate) => !TERMINAL.has(candidate.type));
+      if (index >= 0) {
+        this.buffer.splice(index, 1);
+        this.dropped += 1;
+      }
+    }
+
+    if (TERMINAL.has(event.type) || this.buffer.length >= (this.deps.batchSize ?? 50)) {
+      void this.flush();
+      return;
+    }
+    this.schedule();
+  }
+
+  private schedule(): void {
+    if (this.timer || this.stopped) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.deps.flushIntervalMs ?? 1_000);
+    this.timer.unref?.();
+  }
+
+  /** Sends whatever is buffered. Safe to call at any time; only one send is ever in flight. */
+  async flush(): Promise<void> {
+    if (this.sending) return this.sending;
+    if (this.buffer.length === 0) return;
+
+    const batch = this.buffer;
+    this.buffer = [];
+
+    this.sending = (async () => {
+      try {
+        const { body } = await this.deps.client.request<HeartbeatState>("api/runner/events", {
+          method: "POST",
+          body: { leaseId: this.deps.leaseId, events: batch },
+        });
+        this.lastContactMs = Date.now();
+        // The server dedupes on `event.id`, which is already `${runId}:${sequence}`, so a retried
+        // batch is harmless.
+        if (body) this.deps.onState(body);
+      } catch (error) {
+        if (error instanceof LeaseLostError) {
+          this.deps.onLeaseLost(error.message);
+          return;
+        }
+        // Put them back at the front so ordering survives a blip.
+        this.buffer = [...batch, ...this.buffer];
+      } finally {
+        this.sending = null;
+      }
+    })();
+
+    return this.sending;
+  }
+
+  /** Called when nothing has been sent for a while, so the lease does not lapse mid-synthesis. */
+  async heartbeat(): Promise<void> {
+    try {
+      const { body } = await this.deps.client.request<HeartbeatState>("api/runner/heartbeat", {
+        method: "POST",
+        body: { leaseId: this.deps.leaseId },
+      });
+      this.lastContactMs = Date.now();
+      if (body) this.deps.onState(body);
+    } catch (error) {
+      if (error instanceof LeaseLostError) this.deps.onLeaseLost(error.message);
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    await this.flush();
+    this.stopped = true;
+  }
+
+  get droppedCount(): number {
+    return this.dropped;
+  }
+}

package/src/run/execute.ts

@@ -0,0 +1,344 @@
+import {
+  EvidencePipeline,
+  ModelGateway,
+  RunCoordinator,
+  makeBudgetGuard,
+  type DivergenceTrace,
+  type RunOutcome,
+} from "@aloud/engine";
+import { PlaywrightWorkerFactory } from "@aloud/engine/browser/playwright-worker";
+import { DEFAULT_SINGLE_PERSONA_BASELINE, measureDivergence } from "@aloud/eval/divergence";
+import { PromptStage, systemClock, type JobLease, type PromptStage as Stage, type StudyRun } from "@aloud/core";
+import { LeaseLostError, type RunnerClient } from "../protocol/client";
+import { BlobSpool } from "../protocol/blob-spool";
+import { ProxyModelAdapter, type StageRouting } from "../model/proxy-adapter";
+import { UploadingObjectStore } from "../evidence/uploading-store";
+import { EventShipper, type HeartbeatState } from "./event-shipper";
+import { sanitiseSnapshot, SnapshotRefused } from "./sanitise";
+import { GuardedWorkerFactory } from "./guarded-workers";
+import type { LocalPolicy } from "../config/policy";
+
+/**
+ * One lease, start to finish.
+ *
+ * The important structural point is that the run executes in a single process that owns it from
+ * claim to complete. That is what makes `liveRuns`, the in-memory usage array and per-run
+ * cancellation correct here, where on a serverless control plane they silently break across
+ * instances.
+ */
+export interface ExecuteDeps {
+  client: RunnerClient;
+  lease: JobLease;
+  /**
+   * The run row this lease is for.
+   *
+   * Carried in the claim response rather than reconstructed here. The report's methodology section
+   * quotes the run's dates and budget, and a runner inventing them would produce a report that
+   * quietly disagrees with the database it is written into.
+   */
+  run: StudyRun;
+  /** The product the run's issues are filed against, so a rerun compares against the same history. */
+  productId: string;
+  routing: Partial<Record<Stage, StageRouting>>;
+  local: LocalPolicy;
+  spool: BlobSpool;
+  ui: RunReporter;
+  /** Injected by tests. Real runs drive Chromium. */
+  workers?: ConstructorParameters<typeof GuardedWorkerFactory>[0];
+  /** Injected by tests, so a whole study can run without a browser or a clock. */
+  now?: () => number;
+}
+
+export interface RunReporter {
+  studyStarted(input: { name: string; goal: string; startUrl: string; participants: number; runId: string }): void;
+  sessionProgress(personaName: string, detail: string): void;
+  sessionFinished(personaName: string, detail: string): void;
+  synthesising(): void;
+  finished(summary: { participants: number; succeeded: number; costCents: number; runId: string }): void;
+  failed(reason: string): void;
+  note(message: string): void;
+  connection(state: "lost" | "restored", detail: string): void;
+}
+
+export interface ExecuteResult {
+  status: "completed" | "failed" | "canceled";
+  reason: string | null;
+  costCents: number;
+}
+
+const HEARTBEAT_INTERVAL_MS = 10_000;
+/** Over this and the process was asleep, not merely slow. The lease is long gone. */
+const SLEEP_THRESHOLD_MS = 120_000;
+
+export async function executeLease(deps: ExecuteDeps): Promise<ExecuteResult> {
+  const clock = systemClock;
+  const now = deps.now ?? (() => Date.now());
+
+  // Nothing from the wire decides what may be opened.
+  let effective;
+  try {
+    effective = await sanitiseSnapshot(deps.lease.snapshot, deps.lease, deps.local, clock.nowIso());
+  } catch (error) {
+    const reason = error instanceof SnapshotRefused ? error.message : (error as Error).message;
+    deps.ui.failed(reason);
+    await complete(deps.client, deps.lease.id, reason);
+    return { status: "failed", reason, costCents: 0 };
+  }
+
+  const snapshot = effective.snapshot;
+  const store = new UploadingObjectStore({
+    client: deps.client,
+    spool: deps.spool,
+    leaseId: deps.lease.id,
+    clock,
+    onError: (key, error) => deps.ui.note(`Could not upload evidence ${key}: ${error.message}`),
+  });
+
+  let budgetExhausted: string | null = null;
+  let leaseLost: string | null = null;
+  let cancelled: string | null = null;
+  // Declared before the coordinator exists so the adapters can reach it. All three ways a run can
+  // be stopped - a heartbeat saying so, a proxy call refused, a signal on this machine - funnel
+  // through this one function.
+  let coordinator: RunCoordinator | null = null;
+  const stopRun = (reason: string) => {
+    if (cancelled) return;
+    cancelled = reason;
+    coordinator?.cancel(reason);
+  };
+
+  const adapters = new Map<Stage, ProxyModelAdapter>();
+  for (const stage of PromptStage.options) {
+    const routing = deps.routing[stage] ?? deps.routing.participant_decision;
+    if (!routing) continue;
+    adapters.set(
+      stage,
+      new ProxyModelAdapter({
+        client: deps.client,
+        spool: deps.spool,
+        leaseId: deps.lease.id,
+        stage,
+        routing,
+        onBudgetExhausted: (message) => {
+          budgetExhausted ??= message;
+        },
+        onLeaseLost: (message) => {
+          leaseLost ??= message;
+          stopRun(message);
+        },
+      }),
+    );
+  }
+
+  const gateway = new ModelGateway({
+    route: (stage) => {
+      const adapter = adapters.get(stage);
+      if (!adapter) throw new Error(`The server did not say which model to use for ${stage}.`);
+      return adapter;
+    },
+    clock,
+    // Advisory only. The server enforces the real ceiling at the proxy, which is the one place
+    // money is actually spent.
+    budget: makeBudgetGuard(null),
+  });
+
+  const workers = new GuardedWorkerFactory(
+    deps.workers ?? new PlaywrightWorkerFactory(),
+    effective.allowedHosts,
+    deps.local,
+  );
+
+  coordinator = new RunCoordinator(
+    {
+      // The sanitised snapshot, not the one the run row carries: what may be opened is decided on
+      // this machine.
+      run: { ...deps.run, snapshot },
+      snapshot,
+      productId: deps.productId,
+    },
+    {
+      gateway,
+      workers,
+      evidence: new EvidencePipeline(store, clock),
+      clock,
+      measureDivergence: (traces: DivergenceTrace[]) => {
+        const report = measureDivergence(traces);
+        return {
+          score: report.score,
+          baseline: DEFAULT_SINGLE_PERSONA_BASELINE,
+          passed: report.score > DEFAULT_SINGLE_PERSONA_BASELINE,
+        };
+      },
+      // The server does not know how much memory this machine has, so the smaller of the two wins.
+      maxConcurrentSessions: Math.min(deps.local.maxConcurrentSessions, snapshot.cast.length || 1),
+      onSessionResult: async (result, session) => {
+        deps.ui.sessionFinished(session.persona.name, describeOutcome(result));
+        // Checkpoint as each participant finishes. A ten-minute run that dies at minute nine used
+        // to lose every moment in it.
+        await postPart(deps.client, deps.lease.id, "sessions", [session]);
+        await postPart(deps.client, deps.lease.id, "moments", result.moments);
+        await postPart(deps.client, deps.lease.id, "evidence", result.evidenceAssets);
+      },
+    },
+  );
+
+  const shipper = new EventShipper({
+    client: deps.client,
+    leaseId: deps.lease.id,
+    onState: (state: HeartbeatState) => {
+      if (state.cancelRequested) stopRun("Stopped from the web app");
+      else if (state.leaseStatus !== "claimed") stopRun(`This lease is ${state.leaseStatus}`);
+    },
+    onLeaseLost: (reason) => {
+      leaseLost ??= reason;
+      stopRun(reason);
+    },
+  });
+
+  const unsubscribe = coordinator.events.subscribe((event) => {
+    shipper.push(event);
+    if (event.type === "session.moment_recorded") {
+      const data = event.data as { sessionId?: string; sequence?: number };
+      deps.ui.sessionProgress(String(data.sessionId ?? ""), `step ${(data.sequence ?? 0) + 1}`);
+    }
+    if (event.type === "synthesis.started") deps.ui.synthesising();
+  });
+
+  deps.ui.studyStarted({
+    name: String(snapshot.study.name ?? "this study"),
+    goal: String(snapshot.study.goal ?? ""),
+    startUrl: String(snapshot.study.startUrl),
+    participants: snapshot.cast.length,
+    runId: deps.lease.runId,
+  });
+
+  let lastTickMs = now();
+  const heartbeat = setInterval(() => {
+    const elapsed = now() - lastTickMs;
+    lastTickMs = now();
+    // A closed laptop does not fire timers. On wake the clock has jumped and the sockets are dead;
+    // detecting it explicitly beats waiting for a socket timeout to work it out.
+    if (elapsed > SLEEP_THRESHOLD_MS) {
+      stopRun(`This machine was asleep for ${Math.round(elapsed / 60_000)} minutes`);
+      return;
+    }
+    if (shipper.millisecondsSinceContact >= HEARTBEAT_INTERVAL_MS) void shipper.heartbeat();
+  }, HEARTBEAT_INTERVAL_MS);
+  heartbeat.unref?.();
+
+  let outcome: RunOutcome | null = null;
+  let failure: string | null = null;
+
+  try {
+    outcome = await coordinator.run();
+    // `run()` catches its own failures and returns an outcome carrying the failed status rather
+    // than throwing, so the absence of a throw is not success. Reading the status is what stops a
+    // failed study being reported as finished and the lease completed with no reason.
+    if (outcome.run.status === "failed") {
+      failure = failureFrom(outcome) ?? "The study failed during synthesis.";
+    }
+  } catch (error) {
+    failure = error instanceof LeaseLostError ? error.message : (error as Error).message;
+  } finally {
+    clearInterval(heartbeat);
+    unsubscribe();
+  }
+
+  // Evidence is throughput rather than latency, so it lags the run. This is where it catches up.
+  const flushed = await store.flush();
+  if (flushed.failed > 0) {
+    deps.ui.note(`${flushed.failed} screenshots did not upload. The report will say which.`);
+  }
+
+  if (outcome && !leaseLost) {
+    // Same order as the server's own persistence: findings before the report, because the report
+    // holds ordered identifiers that have to resolve to something.
+    await postPart(deps.client, deps.lease.id, "judgments", outcome.judgments);
+    await postPart(deps.client, deps.lease.id, "issues", outcome.issues);
+    await postPart(deps.client, deps.lease.id, "findings", outcome.findings);
+    if (outcome.reportVersion) {
+      await postPart(deps.client, deps.lease.id, "report", [outcome.reportVersion]);
+    }
+    await postPart(deps.client, deps.lease.id, "usage", [...gateway.usageEvents]);
+  }
+
+  await shipper.stop();
+
+  // A study every participant failed out of because the workspace ran out of allowance is not a
+  // completed study with a nought-per-cent success rate, whatever the coordinator concluded.
+  if (!failure && !cancelled && budgetExhausted) failure = budgetExhausted;
+
+  const status: ExecuteResult["status"] = cancelled ? "canceled" : failure ? "failed" : "completed";
+  const reason = cancelled ?? failure;
+
+  if (!leaseLost) {
+    await complete(deps.client, deps.lease.id, reason ?? undefined);
+  }
+
+  const costCents = outcome?.costCents ?? gateway.totalCostCents();
+  if (status === "completed" && outcome) {
+    deps.ui.finished({
+      participants: outcome.sessions.length,
+      succeeded: outcome.sessionResults.filter((r) => r.selfReportedOutcome === "success").length,
+      costCents,
+      runId: deps.lease.runId,
+    });
+  } else if (reason) {
+    deps.ui.failed(reason);
+  }
+
+  return { status, reason, costCents };
+}
+
+async function complete(client: RunnerClient, leaseId: string, failureReason?: string): Promise<void> {
+  try {
+    await client.request("api/runner/complete", {
+      method: "POST",
+      body: { leaseId, ...(failureReason ? { failureReason } : {}) },
+    });
+  } catch {
+    // Nothing useful to do. The lease expires on its own after the heartbeat grace.
+  }
+}
+
+/**
+ * Posts one part of the outcome.
+ *
+ * Never the whole thing in one body: a three-participant study is hundreds of kilobytes of JSON
+ * and a five-participant one would breach the 4.5 MB serverless request limit. Each part is
+ * idempotent on the record ids the server already keys on, so a retry is free.
+ */
+async function postPart(client: RunnerClient, leaseId: string, part: string, records: readonly unknown[]): Promise<void> {
+  if (records.length === 0) return;
+  const pageSize = part === "moments" ? 25 : part === "evidence" ? 100 : records.length;
+
+  for (let cursor = 0; cursor < records.length; cursor += pageSize) {
+    try {
+      await client.request("api/runner/outcome", {
+        method: "POST",
+        body: { leaseId, part, cursor, payload: records.slice(cursor, cursor + pageSize) },
+      });
+    } catch (error) {
+      if (error instanceof LeaseLostError) return;
+      throw error;
+    }
+  }
+}
+
+/** The message the coordinator recorded when it gave up, so the terminal can say what happened. */
+function failureFrom(outcome: RunOutcome): string | null {
+  for (const event of outcome.events.all()) {
+    if (event.type === "run.failed") {
+      const message = (event.data as { message?: unknown }).message;
+      if (typeof message === "string") return message;
+    }
+  }
+  return null;
+}
+
+function describeOutcome(result: { status: string; selfReportedOutcome?: string | null; selfReportedReason?: string | null }): string {
+  if (result.status === "error") return "the browser stopped unexpectedly";
+  if (result.selfReportedOutcome === "success") return "reached the goal";
+  if (result.selfReportedOutcome === "abandoned") return result.selfReportedReason ?? "gave up";
+  return result.selfReportedOutcome ?? "finished";
+}

package/src/run/guarded-workers.ts

@@ -0,0 +1,43 @@
+import type { BrowserWorker, BrowserWorkerFactory, BrowserWorkerOptions } from "@aloud/engine";
+import type { LocalPolicy } from "../config/policy";
+
+/**
+ * Belt and braces around the browser factory.
+ *
+ * `sanitiseSnapshot` is the policy; this is the assertion. Every `create` is re-checked against the
+ * effective allowlist rather than trusted to have come from a sanitised snapshot, so if the two
+ * ever disagree the answer is a thrown error and not an opened browser.
+ *
+ * It also owns `allowPrivateNetwork`, which the coordinator would otherwise derive from
+ * `snapshot.environment.type` - a field that arrives from the server.
+ */
+export class GuardedWorkerFactory implements BrowserWorkerFactory {
+  constructor(
+    private readonly inner: BrowserWorkerFactory,
+    private readonly allowedHosts: readonly string[],
+    private readonly local: LocalPolicy,
+  ) {}
+
+  async create(id: string, options: BrowserWorkerOptions): Promise<BrowserWorker> {
+    const asked = [...options.allowedDomains].sort();
+    const permitted = [...this.allowedHosts].sort();
+
+    if (asked.length !== permitted.length || asked.some((host, index) => host !== permitted[index])) {
+      throw new Error(
+        `Refusing to open a browser for ${asked.join(", ") || "nothing"}: this lease permits ` +
+          `${permitted.join(", ")}. Nothing between the lease and here may widen that.`,
+      );
+    }
+
+    return this.inner.create(id, {
+      ...options,
+      allowedDomains: permitted,
+      blockOffDomainNavigation: true,
+      allowPrivateNetwork: this.local.allowPrivateNetwork,
+    });
+  }
+
+  async shutdown(): Promise<void> {
+    await this.inner.shutdown();
+  }
+}