debutly 0.0.0-stage → 0.2.0

package/src/browser/scan-script.ts

@@ -0,0 +1,108 @@
+// Runs in the page. Passed as a string, not a function, because tsx/esbuild can inject
+// helpers (e.g. __name) into function bodies that don't exist inside the browser.
+// Includes ARIA widgets (custom selects, menus, tabs, toggles) that apps build from divs:
+// without them, agents can open a dropdown but never see its options.
+export const SCAN_SCRIPT = `(() => {
+  const selector = [
+    'a[href]', 'button', 'input', 'select', 'textarea', 'summary',
+    '[role="button"]', '[role="link"]', '[role="option"]', '[role="menuitem"]', '[role="menuitemcheckbox"]',
+    '[role="menuitemradio"]', '[role="tab"]', '[role="checkbox"]', '[role="radio"]', '[role="switch"]', '[role="combobox"]',
+  ].join(', ');
+  const visible = (el) => typeof el.checkVisibility === 'function'
+    ? el.checkVisibility({ visibilityProperty: true })
+    : (getComputedStyle(el).display !== 'none' && getComputedStyle(el).visibility !== 'hidden');
+  const textOf = (el) => (el && (el.innerText || el.textContent)) || '';
+  // What a sighted person sees on a control with no text: its icon. Icon sets name their icons in
+  // class names (lucide-menu, tabler-icon-dots, fa-bars, i-ph-gear), data attributes, sprite
+  // references (<use href="#menu">) or an image's file name. Without it, agents met
+  // a row of buttons named "" and guessed.
+  const ICON_CLASS = /^(?:i-[a-z0-9]+-|lucide-|tabler-icon-|icon-tabler-|fa-|bi-|ti-|mdi-|ph-|ri-|feather-|heroicons?-|bx-|bxs-|octicon-|codicon-|icon-)([a-z][a-z0-9-]*)$/;
+  const NOT_ICON = /^(?:solid|regular|light|thin|duotone|brands|sharp|fw|xs|sm|md|lg|xl|spin|pulse|button|btn|wrapper|container|only|small|large|size-.*)$/;
+  const iconWord = (s) => {
+    const word = s.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().replace(/[-_]+/g, ' ')
+      .replace(/^icon /, '').replace(/( (?:icon|outline|outlined|filled|fill|line|solid|bold|regular|light|thin|duotone|round|rounded|sharp|[0-9]+))+$/, '').trim();
+    return word || s.toLowerCase();
+  };
+  const iconOf = (el) => {
+    for (const n of [el, ...el.querySelectorAll('svg, i, span, img, use')].slice(0, 15)) {
+      const tag = n.tagName.toLowerCase();
+      const href = tag === 'use' ? n.getAttribute('href') || n.getAttribute('xlink:href') || '' : '';
+      const testId = (n.getAttribute('data-testid') || '').match(/^(.+)Icon$/);
+      const named = n.getAttribute('data-icon') || n.getAttribute('data-lucide') || (href.includes('#') && href.split('#').pop()) || (testId && testId[1]);
+      if (named) return iconWord(named);
+      for (const token of n.classList || []) {
+        const m = token.match(ICON_CLASS);
+        if (m && !NOT_ICON.test(m[1])) return iconWord(m[1]);
+      }
+      if (tag === 'img') {
+        const file = (n.getAttribute('src') || '').split(/[?#]/)[0].split('/').pop().replace(/[.][a-z0-9]+$/i, '');
+        if (/^[a-z][a-z_-]{1,30}$/i.test(file)) return iconWord(file);
+      }
+    }
+    return '';
+  };
+  const out = [];
+  let next = 0;
+  // Ids from the last look stay on elements that have since gone out of sight; the same number
+  // given to another element then matches two ("strict mode violation"). Start clean each time.
+  for (const el of document.querySelectorAll('[data-debutly-id]')) el.removeAttribute('data-debutly-id');
+  for (const el of document.querySelectorAll(selector)) {
+    // Apps hide the real file field behind a styled button or drop zone; files can still be
+    // attached to it, so list it.
+    const fileField = el.tagName === 'INPUT' && el.type === 'file';
+    if (el.type === 'hidden' || (!visible(el) && !fileField)) continue;
+    const id = next++;
+    el.setAttribute('data-debutly-id', String(id));
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role') || (tag === 'a' ? 'link' : tag === 'input' ? 'input:' + (el.type || 'text') : tag);
+    const labelledBy = (el.getAttribute('aria-labelledby') || '').split(/\\s+/).filter(Boolean)
+      .map((ref) => textOf(document.getElementById(ref))).join(' ');
+    // A field's label points at it (for=) or wraps it; a wrapping label's name is its own text,
+    // without the field's (a select's options, a textarea's content).
+    const field = tag === 'input' || tag === 'select' || tag === 'textarea';
+    const labelEl = (field && el.labels && el.labels[0]) || (el.id ? document.querySelector('label[for="' + CSS.escape(el.id) + '"]') : null);
+    let label = null;
+    if (labelEl) {
+      label = labelEl.cloneNode(true);
+      label.querySelectorAll('input, select, textarea, button').forEach((n) => n.remove());
+    }
+    // title is the accessible name of last resort, as browsers and screen readers treat it.
+    // A native select's text is all its options run together: name it by its label, and list them apart.
+    const isSelect = tag === 'select';
+    const fileHint = fileField ? 'file upload' + (el.getAttribute('accept') ? ' (' + el.getAttribute('accept') + ')' : '') : '';
+    const labelled = el.getAttribute('aria-label') || labelledBy || (label && label.textContent.trim());
+    const placeholder = el.getAttribute('placeholder');
+    const raw = labelled || placeholder || (isSelect ? '' : textOf(el).trim()) || el.getAttribute('title') || fileHint;
+    const item = { id, role, name: raw.replace(/\\s+/g, ' ').trim().slice(0, 80), tag };
+    // A placeholder is an example, not a label: screen readers read it as the field's name (a
+    // password's dots as "13 bullet"), and it's gone once someone types.
+    if (!labelled && placeholder) item.nameFrom = 'placeholder';
+    if (!item.name) {
+      const icon = iconOf(el);
+      if (icon) item.icon = icon;
+    }
+    // What a keyboard user can reach: a disabled control, or one out of the tab order, isn't.
+    if (el.disabled === true || el.getAttribute('aria-disabled') === 'true') item.disabled = true;
+    else if (el.tabIndex < 0 || el.closest('[inert]')) item.tabbable = false;
+    if (isSelect) {
+      const chosen = el.selectedOptions[0];
+      item.value = chosen ? chosen.label.slice(0, 80) : '';
+      item.options = Array.from(el.options).slice(0, 30).map((o) => o.label.slice(0, 60));
+    }
+    // What a person sees of a control's state: what a field holds (a password only as filled),
+    // whether it can be edited, whether a box is ticked and whether a menu is open.
+    const textField = tag === 'textarea' || (tag === 'input' && !['checkbox', 'radio', 'file', 'submit', 'button', 'reset', 'image', 'range', 'color'].includes(el.type));
+    if (textField && el.value) {
+      if (el.type === 'password') item.filled = true;
+      else item.value = el.value.slice(0, 60);
+    }
+    if (textField && el.readOnly) item.readOnly = true;
+    const ariaChecked = el.getAttribute('aria-checked');
+    if (el.type === 'checkbox' || el.type === 'radio') item.checked = el.checked;
+    else if (ariaChecked === 'true' || ariaChecked === 'false') item.checked = ariaChecked === 'true';
+    const ariaExpanded = el.getAttribute('aria-expanded');
+    if (ariaExpanded === 'true' || ariaExpanded === 'false') item.expanded = ariaExpanded === 'true';
+    out.push(item);
+  }
+  return out;
+})()`;

