debutly 0.0.0-stage → 0.1.0

package/src/cli.ts

@@ -0,0 +1,265 @@
+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 { 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 { 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" },
+  },
+});
+
+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]',
+  );
+  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"]);
+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 = 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);
+console.log(`Generating ${count} ${unitKind === "business" ? `business crew(s) with ${employees} employees each` : "individual(s)"}...`);
+let 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;
+}

package/src/cost/tiers.ts

@@ -0,0 +1,27 @@
+// Run sizes. Units are individuals or business crews; breadth evaluators judge pages on top.
+export const TIERS = {
+  quick: { units: 3, employees: 0 }, // CI / pre-deploy smoke: owners only
+  standard: { units: 10, employees: 2 },
+  deep: { units: 30, employees: 3 },
+} as const;
+export type Tier = keyof typeof TIERS;
+
+export interface RunSize {
+  tier: Tier;
+  units: number;
+  employees: number;
+}
+
+/** A tier's size, with explicitly given counts taking precedence. */
+export function resolveRunSize(o: { tier?: string; units?: number; employees?: number }): RunSize {
+  const tier = (o.tier ?? "quick") as Tier;
+  if (!(tier in TIERS)) throw new Error(`--tier must be quick, standard or deep (got "${o.tier}")`);
+  return { tier, units: o.units ?? TIERS[tier].units, employees: o.employees ?? TIERS[tier].employees };
+}
+
+/** Agents a run will use: individuals count once; a crew is its owner plus employees. */
+export const agentCount = (kind: "individual" | "business", size: RunSize) =>
+  kind === "individual" ? size.units : size.units * (1 + size.employees);
+
+/** Breadth evaluators per tier: Quick ~50, Standard 200–500, Deep 1,000–5,000. */
+export const EVALUATORS: Record<Tier, number> = { quick: 50, standard: 300, deep: 1500 };

package/src/costs.ts

@@ -0,0 +1,96 @@
+// Cost meter: what Debutly is spending, in one place.
+//
+//   npm run debutly:costs -- [--repo owner/name ...]
+//
+// Shows the OpenRouter key's spend (today, this week, this month, limit left) and, for each app
+// repo given, what its latest nightly agent run cost (read from the GitHub run log via `gh`).
+import "./util/legacy-env";
+import "./util/key-defaults";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parseArgs } from "node:util";
+import { isOpenRouter } from "./llm/openrouter";
+
+const run = promisify(execFile);
+
+export interface KeySpend {
+  today: number;
+  week: number;
+  month: number;
+  total: number;
+  limit: number | null;
+  remaining: number | null;
+  resets: string | null;
+}
+
+export async function fetchKeySpend(baseUrl: string, apiKey: string, fetchFn: typeof fetch = fetch): Promise<KeySpend> {
+  const res = await fetchFn(`${baseUrl.replace(/\/+$/, "")}/key`, { headers: { authorization: `Bearer ${apiKey}` } });
+  if (!res.ok) throw new Error(`OpenRouter key info: HTTP ${res.status}`);
+  const { data: d } = (await res.json()) as { data: Record<string, unknown> };
+  const n = (k: string) => (typeof d[k] === "number" ? (d[k] as number) : 0);
+  return {
+    today: n("usage_daily"),
+    week: n("usage_weekly"),
+    month: n("usage_monthly"),
+    total: n("usage"),
+    limit: typeof d.limit === "number" ? d.limit : null,
+    remaining: typeof d.limit_remaining === "number" ? d.limit_remaining : null,
+    resets: typeof d.limit_reset === "string" ? d.limit_reset : null,
+  };
+}
+
+/** The cost a Debutly run printed at the end ("Done: … cost $0.1234 …"), from a CI log. */
+export function costFromLog(log: string): number | null {
+  const matches = [...log.matchAll(/Done: [^\n]*?cost \$(\d+(?:\.\d+)?)/g)];
+  return matches.length ? Number(matches[matches.length - 1][1]) : null;
+}
+
+export interface NightlyCost {
+  repo: string;
+  when: string;
+  costUsd: number | null;
+  url: string;
+}
+
+async function latestNightly(repo: string): Promise<NightlyCost | null> {
+  const { stdout } = await run("gh", ["run", "list", "--repo", repo, "--workflow", "throwaway-env.yml", "--status", "success", "--limit", "5", "--json", "databaseId,createdAt,url,event"]);
+  const runs = JSON.parse(stdout) as { databaseId: number; createdAt: string; url: string; event: string }[];
+  for (const r of runs) {
+    const { stdout: log } = await run("gh", ["run", "view", String(r.databaseId), "--repo", repo, "--log"], { maxBuffer: 64 * 1024 * 1024 });
+    const costUsd = costFromLog(log);
+    if (costUsd !== null) return { repo, when: r.createdAt, costUsd, url: r.url };
+  }
+  return null;
+}
+
+const usd = (x: number) => `$${x.toFixed(2)}`;
+
+if (process.argv[1]?.endsWith("costs.ts")) {
+  const { values } = parseArgs({ options: { repo: { type: "string", multiple: true } } });
+  const { DEBUTLY_BASE_URL, DEBUTLY_API_KEY } = process.env;
+  if (DEBUTLY_BASE_URL && isOpenRouter(DEBUTLY_BASE_URL) && DEBUTLY_API_KEY) {
+    const s = await fetchKeySpend(DEBUTLY_BASE_URL, DEBUTLY_API_KEY);
+    console.log("OpenRouter key");
+    console.log(`  Today ${usd(s.today)} · this week ${usd(s.week)} · this month ${usd(s.month)} · all time ${usd(s.total)}`);
+    if (s.limit !== null) console.log(`  Limit ${usd(s.limit)}${s.resets ? ` (resets ${s.resets})` : ""} · left ${usd(s.remaining ?? 0)}`);
+  } else {
+    console.log("OpenRouter key: not configured (DEBUTLY_BASE_URL / DEBUTLY_API_KEY)");
+  }
+
+  const nightly: NightlyCost[] = [];
+  for (const repo of values.repo ?? []) {
+    try {
+      const n = await latestNightly(repo);
+      if (n) nightly.push(n);
+      else console.log(`  ${repo}: no costed agent run found yet`);
+    } catch (err) {
+      console.log(`  ${repo}: could not read runs (${err instanceof Error ? err.message.split("\n")[0] : err})`);
+    }
+  }
+  if (nightly.length) {
+    console.log("\nLatest agent run per app");
+    for (const n of nightly) console.log(`  ${n.repo.padEnd(40)} ${usd(n.costUsd ?? 0)}  (${n.when.slice(0, 10)})`);
+    const perNight = nightly.reduce((a, n) => a + (n.costUsd ?? 0), 0);
+    console.log(`  ${"Per night, all apps".padEnd(40)} ${usd(perNight)}  → about ${usd(perNight * 30)} a month`);
+  }
+}

