debutly 0.0.0-stage → 0.2.0

package/src/report/launch-readiness.ts

@@ -0,0 +1,106 @@
+import type { PerceptionResult } from "../perception/run-perception";
+import type { Finding } from "../types";
+
+export interface LaunchReadinessInput {
+  target: string;
+  icp: string;
+  result: PerceptionResult;
+  /** Functional findings from a depth run, when there was one. */
+  functional?: Finding[];
+}
+
+const pct = (x: number) => `${Math.round(x * 100)}%`;
+const label = (category: string) => category.replace(/_/g, " ");
+
+function renderExperiment(r: PerceptionResult): string[] {
+  const p = r.pairAggregate!;
+  const [a, b] = r.variants;
+  const decided = p.winsA + p.winsB;
+  const row = (v: "A" | "B", name: string, wins: number) => `| ${name} | ${wins} of ${decided} | ${v === p.leader ? `${pct(p.interval.low)}–${pct(p.interval.high)}` : ""} | ${(p.reasons[v] ?? []).slice(0, 2).join("; ")} |`;
+  return [
+    `## Variant comparison`,
+    "",
+    `| Variant | Chosen by | 95% interval (leader) | Why buyers chose it |`,
+    `|---|---|---|---|`,
+    row("A", a, p.winsA),
+    row("B", b, p.winsB),
+    "",
+    `${p.neither} of ${r.pairs.length} buyers wanted neither. ${
+      p.decisive
+        ? `**${p.leader === "A" ? a : b} leads decisively**: its interval excludes a 50/50 split.`
+        : `**No decisive winner**: the interval includes a 50/50 split, so this could be noise. Run more evaluators.`
+    }`,
+    `Position check: the option shown first won ${pct(p.firstShownWinShare)} of choices (50% means no order bias).`,
+    "",
+  ];
+}
+
+function renderObjections(r: PerceptionResult): string[] {
+  return r.variants.flatMap((v) => {
+    const a = r.aggregates[v];
+    if (!a.objections.length) return [];
+    return [
+      ...(r.variants.length > 1 ? [`### ${v}`, ""] : []),
+      ...a.objections.slice(0, 6).map((o) => `- **${label(o.category)}** — ${o.buyers} of ${a.evaluators} buyers. ${o.examples.map((e) => `"${e}"`).join(" ")}`),
+      "",
+    ];
+  });
+}
+
+function renderSingle(r: PerceptionResult): string[] {
+  const a = r.aggregates[r.variants[0]];
+  const s = a.meanScores;
+  return [
+    `## How simulated buyers responded`,
+    "",
+    `Of ${a.evaluators} buyers: ${a.intent.yes} would buy, ${a.intent.maybe} might, ${a.intent.no} would not. This is a comparison baseline, not a conversion rate.`,
+    `Average scores (1–5): clarity ${s.clarity.toFixed(1)}, credibility ${s.credibility.toFixed(1)}, value ${s.value.toFixed(1)}, urgency ${s.urgency.toFixed(1)}.`,
+    a.wouldPay.answers
+      ? `Of those who might buy, ${a.wouldPay.answers} named a price: median $${a.wouldPay.medianUsd}/month (${Object.entries(a.wouldPay.plans).map(([plan, n]) => `${plan} ×${n}`).join(", ")}).`
+      : "",
+    "",
+    ...(a.confusions.length
+      ? [`## Confusion points`, "", ...a.confusions.slice(0, 6).map((c) => `- ${c.exhibitId} (${c.count}): ${c.examples.map((e) => `"${e}"`).join(" ")}`), ""]
+      : []),
+  ].filter((line, i, all) => line !== "" || all[i - 1] !== "");
+}
+
+/** The top-level artifact. Comparative, grounded in counts, never a fake percentage. */
+export function renderLaunchReadiness(i: LaunchReadinessInput): string {
+  const r = i.result;
+  const blockers = (i.functional ?? []).filter((f) => f.severity !== "minor" && f.confidence !== "low" && !f.sandboxCause);
+  const cost = r.usage.costUsd !== undefined ? `$${r.usage.costUsd.toFixed(4)}` : "unknown";
+  return [
+    `# Launch Readiness: ${i.target}`,
+    "",
+    `> Simulated evidence — not real traction. ${r.evaluators} AI buyers matching "${i.icp}" judged ${r.mode === "experiment" ? `${r.variants.join(" vs ")}` : "the product"}; ${r.unusable} replies were unusable and left out.`,
+    "",
+    `## Verdict`,
+    "",
+    r.summary.verdict,
+    "",
+    `## Ranked blockers`,
+    "",
+    ...(blockers.length ? blockers.map((f) => `- [${f.severity.toUpperCase()}] ${f.title} (${f.hitBy.length} of ${f.visitors} agents)`) : ["_No functional blockers from the depth run._"]),
+    "",
+    ...(r.mode === "experiment" ? renderExperiment(r) : renderSingle(r)),
+    `## Strongest objections`,
+    "",
+    ...renderObjections(r),
+    `## Recommended fixes`,
+    "",
+    ...(r.summary.fixes.length ? r.summary.fixes.map((f, n) => `${n + 1}. ${f.fix} _(addresses: ${label(f.addresses)})_`) : ["_None suggested._"]),
+    "",
+    `## What would change our mind`,
+    "",
+    `These predictions are stored. Record what really happens (\`npm run debutly:predictions -- record <id> <actual>\`) to measure how well the simulation predicts.`,
+    "",
+    ...r.predictions.map((p) => `- [${p.metric}] ${p.claim}`),
+    "",
+    ...(r.market
+      ? [`## Market context`, "", ...r.market.competitors.map((c) => `- **${c.name}**: ${c.pricing} (${c.positioning})`), `Sources: ${r.market.sources.join(", ") || "none"}`, ""]
+      : []),
+    `_Evaluator cost: ${cost} (${r.usage.inputTokens.toLocaleString("en-US")} input + ${r.usage.outputTokens.toLocaleString("en-US")} output tokens)._`,
+    "",
+  ].join("\n");
+}