package/src/browser/settle.ts

@@ -0,0 +1,32 @@
+import type { Page } from "playwright";
+
+export interface SettleOptions {
+  /** Longest wait for the network to go quiet (ms). */
+  idleMs?: number;
+  /** Longest extra wait while the page still says it is loading (ms). */
+  busyMs?: number;
+}
+
+/**
+ * Waits, as a person would, until the page has finished loading before it is read: the network
+ * goes quiet, and no "Loading…" placeholder or aria-busy region is left. Client-rendered apps show
+ * a spinner or an empty shell at DOMContentLoaded; on a slow connection agents otherwise judge (and
+ * navigate away from) pages that were only still loading. Bounded, so a page that never settles
+ * (polling, a stuck spinner) is read as it is.
+ */
+export async function settle(page: Page, o: SettleOptions = {}): Promise<void> {
+  const { idleMs = 5_000, busyMs = 10_000 } = o;
+  await page.waitForLoadState("networkidle", { timeout: idleMs }).catch(() => {});
+  const deadline = Date.now() + busyMs;
+  while (Date.now() < deadline) {
+    const busy = await page
+      .evaluate(() => {
+        if (document.querySelector('[aria-busy="true"]')) return true;
+        const text = (document.body?.innerText ?? "").trim();
+        return text.length < 300 && /\b(loading|please wait)\b/i.test(text);
+      })
+      .catch(() => false);
+    if (!busy) return;
+    await page.waitForTimeout(500);
+  }
+}