package/src/crew/run-unit.ts

@@ -0,0 +1,62 @@
+import type { Inbox } from "../inbox/types";
+import type { Business, CustomerUnit, Persona, Session } from "../types";
+
+/** Runs one agent in its own browser context; `brief` joins its system prompt. */
+export type RunAgent = (persona: Persona, goal: string, brief: string | undefined) => Promise<Session>;
+
+export interface UnitDeps {
+  runAgent: RunAgent;
+  emailOf: (persona: Persona) => string;
+  inbox?: Inbox;
+}
+
+const article = (word: string) => (/^[aeiou]/i.test(word) ? "an" : "a");
+
+const companyBrief = (b: Business) =>
+  `You work at ${b.name}, ${article(b.archetype)} ${b.archetype} of about ${b.size} people. Its budget for tools like this is $${b.monthlyBudget} a month. Company goal: ${b.goal}.`;
+
+export function ownerGoal(goal: string, team: { name: string; role?: string; email: string }[]): string {
+  if (!team.length) return goal;
+  const who = team.map((t) => `${t.name} (${t.role ?? "Teammate"}) at ${t.email}`).join("; ");
+  return `${goal}\nOnce you are set up, invite your teammates by email so they can use it too: ${who}.`;
+}
+
+// A teammate who lands in an empty workspace of their own has not joined anything, even if the
+// invite page said "accepted"; that must not count as success.
+export const employeeGoal = (role: string, owner: string, company: string) =>
+  `${owner} has invited you to use this product at ${company}. Check your email for the invite, accept it and set up your account. Then check that you are in ${company}'s shared workspace: you should see what ${owner} set up there, such as the company details or the items they added. If you only see an empty workspace of your own, joining did not work: report that as a failure, not success. If you are in, do one task a ${role} would typically do here. Finish when you have done that or when you would give up.`;
+
+const tag = (s: Session, unitId: string, p: Persona): Session => ({ ...s, unitId, role: p.role, inclusion: p.inclusion, language: p.language });
+const notInvited = (unitId: string, p: Persona, why: string): Session =>
+  tag({ agentId: p.id, personaName: p.name, goal: "", steps: [], outcome: "not_invited", outcomeNote: why }, unitId, p);
+
+/**
+ * One customer unit. An individual runs once. A business crew runs its owner first (who is told
+ * whom to invite), then, in parallel and each in its own browser, only the employees whose invite
+ * actually reached their inbox, sharing the company brief and what the owner reported.
+ */
+export async function runUnit(unit: CustomerUnit, goal: string, deps: UnitDeps): Promise<Session[]> {
+  if (unit.kind === "individual") return [tag(await deps.runAgent(unit.person, goal, undefined), unit.id, unit.person)];
+
+  const { business, owner, employees } = unit;
+  const brief = companyBrief(business);
+  const team = employees.map((e) => ({ name: e.name, role: e.role, email: deps.emailOf(e) }));
+  const ownerSession = tag(
+    await deps.runAgent(owner, ownerGoal(goal, team), `${brief}\nYou run ${business.name} and decide which plan and how many seats to buy.`),
+    unit.id,
+    owner,
+  );
+  if (!employees.length) return [ownerSession];
+  const { inbox } = deps;
+  if (!inbox) return [ownerSession, ...employees.map((e) => notInvited(unit.id, e, "No test inbox, so teammates cannot receive invites."))];
+
+  const shared = `${brief}\n${owner.name} (the owner) reported: "${ownerSession.outcomeNote}"`;
+  const rest = await Promise.all(
+    employees.map(async (e) => {
+      const mail = await inbox.latest(deps.emailOf(e)).catch(() => []);
+      if (!mail.length) return notInvited(unit.id, e, `No invite email arrived after ${owner.name} finished.`);
+      return tag(await deps.runAgent(e, employeeGoal(e.role ?? "teammate", owner.name, business.name), shared), unit.id, e);
+    }),
+  );
+  return [ownerSession, ...rest];
+}