debutly 0.0.0-stage → 0.2.0

package/drizzle/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1790627348170,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1790631168176,
+      "tag": "0001_predictions",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1791025761130,
+      "tag": "0002_dashboard",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "debutly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Rehearse your launch: AI agents use your web app like your first customers and report what breaks.",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "author": "Chetan Sroay (https://github.com/sroay)",
+  "homepage": "https://debutly.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sroay/debutly.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sroay/debutly/issues"
+  },
+  "keywords": [
+    "testing",
+    "e2e",
+    "ai-agents",
+    "playwright",
+    "llm",
+    "synthetic-users",
+    "qa",
+    "launch"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "bin": {
+    "debutly": "bin/debutly.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "drizzle/",
+    "tsconfig.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "workspaces": [
+    "dashboard"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "fixture": "tsx fixture/main.ts",
+    "debutly": "tsx src/cli.ts",
+    "debutly:cancel": "tsx src/cancel.ts",
+    "debutly:worker": "tsx src/worker.ts",
+    "debutly:predictions": "tsx src/predictions.ts",
+    "debutly:perceive": "tsx src/perceive.ts",
+    "debutly:costs": "tsx src/costs.ts",
+    "debutly:import": "tsx src/import.ts",
+    "dashboard": "npm run dev -w dashboard",
+    "dashboard:build": "npm run build -w dashboard",
+    "docs": "tsx scripts/build-docs.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.128.0",
+    "@aws-sdk/client-s3": "^3.1142.0",
+    "@electric-sql/pglite": "^0.5.8",
+    "bullmq": "^6.3.9",
+    "drizzle-orm": "^0.45.3",
+    "express": "^5.2.1",
+    "ioredis": "^5.11.1",
+    "playwright": "^1.63.0",
+    "postgres": "^3.4.9",
+    "tsx": "^4.23.15",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.3",
+    "drizzle-kit": "^0.31.11",
+    "marked": "18.0.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@guidepup/guidepup": "0.36.4"
+  }
+}

package/src/agent/describe.ts

@@ -0,0 +1,29 @@
+import type { Action, Observation } from "../types";
+
+export function describeAction(action: Action, obs: Observation): string {
+  const target = (id: number) => {
+    const el = obs.elements.find((e) => e.id === id);
+    return el ? `${el.role} "${el.name}"` : `element #${id}`;
+  };
+  switch (action.type) {
+    case "click":
+      return `clicked ${target(action.id)}`;
+    case "fill": {
+      const el = obs.elements.find((e) => e.id === action.id);
+      const picks = el && (el.tag === "select" || (el.role === "combobox" && el.tag !== "input" && el.tag !== "textarea"));
+      return picks ? `chose "${action.text}" in ${target(action.id)}` : `typed "${action.text}" into ${target(action.id)}`;
+    }
+    case "upload":
+      return `uploaded the sample ${action.file ?? "file"} with ${target(action.id)}`;
+    case "goto":
+      return `went to ${action.path}`;
+    case "check_email":
+      return "checked email";
+    case "press":
+      return `pressed ${action.key}`;
+    case "wait":
+      return "waited for the page to load";
+    case "done":
+      return `finished (${action.success ? "success" : "gave up"}): ${action.note}`;
+  }
+}

package/src/agent/effect.ts

