debutly 0.0.0-stage → 0.1.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.1.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,37 @@
+import type { Action, ActionResult, Observation, Signal } from "../types";
+
+const pathOf = (url: string) => {
+  try {
+    const u = new URL(url);
+    return u.pathname;
+  } catch {
+    return url;
+  }
+};
+
+// 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.
+export function describeEffect(action: Action, before: Observation, after: Observation, signals: Signal[], result: ActionResult): 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 (pathOf(after.url) !== pathOf(before.url)) parts.push(`now on ${pathOf(after.url)}`);
+  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/loop.ts

@@ -0,0 +1,232 @@
+import type { Page } 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 { parseAgentReply } from "./parse-reply";
+import { buildStepMessage, buildSystemPrompt, type AgentIdentity } from "./prompt";
+
+const MAX_REPLY_ATTEMPTS = 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 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;
+  try {
+    await page.goto(origin, { waitUntil: "domcontentloaded", timeout: timeoutMs });
+  } catch (err) {
+    if (!(err instanceof Error && err.name === "TimeoutError")) throw err;
+    finished = false;
+  }
+  const ms = Date.now() - startedAt;
+  if (!finished || ms >= slowMs) signals.note({ kind: "slow_load", url: origin, ms, finished, slowNetwork });
+}
+
+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";
+  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);
+      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 = "";
+    // 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);
+        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}.`,
+          },
+        );
+      }
+    }
+    if (!reply) {
+      return end("error", `${problem} | last reply: ${raw.slice(0, 300) || "(empty)"}`);
+    }
+
+    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`);
+}