package/src/browser/signals.ts

@@ -0,0 +1,73 @@
+import type { Page } from "playwright";
+import type { Signal } from "../types";
+
+const BODY_CHARS = 500;
+/** How long a step waits for server-error bodies still being read before it is stored without them. */
+const BODY_WAIT_MS = 2000;
+
+export class SignalCollector {
+  private buffer: Signal[] = [];
+  private reading = new Set<Promise<void>>();
+
+  constructor(page: Page) {
+    page.on("console", (msg) => {
+      if (msg.type() === "error") this.buffer.push({ kind: "console_error", message: msg.text(), url: page.url() });
+    });
+    page.on("pageerror", (err) => {
+      this.buffer.push({ kind: "page_error", message: err.message, url: page.url() });
+    });
+    page.on("response", (res) => {
+      if (res.status() < 400) return;
+      // A failed navigation belongs to the page that was requested, not the one being left.
+      const url = res.request().isNavigationRequest() ? res.url() : page.url();
+      const startedAt = res.request().timing().startTime;
+      const signal: Signal = { kind: "http_error", status: res.status(), requestUrl: res.url(), url, startedAt: startedAt > 0 ? startedAt : undefined, at: Date.now() };
+      this.buffer.push(signal);
+      // A server error often says why (e.g. "No API key found"). Read the start of it; it lands on
+      // the same signal object, which findings read once the run is over.
+      if (res.status() >= 500) {
+        const read = res
+          .text()
+          .then((text) => {
+            if (signal.kind === "http_error") signal.body = text.slice(0, BODY_CHARS);
+          })
+          .catch(() => {})
+          .finally(() => this.reading.delete(read));
+        this.reading.add(read);
+      }
+    });
+    // Generating a report often only downloads a file; without this the agent saw "nothing
+    // visibly changed" and concluded the button was broken.
+    page.on("download", (download) => {
+      this.buffer.push({ kind: "download", filename: download.suggestedFilename(), url: page.url() });
+    });
+    // Playwright dismisses dialogs by default, so every confirm() would read as Cancel. Answer OK,
+    // as a person going along with the app would, and let the agent know what it asked.
+    page.on("dialog", (dialog) => {
+      this.buffer.push({ kind: "dialog", dialogType: dialog.type(), message: dialog.message(), url: page.url() });
+      dialog.accept().catch(() => {});
+    });
+  }
+
+  /** A signal the agent loop observed itself, such as a slow page. */
+  note(signal: Signal): void {
+    this.buffer.push(signal);
+  }
+
+  /**
+   * Waits, briefly, for the server-error bodies still being read. A step is stored as soon as it
+   * ends; a fast 502 was stored without the body that said why it failed (2026-10-17).
+   */
+  async settle(): Promise<void> {
+    if (!this.reading.size) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([Promise.allSettled([...this.reading]), new Promise((r) => (timer = setTimeout(r, BODY_WAIT_MS)))]);
+    clearTimeout(timer);
+  }
+
+  drain(): Signal[] {
+    const out = this.buffer;
+    this.buffer = [];
+    return out;
+  }
+}

package/src/cancel.ts

@@ -0,0 +1,20 @@
+// The run kill switch from anywhere: npm run debutly:cancel -- <runId> --store postgres://…
+// Agents stop at their next step; the run still writes its (partial) report.
+import { parseArgs } from "node:util";
+import { openDb } from "./store/db";
+import { PgRunStore } from "./store/pg-run-store";
+
+const { values, positionals } = parseArgs({ allowPositionals: true, options: { store: { type: "string" } } });
+const [runId] = positionals;
+const url = values.store ?? process.env.DATABASE_URL;
+if (!runId || !url) {
+  console.error("Usage: npm run debutly:cancel -- <runId> --store postgres://… (or set DATABASE_URL)");
+  process.exit(1);
+}
+const { db, close } = await openDb(url);
+const store = new PgRunStore(db);
+await store.requestCancel(runId);
+const run = await store.getRun(runId);
+await close();
+console.log(run ? `Run ${runId}: ${run.status}` : `No run ${runId}`);
+process.exit(run ? 0 : 1);