@@ -0,0 +1,94 @@
+import type { Action, ActionResult, InteractiveElement, Observation, Signal } from "../types";
+import { controlLabel, type StepView } from "./label";
+
+const pathOf = (url: string) => {
+  try {
+    const u = new URL(url);
+    return u.pathname;
+  } catch {
+    return url;
+  }
+};
+
+const MAX_LISTED = 4;
+const MAX_LINE = 80;
+
+type Label = (e: InteractiveElement) => string;
+
+/** Controls in `a` beyond those in `b`, counting copies: a second "Untitled" row is new. */
+function beyond(a: InteractiveElement[], b: InteractiveElement[], controlOf: Label): InteractiveElement[] {
+  const left = new Map<string, number>();
+  for (const e of b) left.set(controlOf(e), (left.get(controlOf(e)) ?? 0) + 1);
+  return a.filter((e) => {
+    const n = left.get(controlOf(e)) ?? 0;
+    if (n > 0) left.set(controlOf(e), n - 1);
+    return n === 0;
+  });
+}
+
+/** Controls still there whose state changed: a Save button now enabled, a box now checked. */
+function stateChanges(before: InteractiveElement[], after: InteractiveElement[], controlOf: Label): string[] {
+  const out: string[] = [];
+  for (const a of after) {
+    const b = before.find((e) => controlOf(e) === controlOf(a));
+    if (!b) continue;
+    if (!!b.disabled !== !!a.disabled) out.push(`now ${a.disabled ? "disabled" : "enabled"} ${controlOf(a)}`);
+    if (b.checked !== undefined && a.checked !== undefined && b.checked !== a.checked) out.push(`now ${a.checked ? "checked" : "unchecked"} ${controlOf(a)}`);
+    if (b.expanded !== undefined && a.expanded !== undefined && b.expanded !== a.expanded) out.push(`now ${a.expanded ? "open" : "closed"} ${controlOf(a)}`);
+  }
+  return out;
+}
+
+const listed = (items: string[]) => items.slice(0, MAX_LISTED).join(", ") + (items.length > MAX_LISTED ? `, and ${items.length - MAX_LISTED} more` : "");
+
+/**
+ * What changed on the page, as a person would notice it: controls that appeared or went, state
+ * that changed, and new lines of text. Told only "the page changed", agents missed a password
+ * field that had appeared, pressed "Create company" seven times without seeing seven new rows,
+ * and kept retyping values while waiting for a Save button to wake up.
+ */
+function whatChanged(before: Observation, after: Observation, controlOf: Label): string {
+  const appeared = beyond(after.elements, before.elements, controlOf);
+  const gone = beyond(before.elements, after.elements, controlOf);
+  const names = new Set(after.elements.map((e) => e.name));
+  const had = new Set(before.text.split("\n").map((l) => l.trim()));
+  const newText = [...new Set(after.text.split("\n").map((l) => l.trim()))].filter((l) => l && !had.has(l) && !names.has(l)).map((l) => `"${l.slice(0, MAX_LINE)}"`);
+  const parts = [
+    appeared.length ? `new ${listed(appeared.map(controlOf))}` : "",
+    gone.length ? `gone ${listed(gone.map(controlOf))}` : "",
+    ...stateChanges(before.elements, after.elements, controlOf).slice(0, MAX_LISTED),
+    newText.length ? `new text ${listed(newText)}` : "",
+  ].filter(Boolean);
+  return parts.length ? `the page changed: ${parts.join("; ")}` : "";
+}
+
+// What a person would notice after acting: where they are now, whether anything changed,
+// and whether something visibly broke. Without this, agents retry dead buttons forever.
+// Controls are named as the agent meets them, as in its step message.
+export function describeEffect(action: Action, before: Observation, after: Observation, signals: Signal[], result: ActionResult, view: StepView = {}): string {
+  if (result.blocked) return `blocked: ${result.blocked}`;
+  if (result.error) return `failed: ${result.error}`;
+  // check_email reports its own result; done ends the session.
+  if (action.type === "done" || action.type === "check_email") return "";
+
+  const parts: string[] = [];
+  if (result.enterIgnored) parts.push("Enter did nothing on it, so Space was pressed instead");
+  const changed = whatChanged(before, after, (e) => controlLabel(e, view.screenReader));
+  if (pathOf(after.url) !== pathOf(before.url)) parts.push(`now on ${pathOf(after.url)}`);
+  else if (changed) parts.push(changed);
+  else if (after.text !== before.text) parts.push("the page changed");
+  else if (action.type !== "fill" && !signals.some((s) => s.kind === "download")) parts.push("nothing visibly changed");
+
+  for (const s of signals) if (s.kind === "download") parts.push(`a file downloaded: ${s.filename}`);
+
+  for (const s of signals) if (s.kind === "dialog") parts.push(`a ${s.dialogType} dialog said "${s.message}" (answered OK)`);
+  if (signals.some((s) => s.kind === "page_error")) parts.push("a JavaScript error occurred");
+  const failed = [
+    ...new Set(
+      signals.filter((s) => s.kind === "http_error" && pathOf(s.requestUrl) !== "/favicon.ico").map((s) => (s.kind === "http_error" ? s.status : 0)),
+    ),
+  ];
+  for (const status of failed) parts.push(`a request failed (HTTP ${status})`);
+
+  return parts.join("; ");
+}

package/src/agent/give-up.ts