package/src/report/markdown.ts

@@ -0,0 +1,202 @@
+import { describeAction } from "../agent/describe";
+import { MEASURED } from "../detect/findings";
+import { describeCriterion } from "../detect/wcag";
+import { OUT_OF_CREDITS } from "../llm/types";
+import { languageName } from "../persona/language";
+import type { CustomerUnit, Finding, Session } from "../types";
+import { renderFixFirst, shotPath } from "./fix-first";
+
+export interface ReportInput {
+  targetUrl: string;
+  goal: string;
+  sessions: Session[];
+  findings: Finding[];
+  units?: CustomerUnit[];
+  usage?: { inputTokens: number; outputTokens: number; costUsd?: number };
+  model?: string;
+}
+
+function renderCost(usage: ReportInput["usage"], model?: string): string[] {
+  if (!usage || usage.inputTokens + usage.outputTokens === 0) return [];
+  const tokens = `${usage.inputTokens.toLocaleString("en-US")} input + ${usage.outputTokens.toLocaleString("en-US")} output tokens${model ? ` on ${model}` : ""}`;
+  return [`Cost: ${usage.costUsd !== undefined ? `$${usage.costUsd.toFixed(4)}` : "unknown"} (${tokens})  `];
+}
+
+function renderFinding(f: Finding, sessions: Session[]): string {
+  const lines = [
+    `### [${f.severity.toUpperCase()}] ${f.title}`,
+    "",
+    f.detail,
+    "",
+    MEASURED.has(f.kind)
+      ? `Measured by the browser on ${f.pagePath}, by ${f.hitBy.length} of ${f.visitors} agents who visited it.`
+      : `Hit by ${f.hitBy.length} of ${f.visitors} agents who visited ${f.pagePath} (${f.confidence} confidence).`,
+  ];
+  if (f.wcag?.length) lines.push("", `Related WCAG 2.2: ${f.wcag.map(describeCriterion).join(", ")}, for a person to check.`);
+  const ev = f.evidence[0];
+  const session = sessions.find((s) => s.agentId === ev?.agentId);
+  if (ev && session) {
+    lines.push("", `Reproduction (${session.personaName}):`, "");
+    for (const step of session.steps.slice(0, ev.stepIndex + 1)) {
+      lines.push(`${step.index + 1}. ${describeAction(step.action, step.observation)} — "${step.reasoning}"`);
+    }
+    const shot = session.steps[ev.stepIndex]?.screenshotPath;
+    if (shot) lines.push("", `Screenshot: ${shotPath(shot)}`);
+  }
+  return lines.join("\n");
+}
+
+const STOP_VERB: Partial<Record<Session["outcome"], string>> = {
+  gave_up: "gave up",
+  error: "stopped with an error",
+  budget_exhausted: "ran out of steps",
+  not_invited: "never got an invite",
+  cancelled: "was cancelled",
+};
+
+const OWNER_VERB: Record<Session["outcome"], string> = {
+  success: "succeeded",
+  gave_up: "gave up",
+  error: "hit an engine error",
+  budget_exhausted: "ran out of steps",
+  not_invited: "never got an invite",
+  cancelled: "was cancelled",
+};
+
+// One line per business crew: did the owner get through, and did the team get in?
+function renderUnits(units: CustomerUnit[], sessions: Session[]): string[] {
+  const crews = units.filter((u) => u.kind === "business");
+  if (!crews.length) return [];
+  const lines = crews.map((u) => {
+    const mine = sessions.filter((s) => s.unitId === u.id);
+    const owner = mine.find((s) => s.agentId === u.owner.id);
+    const team = mine.filter((s) => s.agentId !== u.owner.id);
+    const inTeam = team.filter((s) => s.outcome === "success").length;
+    const missing = team.filter((s) => s.outcome !== "success").map((s) => `${s.personaName}: ${s.outcomeNote}`);
+    const b = u.business;
+    const head = `**${b.name}** (${b.archetype}, ~${b.size} people, $${b.monthlyBudget}/mo): owner ${u.owner.name} ${owner ? OWNER_VERB[owner.outcome] : "did not run"}`;
+    if (!team.length) return `- ${head}`;
+    return `- ${head}; ${inTeam} of ${team.length} teammates got in${missing.length ? ` (${missing.join("; ")})` : ""}`;
+  });
+  return [`## Customer units`, "", ...lines, ""];
+}
+
+// Access need and first language, e.g. "screen reader, Arabic".
+const needLabel = (s: Session) =>
+  [s.inclusion?.replace(/_/g, " "), s.language && s.language !== "en" ? languageName(s.language) : ""].filter(Boolean).join(", ") || "—";
+
+// The agents' own reasons are often the clearest statement of a blocker.
+function renderStops(sessions: Session[]): string {
+  const lines = sessions.flatMap((s) => {
+    const verb = STOP_VERB[s.outcome];
+    if (!verb) return [];
+    const last = s.steps.at(-1)?.observation.url;
+    let where = "";
+    try {
+      where = last ? ` on ${new URL(last).pathname}` : "";
+    } catch {
+      where = "";
+    }
+    return [`- **${s.personaName}** ${verb}${where}: "${s.outcomeNote}"`];
+  });
+  return lines.length ? lines.join("\n") : "_Every agent reached its goal._";
+}
+
+const MISSING_KEY_PREFIX = "missing key: ";
+const MADE_UP_SITE_PREFIX = "made-up site: ";
+
+/** Why the test environment, not the app, explains a failure: blocked hosts, a missing key, a made-up site. */
+function sandboxCauseLine(f: Finding): string {
+  const causes = f.sandboxCause ?? [];
+  const hosts = causes.filter((c) => !c.startsWith(MISSING_KEY_PREFIX) && !c.startsWith(MADE_UP_SITE_PREFIX));
+  const said = causes.filter((c) => c.startsWith(MISSING_KEY_PREFIX)).map((c) => `"${c.slice(MISSING_KEY_PREFIX.length)}"`);
+  const sites = causes.filter((c) => c.startsWith(MADE_UP_SITE_PREFIX)).map((c) => c.slice(MADE_UP_SITE_PREFIX.length));
+  return [
+    hosts.length ? `Blocked at the same moment: ${hosts.join(", ")}.` : "",
+    said.length ? `The app said a key or setting is missing: ${said.join("; ")}.` : "",
+    sites.length ? `The app couldn't reach the website the agent made up for its company: ${sites.join(", ")}.` : "",
+    `Hit by ${f.hitBy.length} of ${f.visitors} agents who visited ${f.pagePath}.`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+// Agents the AI provider stopped for lack of credit: the run is incomplete, and not because of the app.
+function renderOutOfCredits(sessions: Session[]): string[] {
+  const stopped = sessions.filter((s) => s.outcome === "error" && s.outcomeNote.startsWith(OUT_OF_CREDITS));
+  if (!stopped.length) return [];
+  return [
+    `## Run cut short`,
+    "",
+    `The AI provider account ran out of credits, so ${stopped.length} of ${sessions.length} agents stopped early: ${stopped.map((s) => s.personaName).join(", ")}. That is not the app's doing. Findings cover only the steps they took. Top up the account and run again.`,
+    "",
+  ];
+}
+
+// Failures the test environment explains (it blocked an outbound call, or has no key the app
+// needs): likely not the app's fault.
+function renderSandboxCaused(caused: Finding[]): string[] {
+  if (!caused.length) return [];
+  return [
+    `## Caused by the test environment`,
+    "",
+    `The test environment blocks the app from reaching real outside services and has none of its secret keys, so nothing leaks and nothing is charged. Each of these failures happened while it was blocking a call, or the app said a key was missing, or it couldn't reach a website the agent made up, so they probably don't happen on the real app. Check there if in doubt.`,
+    "",
+    ...caused.flatMap((f) => [`### ${f.title}`, "", f.detail, "", sandboxCauseLine(f), ""]),
+  ];
+}
+
+export function renderReport(input: ReportInput): string {
+  const caused = input.findings.filter((f) => f.sandboxCause);
+  const real = input.findings.filter((f) => !f.sandboxCause);
+  const confident = real.filter((f) => f.confidence !== "low");
+  const low = real.filter((f) => f.confidence === "low");
+  const count = (s: Finding["severity"]) => confident.filter((f) => f.severity === s).length;
+
+  return [
+    `# Debutly Report`,
+    "",
+    `> Simulated evidence — not real traction. Findings come from AI agents, not real users.`,
+    "",
+    `Target: ${input.targetUrl}  `,
+    `Goal: ${input.goal}  `,
+    `Agents: ${input.sessions.length}  `,
+    ...renderCost(input.usage, input.model),
+    `Findings: ${count("blocker")} blocker, ${count("major")} major, ${count("minor")} minor (${low.length} low-confidence${caused.length ? `, ${caused.length} caused by the test environment` : ""})`,
+    "",
+    ...renderOutOfCredits(input.sessions),
+    ...renderFixFirst(input.sessions, input.findings, needLabel),
+    ...renderUnits(input.units ?? [], input.sessions),
+    `## Agent outcomes`,
+    "",
+    `| Persona | Role | Needs | Outcome | Note |`,
+    `|---|---|---|---|---|`,
+    ...input.sessions.map((s) => `| ${s.personaName} | ${s.role ?? "—"} | ${needLabel(s)} | ${s.outcome} | ${s.outcomeNote} |`),
+    "",
+    `## Where agents stopped`,
+    "",
+    renderStops(input.sessions),
+    "",
+    `## Findings`,
+    "",
+    ...(input.findings.some((f) => f.wcag?.length)
+      ? [
+          `WCAG references point to what a person should check. Debutly doesn't test conformance, and a run without such findings says nothing about it.`,
+          "",
+        ]
+      : []),
+    confident.length ? confident.map((f) => renderFinding(f, input.sessions)).join("\n\n") : "_None._",
+    "",
+    `## Low-confidence findings`,
+    "",
+    `Few of the agents that reached these pages hit these issues. They may be agent errors rather than product bugs.`,
+    "",
+    low.length ? low.map((f) => renderFinding(f, input.sessions)).join("\n\n") : "_None._",
+    "",
+    ...renderSandboxCaused(caused),
+    "---",
+    "",
+    "Rehearsed with [Debutly](https://debutly.dev).",
+    "",
+  ].join("\n");
+}

package/src/run.ts

@@ -0,0 +1,141 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { chromium } from "playwright";
+import { LocalArtifactStore, type ArtifactStore } from "./artifacts/store";
+import { runAgentSession } from "./agent/run-agent";
+import { runUnit, type RunAgent } from "./crew/run-unit";
+import { detectFindings } from "./detect/findings";
+import type { Inbox } from "./inbox/types";
+import type { LlmClient } from "./llm/types";
+import { PEOPLE_FILE } from "./persona/people";
+import { renderReport } from "./report/markdown";
+import type { ModelPrice } from "./llm/meter";
+import { blockedCalls, type SandboxOutbox } from "./sandbox/outbox";
+import type { NewRun, RunStore, RunUsage, SideEffect } from "./store/run-store";
+import type { CustomerUnit, Finding, Persona, Session } from "./types";
+import { mapWithConcurrency } from "./util/pool";
+
+export interface SimulationOptions {
+  url: string;
+  goal: string;
+  /** Individuals and/or business crews; crews run owner first, then invited employees. */
+  units: CustomerUnit[];
+  llm: LlmClient;
+  maxSteps: number;
+  /** How many units run at once. */
+  concurrency: number;
+  outDir: string;
+  /** Gives each agent its own email address and lets it read mail (magic links, invites). */
+  inbox?: Inbox;
+  emailDomain?: string;
+  /** The app's sandbox outbox, to tell failures the test environment caused from real ones. */
+  sandboxOutbox?: SandboxOutbox;
+  /** Where screenshots go; defaults to <outDir>/screenshots. */
+  artifacts?: ArtifactStore;
+  /** Records the run as it happens (and provides its kill switch). */
+  store?: RunStore;
+  /** An existing run to record into (e.g. one queued by an API); otherwise one is created. */
+  runId?: string;
+  /** What to record about the run when creating it. */
+  run?: Omit<NewRun, "targetUrl" | "goal">;
+  /** Per-agent limits. */
+  caps?: { maxTokens?: number; maxMs?: number };
+  /** The nav model's price, to cost each session. */
+  price?: ModelPrice | null;
+  /** In-memory kill switch when there is no store (e.g. Ctrl+C). */
+  shouldStop?: () => boolean | Promise<boolean>;
+  /** Where to keep each agent's browser state (cookies, storage) at the end, for `debutly hear`. */
+  browserStateDir?: string;
+  /** Sends each agent somewhere else to run (e.g. a queue of workers) instead of this process. */
+  dispatch?: (ctx: { runId?: string; runTag: string }) => RunAgent;
+}
+
+export const asIndividuals = (personas: Persona[]): CustomerUnit[] => personas.map((p) => ({ kind: "individual", id: p.id, person: p }));
+
+export function agentEmail(persona: Pick<Persona, "id" | "name">, runTag: string, domain: string): string {
+  const slug = persona.name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return `${slug || "agent"}.${persona.id}.${runTag}@${domain}`;
+}
+
+export interface SimulationResult {
+  runId?: string;
+  sessions: Session[];
+  findings: Finding[];
+  reportPath: string;
+  usage: RunUsage;
+}
+
+/** Sums sessions' usage; the cost is known only if every session's is. */
+export function runUsage(sessions: Session[]): RunUsage {
+  const costs = sessions.filter((s) => s.usage).map((s) => s.usage!.costUsd);
+  return {
+    inputTokens: sessions.reduce((n, s) => n + (s.usage?.inputTokens ?? 0), 0),
+    outputTokens: sessions.reduce((n, s) => n + (s.usage?.outputTokens ?? 0), 0),
+    costUsd: costs.length && costs.every((c) => c !== undefined) ? costs.reduce((a, c) => a + (c ?? 0), 0) : undefined,
+  };
+}
+
+export async function runSimulation(o: SimulationOptions): Promise<SimulationResult> {
+  await mkdir(o.outDir, { recursive: true });
+  const artifacts = o.artifacts ?? new LocalArtifactStore(join(o.outDir, "screenshots"));
+  const origin = new URL(o.url).origin;
+  const started = new Date();
+  const runTag = started.getTime().toString(36);
+  const emailOf = (p: Persona) => agentEmail(p, runTag, o.emailDomain ?? "agents.test");
+  const { store } = o;
+  const runId = store ? (o.runId ?? (await store.createRun({ targetUrl: o.url, goal: o.goal, ...o.run }))) : o.runId;
+  if (store && runId) await store.recordUnits(runId, o.units);
+  // The run kill switch: the store's (so another process can cancel) or the caller's.
+  const shouldStop = store && runId ? () => store.isCancelled(runId) : o.shouldStop;
+  // Queue mode: workers run the agents (and record them); otherwise they run here.
+  const browser = o.dispatch ? undefined : await chromium.launch();
+  try {
+    const runAgent: RunAgent = o.dispatch
+      ? o.dispatch({ runId, runTag })
+      : (persona, goal, brief) =>
+          runAgentSession(
+            { browser: browser!, llm: o.llm, origin, maxSteps: o.maxSteps, artifacts, emailOf, inbox: o.inbox, caps: o.caps, price: o.price, shouldStop, store, runId, browserStateDir: o.browserStateDir },
+            persona,
+            goal,
+            brief,
+          );
+    const perUnit = await mapWithConcurrency(o.units, o.concurrency, (unit) => runUnit(unit, o.goal, { runAgent, emailOf, inbox: o.inbox }));
+    const sessions = perUnit.flat();
+    // Teammates who were never invited never ran; record them too.
+    if (store && runId) for (const s of sessions.filter((x) => x.outcome === "not_invited")) await store.finishSession(runId, s);
+
+    let sideEffects: SideEffect[] = [];
+    if (o.sandboxOutbox) {
+      try {
+        sideEffects = await o.sandboxOutbox.entriesSince(started);
+      } catch (err) {
+        console.warn(`Could not read the sandbox outbox, so failures are not checked against it: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+    const findings = detectFindings(sessions, { blocked: blockedCalls(sideEffects), sandbox: !!o.sandboxOutbox });
+    const usage = runUsage(sessions);
+    const reportMd = renderReport({ targetUrl: o.url, goal: o.goal, sessions, findings, units: o.units, usage, model: o.run?.model });
+    const reportPath = join(o.outDir, "report.md");
+    await writeFile(join(o.outDir, "sessions.json"), JSON.stringify(sessions, null, 2));
+    await writeFile(join(o.outDir, "findings.json"), JSON.stringify(findings, null, 2));
+    await writeFile(join(o.outDir, PEOPLE_FILE), JSON.stringify(o.units, null, 2));
+    await writeFile(reportPath, reportMd);
+    if (store && runId) {
+      const status = sessions.some((s) => s.outcome === "cancelled") ? "cancelled" : "finished";
+      await store.finishRun(runId, { status, findings, reportMd, usage, sideEffects });
+    }
+    return { runId, sessions, findings, reportPath, usage };
+  } catch (err) {
+    if (store && runId) {
+      await store
+        .finishRun(runId, { status: "failed", findings: [], reportMd: `Run failed: ${err instanceof Error ? err.message : err}`, usage: { inputTokens: 0, outputTokens: 0 }, sideEffects: [] })
+        .catch(() => {});
+    }
+    throw err;
+  } finally {
+    await browser?.close();
+  }
+}

package/src/sandbox/outbox.ts

@@ -0,0 +1,65 @@
+import type { SideEffect } from "../store/run-store";
+
+/** An outbound call the app under test tried to make and its sandbox refused. */
+export interface BlockedCall {
+  host: string;
+  url: string;
+  /** When the sandbox blocked it (epoch ms). */
+  at: number;
+}
+
+export interface SandboxOutbox {
+  /** Everything the sandbox faked or blocked since `since`: the run's side effects. */
+  entriesSince(since: Date): Promise<SideEffect[]>;
+}
+
+// Calls a failure can come from: ones the sandbox refused, and AI calls it answered with a stand-in
+// (an app's AI proxy failed on the stand-in answers, 2026-10-16 to 18). A faked email is not
+// one: the app is told it was sent.
+export const blockedCalls = (entries: SideEffect[]): BlockedCall[] =>
+  entries
+    .filter((e) => e.outcome === "blocked" || (e.outcome === "faked" && e.channel === "ai"))
+    .map((e) => ({ host: e.host, url: e.url, at: e.at.getTime() }));
+
+interface OutboxEntry {
+  outcome?: string;
+  rule?: string | null;
+  channel?: string;
+  host?: string;
+  url?: string;
+  recipient?: string | null;
+  summary?: string | null;
+  created_at?: string;
+}
+
+/**
+ * Reads a throwaway environment's sandbox outbox (GET <url>?since=…, bearer token),
+ * the record every Debutly sandbox keeps of what it faked or blocked.
+ */
+export class HttpSandboxOutbox implements SandboxOutbox {
+  constructor(
+    private readonly url: string,
+    private readonly token: string,
+    private readonly fetchFn: typeof fetch = fetch,
+  ) {}
+
+  async entriesSince(since: Date): Promise<SideEffect[]> {
+    const res = await this.fetchFn(`${this.url}?since=${encodeURIComponent(since.toISOString())}`, {
+      headers: { authorization: `Bearer ${this.token}` },
+    });
+    if (!res.ok) throw new Error(`sandbox outbox: HTTP ${res.status}`);
+    const { entries = [] } = (await res.json()) as { entries?: OutboxEntry[] };
+    return entries
+      .filter((e) => e.outcome && e.host && e.created_at)
+      .map((e) => ({
+        outcome: e.outcome!,
+        rule: e.rule ?? null,
+        channel: e.channel ?? "unknown",
+        host: e.host!,
+        url: e.url ?? "",
+        recipient: e.recipient ?? null,
+        summary: e.summary ?? null,
+        at: new Date(e.created_at!),
+      }));
+  }
+}

package/src/store/db.ts

@@ -0,0 +1,40 @@
+import { PGlite } from "@electric-sql/pglite";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import { drizzle as drizzlePglite } from "drizzle-orm/pglite";
+import { migrate as migratePglite } from "drizzle-orm/pglite/migrator";
+import { drizzle as drizzlePostgres } from "drizzle-orm/postgres-js";
+import { migrate as migratePostgres } from "drizzle-orm/postgres-js/migrator";
+import postgres from "postgres";
+import { mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as schema from "./schema";
+import { postgresUrl } from "./url";
+
+export type Db = PgDatabase<PgQueryResultHKT, typeof schema>;
+
+const MIGRATIONS = fileURLToPath(new URL("../../drizzle", import.meta.url));
+
+export interface OpenDb {
+  db: Db;
+  close: () => Promise<void>;
+}
+
+/**
+ * A Postgres connection with the schema migrated. `memory:` gives an in-process
+ * PGlite database (tests, one-off local runs), `pglite:<folder>` one kept in a folder (local
+ * dashboard work without a server); anything else is a postgres:// URL.
+ */
+export async function openDb(url: string): Promise<OpenDb> {
+  if (url === "memory:" || url.startsWith("pglite:")) {
+    const folder = url === "memory:" ? undefined : url.slice("pglite:".length);
+    if (folder) mkdirSync(folder, { recursive: true });
+    const client = folder ? new PGlite(folder) : new PGlite();
+    const db = drizzlePglite(client, { schema });
+    await migratePglite(db, { migrationsFolder: MIGRATIONS });
+    return { db: db as unknown as Db, close: () => client.close() };
+  }
+  const client = postgres(postgresUrl(url), { max: 10, onnotice: () => {} });
+  const db = drizzlePostgres(client, { schema });
+  await migratePostgres(db, { migrationsFolder: MIGRATIONS });
+  return { db: db as unknown as Db, close: () => client.end() };
+}

package/src/store/import-run.ts

@@ -0,0 +1,116 @@
+// Load a finished run's folder (report.md, sessions.json, findings.json, screenshots/) into the
+// store, so runs made without --store (every nightly CI run before the dashboard) can be seen in
+// it. Screenshots go into the database as compact JPEGs, like a stored run's.
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { eq } from "drizzle-orm";
+import { DbArtifactStore } from "../artifacts/db";
+import type { Business, CustomerUnit, Finding, InclusionNeed, Persona, Session } from "../types";
+import type { Db } from "./db";
+import { PgRunStore } from "./pg-run-store";
+import { runs } from "./schema";
+
+export interface ImportOptions {
+  app?: string;
+  trigger?: string;
+  ciUrl?: string;
+  /** When the run happened (its CI run's start); the folder's report has no date. */
+  at?: Date;
+  /** PNG to JPEG, e.g. through a browser; without one, screenshots are left out. */
+  toJpeg?: (png: Buffer) => Promise<Buffer>;
+}
+
+export interface ReportHeader {
+  targetUrl: string;
+  goal: string;
+  costUsd?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  businesses: Business[];
+}
+
+/** What report.md says about the run that sessions.json doesn't: target, goal, cost, businesses. */
+export function parseReportHeader(md: string): ReportHeader {
+  const line = (label: string) => md.match(new RegExp(`^${label}: (.*?)\\s*$`, "m"))?.[1];
+  const cost = md.match(/^Cost: \$([\d.]+) \(([\d,]+) input \+ ([\d,]+) output tokens\)/m);
+  const units = md.match(/## Customer units\n\n([\s\S]*?)\n\n## /)?.[1] ?? "";
+  const businesses = [...units.matchAll(/^- \*\*(.+?)\*\* \((.+?), ~(\d+) people, \$(\d+)\/mo\)/gm)].map(
+    ([, name, archetype, size, budget]) => ({ name, archetype, size: Number(size), monthlyBudget: Number(budget), goal: "" }),
+  );
+  const num = (s?: string) => (s ? Number(s.replace(/,/g, "")) : undefined);
+  return {
+    targetUrl: line("Target") ?? "",
+    goal: line("Goal") ?? "",
+    costUsd: cost ? Number(cost[1]) : undefined,
+    inputTokens: num(cost?.[2]),
+    outputTokens: num(cost?.[3]),
+    businesses,
+  };
+}
+
+/** The customer units the sessions belong to: a business per unit id (u1, u2…), else one person each. */
+export function unitsFromSessions(sessions: Session[], businesses: Business[]): CustomerUnit[] {
+  const persona = (s: Session): Persona => ({
+    id: s.agentId,
+    name: s.personaName,
+    background: "",
+    goal: s.goal,
+    patience: "medium",
+    techSavvy: "medium",
+    ...(s.role ? { role: s.role } : {}),
+    ...(s.inclusion ? { inclusion: s.inclusion as InclusionNeed } : {}),
+  });
+  const byUnit = new Map<string, Session[]>();
+  for (const s of sessions) {
+    const unit = s.unitId ?? s.agentId;
+    byUnit.set(unit, [...(byUnit.get(unit) ?? []), s]);
+  }
+  return [...byUnit.entries()].map(([id, members], i): CustomerUnit => {
+    const owner = members.find((m) => m.agentId.endsWith("-o"));
+    if (!owner) return { kind: "individual", id, person: persona(members[0]) };
+    return {
+      kind: "business",
+      id,
+      business: businesses[i] ?? { name: id, archetype: "", size: members.length, monthlyBudget: 0, goal: "" },
+      owner: persona(owner),
+      employees: members.filter((m) => m !== owner).map(persona),
+    };
+  });
+}
+
+/** Import one run folder; returns the new run's id. */
+export async function importRunFolder(db: Db, dir: string, o: ImportOptions = {}): Promise<string> {
+  const read = (name: string) => readFile(join(dir, name), "utf8");
+  const header = parseReportHeader(await read("report.md"));
+  const sessions = JSON.parse(await read("sessions.json")) as Session[];
+  const findings = JSON.parse(await read("findings.json")) as Finding[];
+  const reportMd = await read("report.md");
+
+  const store = new PgRunStore(db);
+  const runId = await store.createRun({ app: o.app, trigger: o.trigger, ciUrl: o.ciUrl, targetUrl: header.targetUrl, goal: header.goal });
+  await store.recordUnits(runId, unitsFromSessions(sessions, header.businesses));
+
+  const shots = new DbArtifactStore(db, runId);
+  for (const s of sessions) {
+    await store.startSession(runId, s.agentId, s.goal);
+    for (const step of s.steps) {
+      let screenshotPath: string | undefined;
+      const file = step.screenshotPath ? join(dir, "screenshots", basename(step.screenshotPath)) : undefined;
+      if (file && o.toJpeg && existsSync(file)) {
+        screenshotPath = await shots.put(basename(file).replace(/\.png$/i, ".jpg"), await o.toJpeg(await readFile(file)), "image/jpeg");
+      }
+      await store.appendStep(runId, s.agentId, { ...step, screenshotPath });
+    }
+    await store.finishSession(runId, s);
+  }
+
+  const usage = {
+    inputTokens: header.inputTokens ?? sessions.reduce((n, s) => n + (s.usage?.inputTokens ?? 0), 0),
+    outputTokens: header.outputTokens ?? sessions.reduce((n, s) => n + (s.usage?.outputTokens ?? 0), 0),
+    costUsd: header.costUsd,
+  };
+  await store.finishRun(runId, { status: "finished", findings, reportMd, usage, sideEffects: [] });
+  if (o.at) await db.update(runs).set({ createdAt: o.at, startedAt: o.at, finishedAt: o.at }).where(eq(runs.id, runId));
+  return runId;
+}