package/src/agent/parse-reply.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { PRESS_KEYS, type Action } from "../types";
+
+const ActionSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("click"), id: z.number().int() }),
+  z.object({ type: z.literal("fill"), id: z.number().int(), text: z.string() }),
+  z.object({ type: z.literal("upload"), id: z.number().int(), file: z.enum(["photo", "document"]).optional() }),
+  z.object({ type: z.literal("goto"), path: z.string() }),
+  z.object({ type: z.literal("check_email") }),
+  z.object({ type: z.literal("press"), key: z.enum(PRESS_KEYS) }),
+  z.object({ type: z.literal("wait") }),
+  z.object({ type: z.literal("done"), success: z.boolean(), note: z.string() }),
+]);
+
+// Real models sometimes drop the reasoning; the action is what matters.
+const ReplySchema = z.object({ reasoning: z.string().default(""), action: ActionSchema });
+
+export function parseAgentReply(raw: string): { reasoning: string; action: Action } {
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start === -1 || end <= start) throw new Error("no JSON object in agent reply");
+  return ReplySchema.parse(actionAsObject(parseQuotedAction(raw.slice(start, end + 1))));
+}
+
+// Some models (GLM 5.3 Flash) send the action as a string. Unescaped,
+// {"reasoning":"…","action":"{"type":"fill","id":1,"text":"x"}"} is not JSON at all, and asking
+// again got the same reply three times, ending the agent. An action is a flat object, so its
+// quotes can be dropped and the rest parsed as meant. Sometimes the closing quote and brace never
+// come at all; then the reasoning and the action are read out separately.
+function parseQuotedAction(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    const unquoted = text.replace(/("action"\s*:\s*)"(\{[^{}]*\})"/, "$1$2");
+    if (unquoted !== text) {
+      try {
+        return JSON.parse(unquoted);
+      } catch {
+        // fall through to reading the parts
+      }
+    }
+    const parts = readParts(text);
+    if (!parts) throw err;
+    return parts;
+  }
+}
+
+function readParts(text: string): { reasoning: string; action: unknown } | undefined {
+  const action = text.match(/"action"\s*:\s*"?\s*(\{[^{}]*\})/)?.[1];
+  if (!action) return undefined;
+  const reasoning = text.match(/"reasoning"\s*:\s*"((?:[^"\\]|\\.)*)"/)?.[1];
+  try {
+    return { reasoning: reasoning ? JSON.parse(`"${reasoning}"`) : "", action: JSON.parse(action.replace(/\\"/g, '"')) };
+  } catch {
+    return undefined;
+  }
+}
+
+const ACTION_TYPES = new Set(["click", "fill", "upload", "goto", "check_email", "press", "wait", "done"]);
+const ACTION_FIELDS = ["id", "text", "file", "path", "key", "success", "note"] as const;
+
+// Escaped, the same mistake parses, with the action as a string holding its JSON. Or the action is
+// flattened into the reply, {"reasoning":"…","action":"click","id":40}: its type as a string, its
+// fields beside it (2026-10-18; asking again got the same reply).
+function actionAsObject(reply: unknown): unknown {
+  if (!reply || typeof reply !== "object" || typeof (reply as { action?: unknown }).action !== "string") return reply;
+  const r = reply as Record<string, unknown> & { action: string };
+  try {
+    return { ...r, action: JSON.parse(r.action) };
+  } catch {
+    if (!ACTION_TYPES.has(r.action)) return reply; // the schema says what is wrong with it
+    const action: Record<string, unknown> = { type: r.action };
+    for (const field of ACTION_FIELDS) if (field in r) action[field] = r[field];
+    return { reasoning: r.reasoning, action };
+  }
+}

package/src/agent/prompt.ts

@@ -0,0 +1,76 @@
+import { inclusionBrief } from "../persona/inclusion";
+import { languageBrief } from "../persona/language";
+import type { InteractiveElement, Observation, Persona } from "../types";
+
+// Stays constant for the whole session so providers can cache it; everything that changes goes in the user message.
+export interface AgentIdentity {
+  email: string;
+}
+
+// `brief` carries shared context, e.g. the company a crew member works at and what their owner reported.
+export function buildSystemPrompt(persona: Persona, goal: string, identity?: AgentIdentity, brief?: string): string {
+  const email = identity
+    ? `Your email address is ${identity.email}. Use it whenever the site asks for your email.
+To read your inbox (for example a login link or a confirmation), reply {"type":"check_email"}. To open a link from an email, use {"type":"goto","path":"<the full link>"}.`
+    : `Use emails at example.com.`;
+  const about = [
+    `You are ${persona.name}. ${persona.background}`,
+    `Patience: ${persona.patience}. Tech savvy: ${persona.techSavvy}.`,
+    persona.role ? `Your role: ${persona.role}.` : "",
+    brief ?? "",
+    persona.inclusion ? inclusionBrief(persona.inclusion) : "",
+    languageBrief(persona.language),
+  ]
+    .filter(Boolean)
+    .join("\n");
+  return `${about}
+
+You are a real prospective customer using this web product for the first time. Act exactly as this person would: read what is on screen, decide what they would do next, and react honestly to confusion or breakage. If something fails, try a reasonable alternative like a real person. Give up (done with success false) at the point this person would give up, and say why.
+
+Your goal: ${goal}
+
+${email}
+Use test data only: card number 4242 4242 4242 4242. Never enter real personal or payment data.
+
+Reply with exactly one JSON object: {"reasoning": string, "action": Action}
+Action is one of:
+{"type":"click","id":number}
+{"type":"fill","id":number,"text":string}  (on a select or dropdown, text is the option to choose)
+{"type":"upload","id":number,"file":"photo"|"document"}  (attach a file through an upload button or file field: you have a sample photo and a sample CV/document)
+{"type":"goto","path":string}
+{"type":"press","key":"Escape"|"Enter"|"Tab"|"ArrowDown"|"ArrowUp"}  (e.g. Escape closes a popup that blocks the page)
+{"type":"wait"}  (the page is still loading, e.g. a spinner or a form that has not appeared yet: wait a few seconds rather than leave)${identity ? `\n{"type":"check_email"}` : ""}
+{"type":"done","success":boolean,"note":string}`;
+}
+
+function describeElement(e: InteractiveElement, screenReader = false): string {
+  // A screen reader announces the role and name the browser gives it.
+  const heard = screenReader && e.ax ? e.ax : e;
+  const line = `[${e.id}] ${heard.role} "${heard.name}"`;
+  if (!e.options) return line;
+  return `${line} set to "${e.value ?? ""}", options: ${e.options.map((o) => `"${o}"`).join(" | ")}`;
+}
+
+export interface StepView {
+  /** As a screen reader presents the page: the browser's names and roles, without what is hidden from it. */
+  screenReader?: boolean;
+}
+
+export function buildStepMessage(obs: Observation, history: string[], view: StepView = {}): string {
+  const shown = view.screenReader ? obs.elements.filter((e) => !e.ax?.hidden) : obs.elements;
+  const elements = shown.map((e) => describeElement(e, view.screenReader)).join("\n");
+  const past = history.length ? history.map((h, i) => `${i + 1}. ${h}`).join("\n") : "(none yet)";
+  return `URL: ${obs.url}
+Title: ${obs.title}
+
+Interactive elements:
+${elements}
+
+Visible text:
+${obs.text}
+
+Your actions so far:
+${past}
+
+What do you do next?`;
+}

package/src/agent/run-agent.ts

@@ -0,0 +1,68 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Browser } from "playwright";
+import type { ArtifactStore } from "../artifacts/store";
+import type { Inbox } from "../inbox/types";
+import type { ModelPrice } from "../llm/meter";
+import type { LlmClient } from "../llm/types";
+import { openAgentPage } from "../persona/inclusion";
+import type { RunStore } from "../store/run-store";
+import type { Persona, Session } from "../types";
+import { runSession } from "./loop";
+
+export interface AgentRunDeps {
+  browser: Browser;
+  llm: LlmClient;
+  origin: string;
+  maxSteps: number;
+  artifacts: ArtifactStore;
+  emailOf: (persona: Persona) => string;
+  inbox?: Inbox;
+  caps?: { maxTokens?: number; maxMs?: number };
+  price?: ModelPrice | null;
+  shouldStop?: () => boolean | Promise<boolean>;
+  /** With a store and run id, the session and each step are recorded as they happen. */
+  store?: RunStore;
+  runId?: string;
+  /** Keeps the agent's browser state here as <agent id>.json when it finishes, for `debutly hear`. */
+  browserStateDir?: string;
+}
+
+/**
+ * One agent, start to finish, in its own browser context (no shared cookies or login, even
+ * inside a crew). Used in-process by runSimulation and by queue workers alike.
+ */
+export async function runAgentSession(d: AgentRunDeps, persona: Persona, goal: string, brief: string | undefined): Promise<Session> {
+  const record = d.store && d.runId ? { store: d.store, runId: d.runId } : undefined;
+  const { context, page } = await openAgentPage(d.browser, persona.inclusion, persona.language);
+  if (record) await record.store.startSession(record.runId, persona.id, goal);
+  let session: Session;
+  try {
+    session = await runSession({
+      page,
+      llm: d.llm,
+      persona,
+      goal,
+      origin: d.origin,
+      maxSteps: d.maxSteps,
+      artifacts: d.artifacts,
+      identity: d.inbox ? { email: d.emailOf(persona) } : undefined,
+      inbox: d.inbox,
+      brief,
+      caps: d.caps,
+      price: d.price,
+      shouldStop: d.shouldStop,
+      onStep: record ? (step) => record.store.appendStep(record.runId, persona.id, step) : undefined,
+    });
+  } catch (err) {
+    session = { agentId: persona.id, personaName: persona.name, goal, steps: [], outcome: "error", outcomeNote: err instanceof Error ? err.message : String(err) };
+  } finally {
+    if (d.browserStateDir) {
+      await mkdir(d.browserStateDir, { recursive: true });
+      await context.storageState({ path: join(d.browserStateDir, `${persona.id}.json`) }).catch(() => {});
+    }
+    await context.close();
+  }
+  if (record) await record.store.finishSession(record.runId, session);
+  return session;
+}