package/src/cli.ts

@@ -0,0 +1,281 @@
+import "./util/legacy-env";
+import "./util/key-defaults";
+import { parseArgs } from "node:util";
+import { Queue, QueueEvents } from "bullmq";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { estimatePerceptionCost, estimateRunCost } from "./cost/estimate";
+import { fetchModelPrice } from "./cost/prices";
+import { agentCount, resolveRunSize } from "./cost/tiers";
+import { DbArtifactStore, TeeArtifactStore } from "./artifacts/db";
+import { S3ArtifactStore } from "./artifacts/s3";
+import { LocalArtifactStore, type ArtifactStore } from "./artifacts/store";
+import { MailpitInbox } from "./inbox/mailpit";
+import { creditCheck, keyCreditsLeft } from "./llm/credits";
+import { createLlms } from "./llm/factory";
+import { OUT_OF_CREDITS } from "./llm/types";
+import { generateUnits } from "./persona/generate";
+import { withInclusion } from "./persona/inclusion";
+import { languageName, parseLanguages, withLanguages } from "./persona/language";
+import { peopleCount, readPeople } from "./persona/people";
+import { exhibitsFromSessions } from "./perception/exhibits";
+import { runPerception } from "./perception/run-perception";
+import { renderLaunchReadiness } from "./report/launch-readiness";
+import { queueDispatch } from "./queue/dispatch";
+import { AGENT_QUEUE, redisClient } from "./queue/jobs";
+import { HttpSandboxOutbox } from "./sandbox/outbox";
+import { runSimulation } from "./run";
+import { openDb } from "./store/db";
+import { PgRunStore } from "./store/pg-run-store";
+import type { CustomerUnit, Persona } from "./types";
+import { runOrigin } from "./util/run-origin";
+
+const MAX_EMPLOYEES = 4;
+
+const { values } = parseArgs({
+  options: {
+    url: { type: "string" },
+    goal: { type: "string" },
+    icp: { type: "string" },
+    // Customer units: "individual" (B2C, one person each) or "business" (owner + employees).
+    unit: { type: "string", default: "individual" },
+    // Run size: quick (3 units, owners only), standard (10, 2 employees each) or deep (30, 3 each).
+    tier: { type: "string", default: "quick" },
+    // How many units (individuals or business crews); overrides the tier.
+    agents: { type: "string" },
+    // Employees per business crew (0 = owner only); overrides the tier.
+    employees: { type: "string" },
+    // Refuse to start if the run could cost more than this many USD.
+    "max-cost": { type: "string" },
+    // Screen-reader, low-vision, slow-connection and non-native-English agents, rotating nightly.
+    inclusion: { type: "string", default: "on" },
+    // GLM-5.3 Flash, the default agent model, takes about 40% more steps than Gemini.
+    "max-steps": { type: "string", default: "30" },
+    concurrency: { type: "string", default: "3" },
+    out: { type: "string" },
+    // Local mail catcher (e.g. Mailpit from `supabase start`) that gives agents real inboxes.
+    mailpit: { type: "string" },
+    // Keeps each agent's signed-in browser for `debutly hear`; holds session cookies, so keep it out of the report.
+    "browser-state": { type: "string" },
+    "email-domain": { type: "string", default: "agents.test" },
+    // The app's sandbox outbox (token in DEBUTLY_SANDBOX_TOKEN), to separate failures the test environment caused.
+    "sandbox-outbox": { type: "string" },
+    // Record the run as it happens: postgres://… (or memory: for a throwaway in-process database).
+    store: { type: "string" },
+    // For the dashboard: which app this is, what started the run, and its CI page. In GitHub
+    // Actions all three default from the workflow (repository name, event, run URL).
+    app: { type: "string" },
+    trigger: { type: "string" },
+    "ci-url": { type: "string" },
+    // Days to keep screenshots stored in the database (with --store and no S3), default 7.
+    "screenshot-days": { type: "string", default: "7" },
+    // Run agents on queue workers (npm run debutly:worker) instead of here: redis://…; needs a postgres --store.
+    queue: { type: "string" },
+    // Per-agent caps on top of --max-steps.
+    "agent-token-cap": { type: "string" },
+    "agent-minutes": { type: "string" },
+    // After the depth run, this many breadth evaluators judge the pages the agents saw (Launch Readiness report).
+    evaluators: { type: "string" },
+    // Customers' first languages, as lang codes (ar,en): agents take them in turn.
+    languages: { type: "string" },
+    // An earlier run's people.json: the same agents again, e.g. to see whether a fix worked.
+    people: { type: "string" },
+  },
+});
+
+const unitKind = values.unit;
+if (!values.url || !values.goal || !values.icp || (unitKind !== "individual" && unitKind !== "business")) {
+  console.error(
+    'Usage: npx debutly (settings in debutly.json; npx debutly init writes one) or npx debutly --url <url> --goal "<goal>" --icp "<ideal customer profile>" [--unit individual|business] [--tier quick|standard|deep] [--agents N] [--employees N] [--max-cost USD] [--inclusion on|off] [--max-steps 30] [--concurrency 3] [--out runs/x] [--mailpit http://127.0.0.1:54324] [--email-domain agents.test] [--sandbox-outbox http://localhost:3000/api/sandbox/outbox] [--store postgres://…] [--app name] [--trigger nightly|pr|manual] [--ci-url url] [--screenshot-days 7] [--browser-state dir] [--queue redis://…] [--agent-token-cap N] [--agent-minutes N] [--evaluators N] [--people runs/x/people.json]',
+  );
+  process.exit(1);
+}
+// Checked before anything is spent: a wrong code stops the run here.
+let languages: string[];
+try {
+  languages = parseLanguages(values.languages);
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}
+const size = resolveRunSize({
+  tier: values.tier,
+  units: values.agents !== undefined ? Number(values.agents) : undefined,
+  employees: values.employees !== undefined ? Number(values.employees) : undefined,
+});
+const employees = Math.min(Math.max(size.employees || 0, 0), MAX_EMPLOYEES);
+const count = size.units;
+const maxSteps = Number(values["max-steps"]);
+let reused: CustomerUnit[] | undefined;
+try {
+  reused = values.people ? await readPeople(values.people) : undefined;
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}
+if (unitKind === "business" && employees > 0 && !values.mailpit) {
+  console.warn("Business crews need --mailpit for invites; employees will be recorded as not invited.");
+}
+
+// Before anything is spent: what could this run cost?
+const navModel = process.env.DEBUTLY_NAV_MODEL ?? (process.env.DEBUTLY_PROVIDER === "openai-compatible" ? "" : "claude-haiku-4-5");
+const agents = reused ? peopleCount(reused) : agentCount(unitKind, { ...size, employees });
+const price = await fetchModelPrice(navModel);
+const evaluatorCount = values.evaluators !== undefined ? Number(values.evaluators) : 0;
+const depthEstimate = estimateRunCost({ agents, maxSteps, price });
+const breadthEstimate = evaluatorCount ? estimatePerceptionCost({ evaluators: evaluatorCount, experiment: false, price }) : { low: 0, high: 0 };
+const estimate = depthEstimate && breadthEstimate ? { low: depthEstimate.low + breadthEstimate.low, high: depthEstimate.high + breadthEstimate.high } : null;
+console.log(
+  estimate
+    ? `Estimated cost: $${estimate.low.toFixed(2)}–$${estimate.high.toFixed(2)} (${agents} agents × up to ${maxSteps} steps${evaluatorCount ? ` + ${evaluatorCount} evaluators` : ""} on ${navModel})`
+    : `Estimated cost: unknown (no price found for ${navModel})`,
+);
+if (values["max-cost"] !== undefined) {
+  const ceiling = Number(values["max-cost"]);
+  if (!estimate) {
+    console.error(`Refusing to start: --max-cost is set but the price of ${navModel} is unknown.`);
+    process.exit(1);
+  }
+  if (estimate.high > ceiling) {
+    console.error(`Refusing to start: this run could cost up to $${estimate.high.toFixed(2)}, above --max-cost $${ceiling.toFixed(2)}.`);
+    process.exit(1);
+  }
+}
+
+// A key with a spending limit says what it has left: don't start a run it can't finish.
+const credits = creditCheck(await keyCreditsLeft(process.env.DEBUTLY_BASE_URL ?? "", process.env.DEBUTLY_API_KEY ?? ""), estimate);
+if (credits.refuse) {
+  console.error(`Refusing to start: ${credits.refuse}`);
+  process.exit(1);
+}
+if (credits.warn) console.warn(`Warning: ${credits.warn}`);
+
+const { nav, judge } = createLlms(process.env);
+let units: CustomerUnit[];
+if (reused) {
+  console.log(`The same ${agents} agents as before, from ${values.people}:`);
+  units = reused;
+} else {
+  console.log(`Generating ${count} ${unitKind === "business" ? `business crew(s) with ${employees} employees each` : "individual(s)"}...`);
+  units = await generateUnits(judge, values.icp, { kind: unitKind, count, employees, languages });
+  if (values.inclusion !== "off") {
+    const dayOfYear = Math.floor((Date.now() - Date.UTC(new Date().getUTCFullYear(), 0, 1)) / 86_400_000);
+    units = withInclusion(units, dayOfYear);
+  }
+  units = withLanguages(units, languages);
+}
+
+const describe = (p: Persona) =>
+  `${p.id} ${p.name}${p.role ? ` (${p.role})` : ""}${p.inclusion ? ` [${p.inclusion.replace(/_/g, " ")}]` : ""}${p.language && p.language !== "en" ? ` [${languageName(p.language)}]` : ""}: ${p.background}`;
+for (const u of units) {
+  if (u.kind === "individual") console.log(`  ${describe(u.person)}`);
+  else {
+    console.log(`  ${u.id} ${u.business.name}, ${u.business.archetype} of ~${u.business.size}, $${u.business.monthlyBudget}/mo`);
+    for (const p of [u.owner, ...u.employees]) console.log(`    ${describe(p)}`);
+  }
+}
+
+if (values.queue && (!values.store || values.store === "memory:")) {
+  console.error("--queue needs --store postgres://…: workers record the agents there.");
+  process.exit(1);
+}
+const outDir = values.out ?? `runs/${new Date().toISOString().replace(/[:.]/g, "-")}`;
+const opened = values.store ? await openDb(values.store) : undefined;
+const store = opened ? new PgRunStore(opened.db) : undefined;
+const origin = runOrigin({ app: values.app, trigger: values.trigger, ciUrl: values["ci-url"] }, process.env);
+const runId = store
+  ? await store.createRun({ ...origin, targetUrl: values.url, goal: values.goal, icp: values.icp, tier: size.tier, unitKind, model: navModel, estimate })
+  : undefined;
+// Screenshots: S3 when it is configured; otherwise, with a store, the database (compact JPEGs,
+// old ones pruned) as well as the run folder, so the dashboard has them with nothing but Postgres.
+const s3 = runId ? S3ArtifactStore.fromEnv(process.env, runId) : undefined;
+let artifacts: ArtifactStore | undefined = s3;
+if (!s3 && opened && runId && values.store !== "memory:") {
+  const pruned = await DbArtifactStore.prune(opened.db, Number(values["screenshot-days"]));
+  if (pruned) console.log(`Pruned ${pruned} screenshots older than ${values["screenshot-days"]} days from the store.`);
+  artifacts = new TeeArtifactStore([new LocalArtifactStore(join(outDir, "screenshots")), new DbArtifactStore(opened.db, runId)]);
+}
+if (runId) console.log(`Run ${runId} (cancel from anywhere with: npm run debutly:cancel -- ${runId} --store <url>)`);
+
+// Kill switch: the first Ctrl+C lets agents stop at their next step and still writes
+// the report; a second one exits at once.
+let cancelled = false;
+process.on("SIGINT", () => {
+  if (cancelled) process.exit(130);
+  cancelled = true;
+  console.warn("\nCancelling: agents stop at their next step (Ctrl+C again to quit now)...");
+  if (store && runId) void store.requestCancel(runId);
+});
+
+const queue = values.queue ? new Queue(AGENT_QUEUE, { connection: redisClient(values.queue) }) : undefined;
+const queueEvents = values.queue ? new QueueEvents(AGENT_QUEUE, { connection: redisClient(values.queue) }) : undefined;
+const caps = {
+  maxTokens: values["agent-token-cap"] !== undefined ? Number(values["agent-token-cap"]) : undefined,
+  maxMs: values["agent-minutes"] !== undefined ? Number(values["agent-minutes"]) * 60_000 : undefined,
+};
+
+console.log(`Running against ${values.url}${values.mailpit ? " (with inboxes)" : ""}...`);
+const result = await runSimulation({
+  url: values.url,
+  goal: values.goal,
+  units,
+  llm: nav,
+  maxSteps,
+  concurrency: Number(values.concurrency),
+  outDir,
+  inbox: values.mailpit ? new MailpitInbox(values.mailpit) : undefined,
+  emailDomain: values["email-domain"],
+  sandboxOutbox: values["sandbox-outbox"] ? new HttpSandboxOutbox(values["sandbox-outbox"], process.env.DEBUTLY_SANDBOX_TOKEN ?? "") : undefined,
+  store,
+  runId,
+  price,
+  caps,
+  shouldStop: () => cancelled,
+  artifacts,
+  browserStateDir: values["browser-state"],
+  dispatch:
+    queue && queueEvents && runId
+      ? ({ runTag }) =>
+          queueDispatch(queue, queueEvents, {
+            runId,
+            targetUrl: values.url!,
+            maxSteps,
+            caps,
+            price,
+            mailpitUrl: values.mailpit,
+            emailDomain: values["email-domain"] ?? "agents.test",
+            runTag,
+          })
+      : undefined,
+});
+await queueEvents?.close();
+await queue?.close();
+await opened?.close();
+
+if (evaluatorCount > 0) {
+  console.log(`${evaluatorCount} evaluators judging the pages the agents saw...`);
+  const perception = await runPerception({
+    llm: nav,
+    judge,
+    icp: values.icp,
+    product: values.url,
+    exhibitsByVariant: { main: exhibitsFromSessions(result.sessions) },
+    evaluators: evaluatorCount,
+    concurrency: Math.max(Number(values.concurrency), 8),
+    price,
+    judgePrice: await fetchModelPrice(process.env.DEBUTLY_JUDGE_MODEL ?? ""),
+    functional: result.findings,
+  });
+  const readiness = join(outDir, "launch-readiness.md");
+  await writeFile(readiness, renderLaunchReadiness({ target: values.url, icp: values.icp, result: perception, functional: result.findings }));
+  console.log(`Launch Readiness: ${readiness}`);
+}
+
+const noCredit = result.sessions.filter((s) => s.outcome === "error" && s.outcomeNote.startsWith(OUT_OF_CREDITS)).length;
+if (noCredit) {
+  const message = `The AI provider account ran out of credits: ${noCredit} of ${result.sessions.length} agents stopped early. Top up and run again.`;
+  // On GitHub Actions, an annotation puts it on the run's summary page.
+  console.error(process.env.GITHUB_ACTIONS ? `::error title=Debutly run cut short::${message}` : message);
+}
+const cost = result.usage.costUsd !== undefined ? `, cost $${result.usage.costUsd.toFixed(4)}` : "";
+console.log(`Done: ${result.findings.length} findings${cost}. Report: ${result.reportPath}${runId ? ` (run ${runId})` : ""}`);

