stuntdouble 0.1.2 → 0.2.0

package/dist/chunk-XHSDRB3X.js

@@ -0,0 +1,996 @@
+import {
+  startUi
+} from "./chunk-BFI6P5DO.js";
+import {
+  DirectBrowserTools,
+  INDEX_SESSION_SAFETY,
+  hostMatchesDomain,
+  isPrivateHost,
+  redactInput
+} from "./chunk-FMZTT2MC.js";
+import {
+  ActorSchema,
+  ChecklistSchema,
+  ConfigSchema,
+  appendJsonl,
+  describeRunScore,
+  effectiveStatus,
+  isLive,
+  newChecklistScoring,
+  readJson,
+  readRuns,
+  resolveHaltedChecks,
+  resolveSkippedChecks,
+  runningMarker,
+  scoreChecklistRun,
+  sdDir,
+  tallyRun,
+  writeFileAtomic,
+  writeJsonAtomic
+} from "./chunk-F3R3QL7V.js";
+
+// src/run.ts
+import { createHash } from "crypto";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat } from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { join } from "path";
+
+// package.json
+var package_default = {
+  name: "stuntdouble",
+  version: "0.2.0",
+  description: "Stunt Double Local: run Stunt Double checklists in a local Chrome from your own coding agent session, with the runs kept as files and a local viewer",
+  keywords: [
+    "stunt-double",
+    "testing",
+    "browser",
+    "checklist",
+    "mcp",
+    "playwright",
+    "agents"
+  ],
+  license: "Apache-2.0",
+  author: "Turnout Labs Ltd",
+  homepage: "https://github.com/stunt-double/stuntkit/tree/main/packages/local#readme",
+  bugs: {
+    url: "https://github.com/stunt-double/stuntkit/issues"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/stunt-double/stuntkit.git",
+    directory: "packages/local"
+  },
+  type: "module",
+  bin: {
+    stuntdouble: "dist/cli.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  scripts: {
+    build: "tsup",
+    "type-check": "tsc -p tsconfig.json",
+    test: 'node --conditions=@stunt-double/source --test "test/**/*.test.ts"',
+    prepack: "pnpm run build"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "playwright-core": "^1.64.1",
+    zod: "^4.6.7"
+  },
+  devDependencies: {
+    "@stuntkit/browser-toolset": "workspace:*"
+  },
+  engines: {
+    node: ">=22.18"
+  },
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org",
+    provenance: true
+  }
+};
+
+// src/brief.ts
+var CONDITION_LABELS = {
+  always: "always",
+  if_previous_passed: "only if the check before it passed",
+  if_previous_failed: "only if the check before it failed"
+};
+function checkLabel(check) {
+  const kind = check.type === "informational" ? "informational, record what you observe" : check.type === "weighted" ? `weighted x${check.weight ?? 1}${(check.weight ?? 1) < 0 ? ", a penalty" : ""}` : "pass/fail";
+  const parts = [kind, CONDITION_LABELS[check.run_condition]];
+  if (check.on_failure === "stop") parts.push("the run stops if it fails");
+  return `(${parts.join(", ")})`;
+}
+function checkLine(check) {
+  return `- [${check.key}] ${checkLabel(check)} ${check.description}`;
+}
+function buildBrief(input) {
+  const { actor, checklist, url, checks, resumed } = input;
+  const persona = [
+    `You are ${actor.name}${actor.description ? `: ${actor.description.replace(/[.\s]+$/, "")}` : ""}.`,
+    actor.system_prompt ?? ""
+  ].filter(Boolean).join("\n");
+  const knowledge = actor.knowledge.length ? [
+    "What you know:",
+    ...actor.knowledge.map((k) => `### ${k.title} (${k.kind})
+${k.content}`)
+  ].join("\n") : "";
+  return [
+    persona,
+    knowledge,
+    `Your task: ${checklist.instructions}`,
+    `Start at ${url}${resumed ? " (this run is resuming: earlier verdicts stand, judge only the checks below)" : ""}.`,
+    `Checks to judge:
+${checks.map(checkLine).join("\n")}`,
+    [
+      "How to work:",
+      "- Stay in persona: act and judge as this person would, not as a tester.",
+      "- Read the page with read_page and find. Ask for a screenshot only when how something looks is the question.",
+      '- get_page_text and read_page "all" return up to 20,000 characters: keep them for long text such as a policy.',
+      "- Judge each check with evaluate_check as soon as you have observed it, while the evidence is on screen.",
+      "- A passed verdict needs a locator: text visible on the page, or a CSS selector, that shows the evidence. A failure may describe something missing.",
+      "- Cite only what you saw in this run. Never pass a check on what a page probably does.",
+      '- When something stops you (a sign-in wall, a broken page, a CAPTCHA), judge the checks you cannot reach as "blocked" and say what stopped you.',
+      "- Always end with finish_run and a one or two sentence summary, even when blocked or stopped."
+    ].join("\n")
+  ].filter(Boolean).join("\n\n");
+}
+
+// src/driver.ts
+import { chromium } from "playwright-core";
+var pageIds = /* @__PURE__ */ new WeakMap();
+var pageSeq = 0;
+function idOf(page) {
+  let id = pageIds.get(page);
+  if (!id) {
+    pageSeq += 1;
+    id = `pw-${pageSeq}`;
+    pageIds.set(page, id);
+  }
+  return id;
+}
+var PlaywrightPage = class {
+  id;
+  raw;
+  constructor(page) {
+    this.raw = page;
+    this.id = idOf(page);
+  }
+  goto(url, options = {}) {
+    return this.raw.goto(url, {
+      ...options.waitUntil ? { waitUntil: options.waitUntil } : {},
+      ...options.timeoutMs ? { timeout: options.timeoutMs } : {}
+    });
+  }
+  goBack() {
+    return this.raw.goBack();
+  }
+  goForward() {
+    return this.raw.goForward();
+  }
+  screenshot(options = {}) {
+    return this.raw.screenshot(options);
+  }
+  evaluate(expression, arg) {
+    if (typeof expression === "string") return this.raw.evaluate(expression);
+    return this.raw.evaluate(expression, arg);
+  }
+  url() {
+    return this.raw.url();
+  }
+  title() {
+    return this.raw.title();
+  }
+  setViewportSize(width, height) {
+    return this.raw.setViewportSize({ width, height });
+  }
+  waitForTimeout(ms) {
+    return this.raw.waitForTimeout(ms);
+  }
+  waitForSelector(selector, options = {}) {
+    return this.raw.waitForSelector(selector, options);
+  }
+  waitForLoadState(state, timeoutMs) {
+    return this.raw.waitForLoadState(state, timeoutMs ? { timeout: timeoutMs } : void 0);
+  }
+  locator(selector) {
+    return this.raw.locator(selector).first();
+  }
+  click(x, y, options = {}) {
+    return this.raw.mouse.click(x, y, options);
+  }
+  hover(x, y) {
+    return this.raw.mouse.move(x, y);
+  }
+  async scroll(x, y, deltaX, deltaY) {
+    await this.raw.mouse.move(x, y);
+    await this.raw.mouse.wheel(deltaX, deltaY);
+  }
+  async dragAndDrop(fromX, fromY, toX, toY) {
+    await this.raw.mouse.move(fromX, fromY);
+    await this.raw.mouse.down();
+    await this.raw.mouse.move(toX, toY, { steps: 10 });
+    await this.raw.mouse.up();
+  }
+  type(text) {
+    return this.raw.keyboard.type(text);
+  }
+  keyPress(key) {
+    return this.raw.keyboard.press(key);
+  }
+  close() {
+    return this.raw.close();
+  }
+};
+var PlaywrightContext = class {
+  context;
+  active;
+  policy = {};
+  routed = false;
+  constructor(context) {
+    this.context = context;
+    context.on("page", (page) => {
+      this.active = page;
+    });
+  }
+  activePage() {
+    const open = this.context.pages();
+    if (!this.active || this.active.isClosed()) this.active = open[open.length - 1];
+    return this.active ? new PlaywrightPage(this.active) : void 0;
+  }
+  pages() {
+    return this.context.pages().map((p) => new PlaywrightPage(p));
+  }
+  async newPage(url) {
+    const page = await this.context.newPage();
+    this.active = page;
+    if (url) await page.goto(url);
+    return new PlaywrightPage(page);
+  }
+  async setActivePage(page) {
+    const raw = this.context.pages().find((p) => idOf(p) === page.id);
+    if (!raw) throw new Error(`No open tab with id ${page.id}`);
+    this.active = raw;
+    await raw.bringToFront();
+  }
+  clearCookies() {
+    return this.context.clearCookies();
+  }
+  async addInitScript(source) {
+    await this.context.addInitScript(source);
+  }
+  /** Abort requests to blocked hosts, or to anything outside the allow list. */
+  async setDomainPolicy(policy) {
+    this.policy = policy;
+    if (this.routed) return;
+    this.routed = true;
+    await this.context.route("**/*", (route) => {
+      let host = "";
+      try {
+        host = new URL(route.request().url()).hostname;
+      } catch {
+        return route.continue();
+      }
+      const { allowedDomains, blockedDomains } = this.policy;
+      const blocked = (blockedDomains ?? []).some((d) => hostMatchesDomain(host, d)) || allowedDomains !== void 0 && allowedDomains.length > 0 && !allowedDomains.some((d) => hostMatchesDomain(host, d));
+      return blocked ? route.abort("blockedbyclient") : route.continue();
+    });
+  }
+};
+var PlaywrightDriver = class _PlaywrightDriver {
+  context;
+  browserContext;
+  refusal = null;
+  constructor(context) {
+    this.browserContext = context;
+    this.context = new PlaywrightContext(context);
+  }
+  /**
+   * The installed Google Chrome, or Playwright's own Chromium when Chrome is
+   * missing and `npx playwright install chromium` has been run.
+   */
+  static async launch(options) {
+    const settings = {
+      headless: options.headless,
+      viewport: options.viewport,
+      hasTouch: options.touch,
+      ...options.locale ? { locale: options.locale } : {}
+    };
+    let context;
+    try {
+      context = await chromium.launchPersistentContext(options.profileDir, {
+        ...settings,
+        channel: "chrome"
+      });
+    } catch (chromeError) {
+      if (/ProcessSingleton|SingletonLock|already in use/i.test(chromeError.message)) {
+        throw new Error(
+          "Another run is already using this actor's kept login (persist_login). Finish that run first, or try again when it ends.",
+          { cause: chromeError }
+        );
+      }
+      try {
+        context = await chromium.launchPersistentContext(options.profileDir, settings);
+      } catch {
+        throw new Error(
+          `Could not start Chrome (${chromeError.message.split("\n")[0]}). Install Google Chrome, or run \`npx playwright install chromium\`.`
+        );
+      }
+    }
+    const driver = new _PlaywrightDriver(context);
+    const refuse = (request) => {
+      const reason = request.isNavigationRequest() ? options.refuseNavigation(request.url()) : null;
+      if (reason && !request.frame().parentFrame()) driver.refusal = reason;
+      return reason;
+    };
+    await context.route(
+      "**/*",
+      (route) => refuse(route.request()) ? route.abort("blockedbyclient") : route.fallback()
+    );
+    context.on("request", (request) => {
+      if (request.redirectedFrom() && refuse(request)) {
+        request.frame().goto("about:blank").catch(() => {
+        });
+      }
+    });
+    if (context.pages().length === 0) await driver.context.newPage();
+    return driver;
+  }
+  takeRefusal() {
+    const refusal = this.refusal;
+    this.refusal = null;
+    return refusal;
+  }
+  /** Instruction-style actions need a model of their own. Nothing here calls them. */
+  async act() {
+    throw new Error("act is not supported by this driver: use the browser toolset instead");
+  }
+  async extract() {
+    throw new Error("extract is not supported by this driver: use the browser toolset instead");
+  }
+  close() {
+    return this.browserContext.close();
+  }
+};
+
+// src/evidence.ts
+var MAX_LOCATOR_TEXT = 120;
+var MAX_LOCATOR_SELECTOR = 400;
+var SETTLE_MS = 350;
+var FIND_TIMEOUT_MS = 5e3;
+function cleanLocator(locator) {
+  const clean = (value) => value?.replace(/\s+/g, " ").trim() || null;
+  const selector = clean(locator?.selector);
+  return {
+    selector: selector && selector.length <= MAX_LOCATOR_SELECTOR ? selector : null,
+    text: clean(locator?.text)?.slice(0, MAX_LOCATOR_TEXT) ?? null
+  };
+}
+async function focusEvidence(page, query, timeoutMs = FIND_TIMEOUT_MS) {
+  if (!query.selector && !query.text) return null;
+  let timer;
+  const via = await Promise.race([
+    page.evaluate(findAndScroll, query),
+    new Promise((ok) => timer = setTimeout(() => ok(null), timeoutMs))
+  ]).catch(() => null).finally(() => clearTimeout(timer));
+  if (via) await page.waitForTimeout(SETTLE_MS).catch(() => {
+  });
+  return via;
+}
+function findAndScroll(query) {
+  const centre = { block: "center", inline: "center" };
+  const shown = (el) => {
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0 && el.checkVisibility({ visibilityProperty: true, opacityProperty: true });
+  };
+  const norm = (s) => (s ?? "").replace(/\s+/g, " ").toLowerCase();
+  const wanted = query.text ? norm(query.text) : null;
+  const labelled = (el, fragment) => {
+    const labels = ["placeholder", "aria-label", "alt", "title"].map((a) => el.getAttribute(a));
+    if ("value" in el && typeof el.value === "string") labels.push(el.value);
+    return labels.some((l) => norm(l).includes(fragment));
+  };
+  const rendered = (el) => norm(el instanceof HTMLElement ? el.innerText : "");
+  if (query.selector) {
+    let matches = [];
+    try {
+      matches = Array.from(document.querySelectorAll(query.selector));
+    } catch {
+    }
+    const el = matches.find(
+      (m) => m !== document.documentElement && m !== document.body && m.tagName !== "MAIN" && shown(m) && (!wanted || labelled(m, wanted) || rendered(m).includes(wanted))
+    );
+    if (el) {
+      el.scrollIntoView(centre);
+      return "selector";
+    }
+  }
+  if (!wanted) return null;
+  const elements = [];
+  const collect = (root) => {
+    for (const el of Array.from(root.querySelectorAll("*"))) {
+      elements.push(el);
+      if (el.shadowRoot) collect(el.shadowRoot);
+    }
+  };
+  collect(document.body);
+  let best = null;
+  let bestLength = Number.POSITIVE_INFINITY;
+  for (const el of elements) {
+    if (["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE"].includes(el.tagName)) continue;
+    let length = 0;
+    if (!labelled(el, wanted)) {
+      const text = rendered(el);
+      length = text.includes(wanted) ? text.length : Number.POSITIVE_INFINITY;
+    }
+    if (length >= bestLength || !shown(el)) continue;
+    best = el;
+    bestLength = length;
+  }
+  if (!best) return null;
+  best.scrollIntoView(centre);
+  return "text";
+}
+
+// src/run.ts
+var PACKAGE = `${package_default.name}@${package_default.version}`;
+var STOPPED = "This run was stopped from the viewer. Do not use the browser again: call finish_run now with a summary of what you found.";
+var NOT_JUDGED = "Not judged before the run finished.";
+var PRIVATE_REFUSED = "Local and private addresses other than the app under test are not reachable.";
+var SETUP = "Run /stuntdouble setup to create one.";
+var LOG_TEXT_CHARS = 500;
+var PRESETS = {
+  desktop: { width: 1280, height: 720, touch: false },
+  tablet: { width: 1024, height: 1366, touch: true },
+  mobile: { width: 390, height: 844, touch: true }
+};
+function rebase(url, localBase) {
+  if (!localBase) return url;
+  const target = new URL(url);
+  return new URL(target.pathname + target.search + target.hash, new URL(localBase).origin).href;
+}
+function stamp(date = /* @__PURE__ */ new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`;
+}
+var now = () => (/* @__PURE__ */ new Date()).toISOString();
+function ago(iso) {
+  if (!iso) return "not started";
+  const minutes = Math.round((Date.now() - Date.parse(iso)) / 6e4);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes} min ago`;
+  const hours = Math.round(minutes / 60);
+  return hours < 48 ? `${hours} h ago` : `${Math.round(hours / 24)} days ago`;
+}
+var LocalSession = class {
+  root;
+  launch;
+  active = null;
+  ui = null;
+  /** The run this session last finished, so a second finish_run is answered, not refused. */
+  finished = null;
+  /** Extra `runner` fields for a new run, such as the model a standalone run uses. */
+  runnerFields;
+  /** A viewer started by someone else (the Studio): its links are used, and it is not closed here. */
+  sharedUi;
+  constructor(options) {
+    this.root = sdDir(options.project);
+    this.launch = options.launch ?? PlaywrightDriver.launch;
+    this.runnerFields = options.runner ?? {};
+    this.ui = options.ui ?? null;
+    this.sharedUi = Boolean(options.ui);
+  }
+  /** The viewer's address, starting it on first use. */
+  async openUi(path = "/") {
+    this.ui ??= await startUi({ root: this.root });
+    await writeJsonAtomic(join(this.root, ".live", "server.json"), {
+      port: this.ui.port,
+      token: this.ui.token,
+      pid: process.pid
+    });
+    return this.ui.link(path);
+  }
+  /** The viewer's port while it is running in this process. */
+  get viewerPort() {
+    return this.ui?.port ?? null;
+  }
+  /** open_ui: the link, and a line on each of the latest runs. */
+  async overview() {
+    const link = await this.openUi();
+    const runs = (await readRuns(this.root)).slice(0, 5);
+    if (runs.length === 0) return `${link}
+
+No runs yet.`;
+    const lines = runs.map((e) => {
+      if (!("run" in e)) return `- ${e.id}: unreadable (${e.error.split("\n")[0]})`;
+      const { run } = e;
+      const status = effectiveStatus(this.root, run);
+      const t = tallyRun(run);
+      const outcome = run.score ? `${status}, ${run.score.outcome}` : status;
+      return `- ${run.checklist}: ${outcome}, ${t.passed}/${t.total} checks passed, started ${ago(run.started_at)} (${run.id})`;
+    });
+    return [link, `Latest runs, newest first:
+${lines.join("\n")}`].join("\n\n");
+  }
+  async startRun(input) {
+    if (this.active) return this.resumeActive(input);
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(input.checklist)) {
+      throw new Error(`"${input.checklist}" is not a checklist slug (checklists/<slug>.json).`);
+    }
+    const config = await readJson(
+      join(this.root, "stuntdouble.json"),
+      ConfigSchema,
+      ".stuntdouble/stuntdouble.json"
+    ).catch((err) => {
+      throw /file not found$/.test(err.message) ? new Error(`${err.message}. ${SETUP}`) : err;
+    });
+    let checklist = await readJson(
+      join(this.root, "checklists", `${input.checklist}.json`),
+      ChecklistSchema,
+      `.stuntdouble/checklists/${input.checklist}.json`
+    ).catch(async (err) => {
+      if (!/file not found$/.test(err.message)) throw err;
+      const slugs = (await readdir(join(this.root, "checklists")).catch(() => [])).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -".json".length));
+      throw new Error(
+        `${err.message}. ${slugs.length ? `The checklists here are: ${slugs.join(", ")}.` : SETUP}`
+      );
+    });
+    const actor = await readJson(
+      join(this.root, "actors", `${checklist.actor}.json`),
+      ActorSchema,
+      `.stuntdouble/actors/${checklist.actor}.json`
+    );
+    await this.markInterrupted();
+    let run;
+    let dir;
+    if (input.resume) {
+      const entry = (await readRuns(this.root)).find(
+        (e) => "run" in e && e.run.checklist === input.checklist && e.run.runner.kind === "local" && (e.run.status === "interrupted" || e.run.status === "stopped")
+      );
+      if (!entry || !("run" in entry)) {
+        throw new Error(`No interrupted or stopped run of ${input.checklist} to resume.`);
+      }
+      dir = join(this.root, "runs", entry.id);
+      checklist = ChecklistSchema.parse(entry.run.checklist_snapshot);
+      await this.clearStop(entry.id);
+      run = {
+        ...entry.run,
+        results: entry.run.results.filter((r) => r.evidence !== NOT_JUDGED),
+        status: "running",
+        pid: process.pid,
+        finished_at: null,
+        score: null,
+        summary: null
+      };
+    } else {
+      dir = "";
+      run = {
+        format: "stuntdouble.run/1",
+        id: "",
+        runner: { ...this.runnerFields, kind: "local", package: PACKAGE, judged: false },
+        status: "running",
+        pid: process.pid,
+        url: rebase(checklist.url, config.local_base_url),
+        started_at: now(),
+        finished_at: null,
+        checklist: input.checklist,
+        actor: checklist.actor,
+        checklist_snapshot: { ...checklist, cloud: void 0 },
+        results: [],
+        score: null,
+        summary: null,
+        cloud: null
+      };
+    }
+    const trusted = [run.url, checklist.url, config.local_base_url].filter((u) => Boolean(u)).map((u) => new URL(u));
+    const trustedHosts = [...new Set(trusted.map((u) => u.hostname))];
+    const trustedOrigins = new Set(trusted.map((u) => u.origin));
+    const refuseNavigation = (href) => {
+      const url = URL.parse(href);
+      return url && isPrivateHost(url.hostname) && !trustedOrigins.has(url.origin) ? PRIVATE_REFUSED : null;
+    };
+    const preset = PRESETS[checklist.browser_config?.preset ?? "desktop"];
+    const toolOptions = {
+      viewport: checklist.browser_config?.viewport ?? preset,
+      allowPrivateHosts: true,
+      checkNavigation: refuseNavigation
+    };
+    const tempProfile = actor.persist_login ? null : await mkdtemp(join(tmpdir(), "stuntdouble-profile-"));
+    const project = createHash("sha256").update(this.root).digest("hex").slice(0, 12);
+    const profileDir = tempProfile ?? join(homedir(), ".stuntdouble", "profiles", project, checklist.actor);
+    await mkdir(profileDir, { recursive: true });
+    let driver;
+    try {
+      driver = await this.launch({
+        profileDir,
+        headless: config.headless,
+        viewport: toolOptions.viewport,
+        touch: checklist.browser_config?.touch ?? preset.touch,
+        locale: checklist.browser_config?.locale,
+        refuseNavigation
+      });
+    } catch (err) {
+      if (tempProfile) await rm(tempProfile, { recursive: true, force: true });
+      throw err;
+    }
+    if (!input.resume) {
+      await mkdir(join(this.root, "runs"), { recursive: true });
+      for (let n = 1; !dir; n++) {
+        const id = `${stamp()}-${input.checklist}${n > 1 ? `-${n}` : ""}`;
+        const made = await mkdir(join(this.root, "runs", id)).then(
+          () => true,
+          (err) => {
+            if (err.code === "EEXIST") return false;
+            throw err;
+          }
+        );
+        if (made) [run.id, dir] = [id, join(this.root, "runs", id)];
+      }
+    }
+    const gitignore = join(this.root, ".gitignore");
+    if (!await stat(gitignore).catch(() => null)) await writeFileAtomic(gitignore, ".live/\n");
+    this.active = {
+      dir,
+      run,
+      checklist,
+      actor,
+      driver,
+      trusted: new DirectBrowserTools(driver, toolOptions),
+      guarded: config.safety === "third_party" ? new DirectBrowserTools(driver, { ...toolOptions, safety: INDEX_SESSION_SAFETY }) : null,
+      trustedHosts,
+      tempProfile,
+      everyScreenshot: config.model_screenshots === "every_action",
+      stopped: false
+    };
+    this.finished = null;
+    await this.save();
+    await this.markRunning();
+    await this.log("start_run", input, input.resume ? "Resumed" : "Started");
+    const opened = await this.browserTool("navigate", { url: run.url });
+    const pending = this.pending();
+    const viewer = await this.openUi(`/runs/${run.id}`);
+    return [
+      `Run ${run.id} ${input.resume ? "resumed" : "started"}. Watch it or stop it at ${viewer}`,
+      unweightedNote(checklist),
+      buildBrief({
+        actor,
+        checklist,
+        url: run.url,
+        checks: pending,
+        resumed: Boolean(input.resume)
+      }),
+      // Not the navigate result: it carries the page title, and this reply is
+      // read by the main session, which never reads page content.
+      opened.isError ? `The start page did not load: ${opened.text}
+Try navigate again, or judge the checks you cannot reach as "blocked".` : `The browser is open at ${run.url}: read the page with read_page before acting.`,
+      this.nextStep()
+    ].filter(Boolean).join("\n\n");
+  }
+  /** One of the browser toolset's direct tools, on the active run's browser. */
+  async browserTool(name, input) {
+    const active = this.requireActive();
+    if (await this.stopRequested(active)) return { text: STOPPED, isError: true };
+    const page = await active.driver.context.activePage();
+    const host = page ? URL.parse(await page.url())?.hostname ?? "" : "";
+    const tools = active.guarded && !isTrustedHost(host, active.trustedHosts) ? active.guarded : active.trusted;
+    const result = await tools.run(name, input);
+    const refusal = active.driver.takeRefusal();
+    if (refusal) {
+      const text = `Error: Navigation refused. ${refusal}`;
+      await this.log(name, redactInput(name, input), text);
+      return { text, isError: true };
+    }
+    if (result.screenshotBase64)
+      await this.saveFrame(Buffer.from(result.screenshotBase64, "base64"));
+    await this.log(name, redactInput(name, input), result.text);
+    const image = result.screenshotBase64 && (name === "screenshot" || active.everyScreenshot) ? result.screenshotBase64 : void 0;
+    return { text: result.text, ...image ? { image } : {}, isError: Boolean(result.error) };
+  }
+  async evaluateCheck(input) {
+    if (!this.active && this.finished) return this.alreadyFinished();
+    const active = this.requireActive();
+    if (await this.stopRequested(active)) throw new Error(STOPPED);
+    const { run, checklist } = active;
+    const check = checklist.checks.find((c) => c.key === input.check);
+    if (!check) {
+      throw new Error(
+        `No check "${input.check}" in this run. The keys are: ${checklist.checks.map((c) => c.key).join(", ")}.`
+      );
+    }
+    const earlier = run.results.find((r) => r.check === check.key);
+    if (earlier) {
+      throw new Error(
+        `[${check.key}] already has a verdict (${earlier.status}). Each check gets one.`
+      );
+    }
+    if (check.type === "informational" && (input.status === "passed" || input.status === "failed")) {
+      throw new Error(
+        `[${check.key}] is informational: record what you observed with status "informational".`
+      );
+    }
+    if (check.type !== "informational" && input.status === "informational") {
+      throw new Error(
+        `[${check.key}] is scored: judge it "passed" or "failed", or "blocked" if you could not reach it.`
+      );
+    }
+    const page = await active.driver.context.activePage();
+    const query = cleanLocator(input.locator);
+    const found = page ? await focusEvidence(page, query) : null;
+    if (input.status === "passed" && !found) {
+      throw new Error(
+        query.text || query.selector ? `Not recorded: the locator ${JSON.stringify(query.text ?? query.selector)} is not visible on the current page. Go back to where you saw the evidence, or cite text that is on screen now.` : 'Not recorded: a passed verdict needs a locator, {"text": "..."} visible on the page or {"selector": "..."}.'
+      );
+    }
+    let screenshot;
+    if (page) {
+      try {
+        const png = await page.screenshot({ type: "png", timeout: 1e4 });
+        screenshot = `shots/${check.key}.png`;
+        await writeFileAtomic(join(active.dir, screenshot), png);
+        await this.saveFrame(png);
+      } catch {
+        screenshot = void 0;
+      }
+    }
+    run.results.push({
+      check: check.key,
+      status: input.status === "blocked" ? "error" : input.status,
+      evidence: input.evidence,
+      ...query.text || query.selector ? {
+        locator: {
+          ...query.text ? { text: query.text } : {},
+          ...query.selector ? { selector: query.selector } : {}
+        }
+      } : {},
+      ...screenshot ? { screenshot } : {},
+      at: now()
+    });
+    const statuses = new Map(run.results.map((r) => [r.check, r.status]));
+    const halted = resolveHaltedChecks({
+      checks: checklist.checks.map((c) => ({
+        id: c.key,
+        description: c.description,
+        onFailure: c.on_failure
+      })),
+      statuses
+    });
+    const skipped = halted.length ? halted : this.conditionSkips(statuses);
+    for (const s of skipped) {
+      run.results.push({ check: s.checkId, status: "skipped", evidence: s.reason, at: now() });
+    }
+    await this.save();
+    const recorded = `Recorded [${check.key}] as ${input.status}.`;
+    await this.log("evaluate_check", input, recorded);
+    const notes = skipped.map((s) => `[${s.checkId}] ${s.reason}`);
+    if (halted.length) notes.push("The run has stopped.");
+    return [recorded, ...notes, this.nextStep()].join("\n");
+  }
+  async finishRun(input) {
+    if (!this.active && this.finished) return this.alreadyFinished();
+    const active = this.requireActive();
+    const stopped = await this.stopRequested(active);
+    const { run, checklist } = active;
+    for (const s of this.conditionSkips(new Map(run.results.map((r) => [r.check, r.status])))) {
+      run.results.push({ check: s.checkId, status: "skipped", evidence: s.reason, at: now() });
+    }
+    for (const check of this.pending()) {
+      run.results.push({
+        check: check.key,
+        status: "error",
+        evidence: NOT_JUDGED,
+        at: now()
+      });
+    }
+    const score = scoreLocalRun(checklist, run.results);
+    run.score = {
+      score: score.score,
+      unit: score.scoreUnit,
+      outcome: score.outcome,
+      pass_threshold: score.passThreshold,
+      grade: score.grade
+    };
+    run.summary = input.summary;
+    run.status = stopped ? "stopped" : "completed";
+    run.finished_at = now();
+    await this.save();
+    await this.log("finish_run", input, `Finished: ${score.outcome}`);
+    const viewer = await this.openUi(`/runs/${run.id}`);
+    await this.endBrowser();
+    const line = (r) => `- [${r.check}] ${r.evidence}`;
+    const failed = run.results.filter((r) => r.status === "failed");
+    const blocked = run.results.filter((r) => r.status === "error");
+    const counts = describeRunScore(score, {
+      passedCount: run.results.filter((r) => r.status === "passed").length,
+      totalCount: checklist.checks.length
+    });
+    const t = tallyRun(run);
+    const tally = score.weighted ? ` ${t.passed}/${t.total} checks passed.` : "";
+    this.finished = { id: run.id, report: viewer };
+    return [
+      `Run ${run.id} ${run.status}: ${score.outcome}. ${counts}.${tally} ${score.weighted ? "" : `${unweightedNote(checklist, true)} `}Self-judged: the actor recorded its own verdicts.`,
+      failed.length ? `Failed:
+${failed.map(line).join("\n")}` : "",
+      blocked.length ? `Not judged:
+${blocked.map(line).join("\n")}` : "",
+      `Report: ${viewer}`
+    ].filter(Boolean).join("\n\n");
+  }
+  /**
+   * start_run while this process still has a run open, as when the person
+   * interrupts the actor: resume carries on with it in the same browser.
+   */
+  async resumeActive(input) {
+    const active = this.requireActive();
+    const { run } = active;
+    if (!input.resume || run.checklist !== input.checklist) {
+      throw new Error(
+        `Run ${run.id} of ${run.checklist} is still going: call start_run with checklist "${run.checklist}" and resume to carry on with it, or finish_run to end it.`
+      );
+    }
+    active.stopped = false;
+    run.status = "running";
+    await this.clearStop(run.id);
+    await this.save();
+    await this.markRunning();
+    await this.log("start_run", input, "Resumed");
+    const viewer = await this.openUi(`/runs/${run.id}`);
+    return [
+      `Run ${run.id} resumed. Watch it or stop it at ${viewer}`,
+      buildBrief({
+        actor: active.actor,
+        checklist: active.checklist,
+        url: run.url,
+        checks: this.pending(),
+        resumed: true
+      }),
+      "The browser is still open where the run left off: read the page before acting.",
+      this.nextStep()
+    ].join("\n\n");
+  }
+  /** On shutdown: an unfinished run is marked interrupted, so it can be resumed. */
+  async close() {
+    if (this.active) {
+      this.active.run.status = this.active.stopped ? "stopped" : "interrupted";
+      await this.save().catch(() => {
+      });
+      await this.endBrowser();
+    }
+    if (!this.sharedUi) await this.ui?.close();
+    this.ui = null;
+  }
+  alreadyFinished() {
+    const { id, report } = this.finished;
+    return `Run ${id} has already finished: its report is at ${report}. Start another with start_run.`;
+  }
+  requireActive() {
+    if (!this.active) throw new Error("No run is going: call start_run first.");
+    return this.active;
+  }
+  /** Checks with no result yet, in run order. */
+  pending() {
+    const active = this.requireActive();
+    const judged = new Set(active.run.results.map((r) => r.check));
+    return active.checklist.checks.filter((c) => !judged.has(c.key));
+  }
+  conditionSkips(statuses) {
+    return resolveSkippedChecks({
+      checks: this.requireActive().checklist.checks.map((c) => ({
+        id: c.key,
+        description: c.description,
+        runCondition: c.run_condition
+      })),
+      statuses
+    });
+  }
+  nextStep() {
+    const pending = this.pending();
+    if (pending.length === 0)
+      return "Every check has a verdict: call finish_run with a short summary.";
+    const next = pending[0];
+    return `Next: [${next.key}] ${checkLabel(next)} ${next.description} (${pending.length} left).`;
+  }
+  /** The viewer's Stop writes the run id to `.live/stop`; the run notices on its next call. */
+  async stopRequested(active) {
+    if (active.stopped) return true;
+    const flag = await readFile(join(this.root, ".live", "stop"), "utf8").catch(() => "");
+    if (flag.trim() !== active.run.id) return false;
+    active.stopped = true;
+    active.run.status = "stopped";
+    await this.save();
+    await this.log("stop", {}, "Stopped from the viewer");
+    return true;
+  }
+  /** Runs left `running` by a process that is gone, or by this one before a restart. */
+  async markInterrupted() {
+    for (const entry of await readRuns(this.root)) {
+      if (!("run" in entry) || entry.run.status !== "running") continue;
+      if (entry.run.pid !== process.pid && isLive(this.root, entry.run)) continue;
+      await writeJsonAtomic(join(this.root, "runs", entry.id, "run.json"), {
+        ...entry.run,
+        status: "interrupted"
+      });
+    }
+  }
+  async endBrowser() {
+    const active = this.active;
+    if (!active) return;
+    this.active = null;
+    await active.driver.close().catch(() => {
+    });
+    if (active.tempProfile) await rm(active.tempProfile, { recursive: true, force: true });
+    await this.clearStop(active.run.id);
+    await rm(runningMarker(this.root, active.run.id), { force: true });
+  }
+  async markRunning() {
+    const { run } = this.requireActive();
+    await writeFileAtomic(runningMarker(this.root, run.id), String(run.pid));
+  }
+  async clearStop(id) {
+    const stopFile = join(this.root, ".live", "stop");
+    const flag = await readFile(stopFile, "utf8").catch(() => "");
+    if (flag.trim() === id) await rm(stopFile, { force: true });
+  }
+  async save() {
+    const active = this.requireActive();
+    await writeJsonAtomic(join(active.dir, "run.json"), active.run);
+  }
+  async log(tool, input, text) {
+    const active = this.requireActive();
+    await appendJsonl(join(active.dir, "activity.jsonl"), {
+      at: now(),
+      tool,
+      input,
+      text: text.length > LOG_TEXT_CHARS ? `${text.slice(0, LOG_TEXT_CHARS)}...` : text
+    });
+  }
+  /** The viewer's live frame, best effort. ponytail: one per project, so two sessions running at once share it. */
+  async saveFrame(png) {
+    await writeFileAtomic(join(this.root, ".live", "latest.png"), png).catch(() => {
+    });
+  }
+};
+function isTrustedHost(host, trustedHosts) {
+  return host !== "" && trustedHosts.some((t) => hostMatchesDomain(host, t));
+}
+function unweightedNote(checklist, atFinish = false) {
+  if (checklist.checks.some((c) => c.type === "weighted")) return null;
+  const threshold = checklist.pass_threshold == null ? "" : ` Its pass_threshold (${checklist.pass_threshold}) applies to weighted checks only.`;
+  if (!atFinish && !threshold) return null;
+  return `No score: this checklist has no weighted checks, so it passes only when every pass/fail check passes.${threshold}`;
+}
+function scoreLocalRun(checklist, results) {
+  const scoring = newChecklistScoring({
+    scoreType: checklist.score_type,
+    scoreUnit: checklist.score_unit,
+    passThreshold: checklist.pass_threshold,
+    scoreBands: checklist.score_bands,
+    checks: checklist.checks.map((c) => ({ checkType: c.type, weight: c.weight }))
+  });
+  return scoreChecklistRun({
+    checks: checklist.checks.map((c) => ({
+      id: c.key,
+      checkType: c.type,
+      weight: c.weight ?? 1,
+      onFailure: c.on_failure
+    })),
+    results: results.map((r) => ({ checkId: r.check, status: r.status })),
+    passThreshold: scoring.pass_threshold,
+    scoreBands: scoring.score_bands,
+    scoreType: scoring.score_type,
+    scoreUnit: scoring.score_unit
+  });
+}
+
+export {
+  PACKAGE,
+  rebase,
+  LocalSession,
+  isTrustedHost,
+  unweightedNote,
+  scoreLocalRun
+};
+//# sourceMappingURL=chunk-XHSDRB3X.js.map