@@ -0,0 +1,42 @@
+import type { Observation, Step } from "../types";
+
+// What a person presses before giving up: to go on, join, sign in or start, or to add or create
+// what they came to add (agents said adding a person was "missing" beside "Add person").
+// Arabic too, as agents often use Arabic interfaces.
+const WAY_ON =
+  /^(continue|next|proceed|join\b.*|accept\b.*|sign ?in|log ?in|sign ?up|create (an )?account|get started|start|confirm|verify|submit|(add|create|new)\b.*|استمر|متابعة|التالي|انضم.*|قبول.*|تسجيل الدخول|ابدأ.*|تأكيد|إرسال|(إنشاء|أضف|إضافة).*)$/i;
+// Buttons only: a page's own way on. A "Sign up" link in the site's menu is not one from where it stands.
+const PRESSABLE = /^(button|input:(submit|button))$/;
+
+const pathOf = (url: string) => {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+};
+
+/**
+ * The ways on that an agent about to give up hasn't tried on the page it is on: enabled buttons
+ * named like Continue, Join or Sign in that it hasn't pressed since it came to this page.
+ * A teammate agent gave up on Twenty's invite page saying there was "no way into the workspace",
+ * with a Continue button under its eyes (2026-10-25), and the report blamed the app.
+ */
+export function untriedWaysOn(obs: Observation, steps: Step[], screenReader = false): string[] {
+  const path = pathOf(obs.url);
+  const pressed = new Set<string>();
+  for (let i = steps.length - 1; i >= 0 && pathOf(steps[i].observation.url) === path; i--) {
+    const { action, observation } = steps[i];
+    if (action.type !== "click") continue;
+    const el = observation.elements.find((e) => e.id === action.id);
+    if (el) pressed.add((el.ax?.name || el.name).trim().toLowerCase());
+  }
+  const names = obs.elements
+    .filter((e) => PRESSABLE.test(e.role) && !e.disabled && !(screenReader && e.ax?.hidden))
+    .map((e) => (screenReader && e.ax ? e.ax.name : e.name || e.ax?.name || "").trim())
+    .filter((name) => WAY_ON.test(name) && !pressed.has(name.toLowerCase()));
+  return [...new Set(names)].slice(0, 3);
+}
+
+/** A page with nothing to press is often still arriving: one agent on a slow connection gave up the moment an invite page opened. */
+export const nothingToPressYet = (obs: Observation) => obs.elements.length === 0;

package/src/agent/label.ts

@@ -0,0 +1,19 @@
+import type { InteractiveElement } from "../types";
+
+// Apart from prompt.ts, which needs the browser (Playwright) through the inclusion briefs: the
+// dashboard imports effect.ts, and its build has no Playwright.
+
+export interface StepView {
+  /** As a screen reader presents the page: the browser's names and roles, without what is hidden from it. */
+  screenReader?: boolean;
+}
+
+/**
+ * A control as the agent meets it. A screen reader announces the role and name the browser gives
+ * it; a sighted person looking at a control with no text sees its icon.
+ */
+export function controlLabel(e: InteractiveElement, screenReader = false): string {
+  const heard = screenReader && e.ax ? e.ax : e;
+  const icon = !screenReader && !e.name && e.icon ? ` (${e.icon} icon)` : "";
+  return `${heard.role} "${heard.name}"${icon}`;
+}

package/src/agent/loop.ts