package/src/config.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Settings for `debutly run`, kept in the app's repo so a run needs no flags. */
+export const CONFIG_FILE = "debutly.json";
+
+// What debutly.json may set: the run's flags, camelCased. The store's address is a secret, so it
+// comes from DEBUTLY_STORE_URL instead; where reports go and what started a run are per run.
+const SETTINGS = [
+  "url",
+  "goal",
+  "icp",
+  "unit",
+  "tier",
+  "agents",
+  "employees",
+  "maxCost",
+  "inclusion",
+  "maxSteps",
+  "concurrency",
+  "mailpit",
+  "emailDomain",
+  "sandboxOutbox",
+  "app",
+  "screenshotDays",
+  "agentTokenCap",
+  "agentMinutes",
+  "evaluators",
+  "languages",
+] as const;
+
+export type Setting = (typeof SETTINGS)[number];
+export type DebutlyConfig = Partial<Record<Setting, string | number | boolean>> & { $schema?: string };
+
+const flagOf = (setting: string) => `--${setting.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+
+/** The config file in `dir`, or undefined when there is none. */
+export function readConfig(dir: string = process.cwd()): DebutlyConfig | undefined {
+  const path = join(dir, CONFIG_FILE);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("it should hold one JSON object");
+    return parsed as DebutlyConfig;
+  } catch (err) {
+    throw new Error(`${CONFIG_FILE} can't be read: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+/** The config as command-line flags. Flags given on the command line come after, so they win. */
+export function configArgs(config: DebutlyConfig): string[] {
+  const args: string[] = [];
+  for (const [key, value] of Object.entries(config)) {
+    if (key === "$schema" || value === undefined || value === null) continue;
+    if (!(SETTINGS as readonly string[]).includes(key)) {
+      throw new Error(`${CONFIG_FILE}: "${key}" is not a setting. Settings: ${SETTINGS.join(", ")}.`);
+    }
+    if (typeof value === "object") throw new Error(`${CONFIG_FILE}: "${key}" should be text or a number.`);
+    args.push(flagOf(key), key === "inclusion" && typeof value === "boolean" ? (value ? "on" : "off") : String(value));
+  }
+  return args;
+}

package/src/cost/estimate.ts

@@ -0,0 +1,32 @@
+import type { ModelPrice } from "../llm/meter";
+
+export interface CostEstimate {
+  low: number;
+  high: number;
+}
+
+// Typical navigation step on the 2026-09-27/28 runs: ~2,500 prompt tokens (page + history, with
+// provider-side caching) and ~150 reply tokens. That brackets the observed ~$0.08 per 3-agent run.
+// Replace with averages from stored runs once enough are recorded.
+const TOKENS_PER_STEP = { input: 2500, output: 150 };
+
+/** Cost range for a run: agents using 60% (low) to 100% (high) of their step budget. */
+export function estimateRunCost(o: { agents: number; maxSteps: number; price: ModelPrice | null; tokensPerStep?: { input: number; output: number } }): CostEstimate | null {
+  if (!o.price) return null;
+  const t = o.tokensPerStep ?? TOKENS_PER_STEP;
+  const perStep = (t.input * o.price.inputPerMTok + t.output * o.price.outputPerMTok) / 1_000_000;
+  const high = o.agents * o.maxSteps * perStep;
+  return { low: high * 0.6, high };
+}
+
+// One evaluator call: the pages (~3,000 tokens; two variants ~5,000) plus rubric and persona in,
+// a JSON verdict (~450 tokens) out. Persona generation and the summary add little.
+const EVALUATOR_TOKENS = { single: { input: 3500, output: 450 }, experiment: { input: 5500, output: 500 } };
+
+/** Cost range for a perception run: ±20% around the per-call estimate. */
+export function estimatePerceptionCost(o: { evaluators: number; experiment: boolean; price: ModelPrice | null }): CostEstimate | null {
+  if (!o.price) return null;
+  const t = o.experiment ? EVALUATOR_TOKENS.experiment : EVALUATOR_TOKENS.single;
+  const mid = (o.evaluators * (t.input * o.price.inputPerMTok + t.output * o.price.outputPerMTok)) / 1_000_000;
+  return { low: mid * 0.8, high: mid * 1.2 };
+}