@@ -0,0 +1,302 @@
+import type { Page, Request } from "playwright";
+import type { ArtifactStore } from "../artifacts/store";
+import { execute } from "../browser/execute";
+import { observe } from "../browser/observe";
+import { ReflowMeter } from "../browser/reflow";
+import { settle, type SettleOptions } from "../browser/settle";
+import { SignalCollector } from "../browser/signals";
+import type { EmailMessage, Inbox } from "../inbox/types";
+import { Meter, type ModelPrice } from "../llm/meter";
+import type { LlmClient, LlmMessage } from "../llm/types";
+import type { ActionResult, Persona, Session, Step } from "../types";
+import { describeAction } from "./describe";
+import { describeEffect } from "./effect";
+import { nothingToPressYet, untriedWaysOn } from "./give-up";
+import { NoActionError, parseAgentReply } from "./parse-reply";
+import { buildStepMessage, buildSystemPrompt, type AgentIdentity } from "./prompt";
+
+const MAX_REPLY_ATTEMPTS = 3;
+/** Steps a session may wait for want of an action in the reply, before that is an engine error. */
+const MAX_NO_ACTION_WAITS = 3;
+const LINKS_PER_EMAIL = 3;
+/** How long the first page may take to arrive; a slow-connection agent needs more than 30 s. */
+const FIRST_LOAD_MS = 90_000;
+/** A first page slower than this is reported. */
+const SLOW_LOAD_MS = 10_000;
+/** How long a slow first page's scripts and styles may take to be weighed before it is reported without. */
+const WEIGH_MS = 2_000;
+/** How long a step's screenshot may take before the step goes without one. */
+const SCREENSHOT_MS = 15_000;
+
+export interface RunSessionOptions {
+  page: Page;
+  llm: LlmClient;
+  persona: Persona;
+  goal: string;
+  origin: string;
+  maxSteps: number;
+  /** Where step screenshots go (a local folder, or S3); none means no screenshots. */
+  artifacts?: ArtifactStore;
+  identity?: AgentIdentity;
+  inbox?: Inbox;
+  /** Shared context for the system prompt, e.g. a crew member's company. */
+  brief?: string;
+  /** Per-agent limits on top of maxSteps. */
+  caps?: { maxTokens?: number; maxMs?: number };
+  /** The run's kill switch, checked before every step. */
+  shouldStop?: () => Promise<boolean> | boolean;
+  /** Prices the session's usage; omitted or null leaves the cost unknown. */
+  price?: ModelPrice | null;
+  /** Called with each step as it completes, e.g. to record it for live views. */
+  onStep?: (step: Step) => Promise<void> | void;
+  /** How long to let each page finish loading before the agent reads it. */
+  settle?: SettleOptions;
+  /** How long the first page may take, and from when it counts as slow (defaults: 90 s, 10 s). */
+  firstLoad?: { timeoutMs?: number; slowMs?: number };
+}
+
+function describeInbox(messages: EmailMessage[]): string {
+  if (!messages.length) return "checked email → no emails yet";
+  const items = messages.map((m) => `"${m.subject}"${m.links.length ? ` links: ${m.links.slice(0, LINKS_PER_EMAIL).join(" ")}` : ""}`);
+  return `checked email → ${messages.length} email${messages.length === 1 ? "" : "s"}: ${items.join("; ")}`;
+}
+
+/**
+ * Open the app the way a person does: wait for the page, but never fail the session because it
+ * is slow. Waiting for every image and font ("load") within Playwright's 30 s ended the
+ * slow-connection agents on a test app's home page before their first step, two nights running.
+ * Now the agent starts once the document is in (settle() waits for the rest), with up to
+ * FIRST_LOAD_MS for that; whatever has arrived by then is what it sees, and it can wait or give up.
+ * A slow start is itself a finding.
+ */
+async function openFirstPage(
+  page: Page,
+  origin: string,
+  signals: SignalCollector,
+  slowNetwork: boolean,
+  { timeoutMs = FIRST_LOAD_MS, slowMs = SLOW_LOAD_MS }: RunSessionOptions["firstLoad"] = {},
+): Promise<void> {
+  const startedAt = Date.now();
+  let finished = true;
+  // What its scripts and styles weigh as sent, and how much came uncompressed: a test copy served
+  // straight from its container may skip the compression its real hosting does (Twenty's sent
+  // 10 MB uncompressed, 2026-10-24), and then a slow page says more about the copy than the app.
+  const assets = { files: 0, bytes: 0, uncompressedBytes: 0 };
+  const weighing = new Set<Promise<void>>();
+  const weigh = (request: Request) => {
+    if (request.resourceType() !== "script" && request.resourceType() !== "stylesheet") return;
+    const done = (async () => {
+      const [{ responseBodySize }, encoding] = await Promise.all([request.sizes(), request.response().then((r) => r?.headerValue("content-encoding"))]);
+      assets.files++;
+      assets.bytes += responseBodySize;
+      if (!encoding || encoding === "identity") assets.uncompressedBytes += responseBodySize;
+    })()
+      .catch(() => {}) // the page moved on before it could be weighed
+      .finally(() => weighing.delete(done));
+    weighing.add(done);
+  };
+  page.on("requestfinished", weigh);
+  try {
+    await page.goto(origin, { waitUntil: "domcontentloaded", timeout: timeoutMs });
+  } catch (err) {
+    if (!(err instanceof Error && err.name === "TimeoutError")) throw err;
+    finished = false;
+  } finally {
+    page.off("requestfinished", weigh);
+  }
+  const ms = Date.now() - startedAt;
+  if (!finished || ms >= slowMs) {
+    await Promise.race([Promise.allSettled([...weighing]), new Promise((resolve) => setTimeout(resolve, WEIGH_MS))]);
+    signals.note({ kind: "slow_load", url: origin, ms, finished, slowNetwork, ...(assets.files ? { assets: { ...assets } } : {}) });
+  }
+}
+
+export async function runSession(o: RunSessionOptions): Promise<Session> {
+  const signals = new SignalCollector(o.page);
+  const system = buildSystemPrompt(o.persona, o.goal, o.inbox ? o.identity : undefined, o.brief);
+  const steps: Step[] = [];
+  const history: string[] = [];
+  const emailedLinks = new Set<string>();
+  const meter = new Meter();
+  const startedAt = Date.now();
+  const base = { agentId: o.persona.id, personaName: o.persona.name, goal: o.goal, steps };
+  // The low-vision agent's pages, each measured at 320 CSS pixels wide as it arrives (WCAG 1.4.10).
+  const reflow = o.persona.inclusion === "low_vision" ? new ReflowMeter() : undefined;
+  // Every way out of the session carries what it spent, and what it measured.
+  const end = (outcome: Session["outcome"], outcomeNote: string): Session => ({
+    ...base,
+    outcome,
+    outcomeNote,
+    usage: { ...meter.total, costUsd: meter.costUsd(o.price) },
+    ...(reflow?.checks.length ? { reflow: [...reflow.checks] } : {}),
+  });
+
+  await openFirstPage(o.page, o.origin, signals, o.persona.inclusion === "slow_connection", o.firstLoad);
+
+  // A failure part-way (the provider out of credits, the browser gone) still ends the session
+  // with the steps it took: they hold findings, and they were paid for.
+  try {
+    return await takeSteps(o, { signals, system, steps, history, emailedLinks, meter, startedAt, end, reflow });
+  } catch (err) {
+    return end("error", err instanceof Error ? err.message : String(err));
+  }
+}
+
+interface SessionState {
+  signals: SignalCollector;
+  system: string;
+  steps: Step[];
+  history: string[];
+  emailedLinks: Set<string>;
+  meter: Meter;
+  startedAt: number;
+  end: (outcome: Session["outcome"], outcomeNote: string) => Session;
+  reflow?: ReflowMeter;
+}
+
+async function takeSteps(o: RunSessionOptions, { signals, system, steps, history, emailedLinks, meter, startedAt, end, reflow }: SessionState): Promise<Session> {
+  // The screen-reader agent hears what the browser tells assistive technology and works by keyboard.
+  const screenReader = o.persona.inclusion === "screen_reader";
+  let noActionWaits = 0;
+  const askedBeforeGivingUp = new Set<string>();
+  for (let index = 0; index < o.maxSteps; index++) {
+    if (o.shouldStop && (await o.shouldStop())) return end("cancelled", "run cancelled");
+    const { inputTokens, outputTokens } = meter.total;
+    if (o.caps?.maxTokens !== undefined && inputTokens + outputTokens >= o.caps.maxTokens) {
+      return end("budget_exhausted", `stopped at the token cap (${o.caps.maxTokens} tokens)`);
+    }
+    if (o.caps?.maxMs !== undefined && Date.now() - startedAt >= o.caps.maxMs) {
+      return end("budget_exhausted", `stopped at the time cap (${Math.round(o.caps.maxMs / 1000)}s)`);
+    }
+    await settle(o.page, o.settle);
+    await reflow?.measure(o.page);
+    const observation = await observe(o.page);
+    // Now that we can see the page after the previous action, tell the agent what it did.
+    const prev = steps.at(-1);
+    if (prev) {
+      const effect = describeEffect(prev.action, prev.observation, observation, prev.signals, prev, { screenReader });
+      if (effect) history[history.length - 1] += ` → ${effect}`;
+    }
+    const messages: LlmMessage[] = [{ role: "user", content: buildStepMessage(observation, history, { screenReader }) }];
+    let reply: ReturnType<typeof parseAgentReply> | undefined;
+    let raw = "";
+    let problem = "";
+    let noAction: NoActionError | undefined;
+    // Real models occasionally send prose, an empty reply or malformed JSON; say what was wrong and ask again.
+    for (let attempt = 0; attempt < MAX_REPLY_ATTEMPTS && !reply; attempt++) {
+      raw = await o.llm.complete({ system, messages: [...messages], maxTokens: 4096, onUsage: meter.add });
+      try {
+        reply = parseAgentReply(raw);
+      } catch (err) {
+        problem = err instanceof Error ? err.message : String(err);
+        noAction = err instanceof NoActionError ? err : undefined;
+        messages.push(
+          { role: "assistant", content: raw || "(empty reply)" },
+          {
+            role: "user",
+            content: `Your last reply was not valid: ${problem.slice(0, 300)}\nReply with only one JSON object: {"reasoning": string, "action": Action}.`,
+          },
+        );
+      }
+    }
+    // Asked three times, GLM 5.3 Flash went on sending only its reasoning, often "I will wait", and
+    // the agent ended on an engine error (2026-10-24). It waits instead, as someone unsure what to
+    // do next would; not for ever.
+    if (!reply && noAction && noActionWaits < MAX_NO_ACTION_WAITS) {
+      noActionWaits++;
+      reply = { reasoning: noAction.reasoning, action: { type: "wait" } };
+    }
+    if (!reply) {
+      return end("error", `${problem} | last reply: ${raw.slice(0, 300) || "(empty)"}`);
+    }
+    // Giving up with a way on in plain sight that it never pressed here, or on a page with nothing
+    // to press yet: asked once per page. Still giving up, it gives up.
+    if (reply.action.type === "done" && !reply.action.success && !askedBeforeGivingUp.has(observation.url)) {
+      const wayOn = untriedWaysOn(observation, steps, screenReader);
+      const ask = wayOn.length
+        ? `Before you give up: on this page you haven't tried ${wayOn.map((n) => `"${n}"`).join(", ")}. Someone who wanted to get on would try that first.`
+        : nothingToPressYet(observation)
+          ? "Before you give up: nothing on this page can be pressed yet, so it may still be loading. Someone who wanted to get on would wait a little first."
+          : "";
+      if (ask) {
+        askedBeforeGivingUp.add(observation.url);
+        const again = await o.llm.complete({
+          system,
+          messages: [
+            ...messages,
+            { role: "assistant", content: raw },
+            {
+              role: "user",
+              content: `${ask} Reply again with one JSON object: go on, or give up if you are sure.`,
+            },
+          ],
+          maxTokens: 4096,
+          onUsage: meter.add,
+        });
+        try {
+          reply = parseAgentReply(again);
+        } catch {
+          // an unreadable second answer leaves the first one standing
+        }
+      }
+    }
+
+    let result: ActionResult;
+    let historyLine = describeAction(reply.action, observation);
+    if (reply.action.type === "check_email") {
+      if (!o.inbox || !o.identity) {
+        result = { error: "this agent has no inbox" };
+      } else {
+        try {
+          const mail = await o.inbox.latest(o.identity.email);
+          for (const m of mail) for (const link of m.links) emailedLinks.add(link);
+          historyLine = describeInbox(mail);
+          result = {};
+        } catch (err) {
+          result = { error: err instanceof Error ? err.message : String(err) };
+        }
+      }
+    } else {
+      result = await execute(o.page, reply.action, observation, o.origin, (href) => emailedLinks.has(href), { keyboard: screenReader });
+    }
+
+    let screenshotPath: string | undefined;
+    if (o.artifacts) {
+      // JPEG where the store asks for it (the database keeps them small); PNG otherwise. A
+      // screenshot that fails (one timed out on a slow page) costs this step
+      // its picture, not the agent its session.
+      const format = o.artifacts.screenshotFormat;
+      try {
+        const shot = await o.page.screenshot({ ...(format ?? {}), timeout: SCREENSHOT_MS });
+        const name = `${o.persona.id}-${String(index).padStart(3, "0")}`;
+        screenshotPath = format
+          ? await o.artifacts.put(`${name}.jpg`, shot, "image/jpeg")
+          : await o.artifacts.put(`${name}.png`, shot, "image/png");
+      } catch (err) {
+        console.warn(`[${o.persona.name}] no screenshot for step ${index}: ${err instanceof Error ? err.message.split("\n")[0] : err}`);
+      }
+    }
+
+    const guessedUrl = reply.action.type === "goto" && !emailedLinks.has(reply.action.path);
+    await signals.settle();
+    const step: Step = {
+      index,
+      observation,
+      action: reply.action,
+      reasoning: reply.reasoning,
+      signals: signals.drain(),
+      screenshotPath,
+      ...result,
+      ...(guessedUrl ? { guessedUrl } : {}),
+    };
+    steps.push(step);
+    await o.onStep?.(step);
+    history.push(historyLine);
+
+    if (reply.action.type === "done") {
+      return end(reply.action.success ? "success" : "gave_up", reply.action.note);
+    }
+  }
+
+  return end("budget_exhausted", `stopped after ${o.maxSteps} steps`);
+}