package/src/cost/prices.ts

@@ -0,0 +1,32 @@
+import type { ModelPrice } from "../llm/meter";
+
+// USD per million tokens, from OpenRouter's model list on 2026-09-28. Used when it can't be reached.
+const KNOWN: Record<string, ModelPrice> = {
+  "google/gemini-3.8-flash": { inputPerMTok: 0.75, outputPerMTok: 3.75 },
+  "z-ai/glm-5.3-flash": { inputPerMTok: 0.15, outputPerMTok: 0.5 },
+  "deepseek/deepseek-v4-flash": { inputPerMTok: 0.079, outputPerMTok: 0.159 },
+  "anthropic/claude-haiku-4.5": { inputPerMTok: 1, outputPerMTok: 5 },
+  "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5 },
+  "anthropic/claude-sonnet-5": { inputPerMTok: 2, outputPerMTok: 10 },
+  "anthropic/claude-opus-5": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-opus-5": { inputPerMTok: 5, outputPerMTok: 25 },
+};
+
+/** A model's price per million tokens: OpenRouter's live list, then the table above, else null (unknown). */
+export async function fetchModelPrice(model: string, fetchFn: typeof fetch = fetch): Promise<ModelPrice | null> {
+  try {
+    const res = await fetchFn("https://openrouter.ai/api/v1/models");
+    if (res.ok) {
+      const { data = [] } = (await res.json()) as { data?: { id: string; pricing?: { prompt?: string; completion?: string } }[] };
+      const pricing = data.find((m) => m.id === model)?.pricing;
+      const input = Number(pricing?.prompt);
+      const output = Number(pricing?.completion);
+      if (Number.isFinite(input) && Number.isFinite(output) && pricing) {
+        return { inputPerMTok: Math.round(input * 1e9) / 1e3, outputPerMTok: Math.round(output * 1e9) / 1e3 };
+      }
+    }
+  } catch {
+    // Offline or blocked: fall through to the table.
+  }
+  return KNOWN[model] ?? null;
+}