@oalo-ai/cli 0.0.0-stage → 0.1.0

package/src/commands/metrics.js

@@ -0,0 +1,168 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo metrics`: a number from the workspace's data, the same query the
+ * dashboards draw (AppBuilder.Metrics).
+ *
+ *   oalo metrics orders                                   how many rows
+ *   oalo metrics orders --sum total --by status --days 30
+ *   oalo metrics orders --every week --days 90 --where "status = paid"
+ *   oalo metrics events --event order.created --every day --days 14
+ *   oalo metrics contacts --by source
+ *
+ * `oalo dashboards`: the workspace's dashboards, and a chart put on one.
+ *
+ *   oalo dashboards
+ *   oalo dashboards add Sales orders --title "Revenue by plan" --kind bars --sum total --by plan --days 30
+ *   oalo dashboards add Sales events --title Funnel --kind funnel --steps lead.captured,order.created --days 30
+ */
+
+const MEASURES = ["sum", "avg", "min", "max", "distinct"];
+const KINDS = ["number", "line", "bars", "table", "funnel"];
+
+/** "status = paid and total > 100" → filters. Throws on what it can't read. */
+export function parseWhere(text) {
+  if (text == null || text === true) return [];
+  return String(text)
+    .split(/\s+and\s+/i)
+    .map((part) => {
+      const p = part.trim();
+      let m;
+      if ((m = p.match(/^([\w.]+)\s+(present|absent)$/i))) return { field: m[1], op: m[2].toLowerCase() === "present" ? "set" : "unset" };
+      if ((m = p.match(/^([\w.]+)\s+in\s+(.+)$/i))) return { field: m[1], op: "in", value: m[2].split(",").map((v) => v.trim()).filter(Boolean) };
+      if ((m = p.match(/^([\w.]+)\s*(!=|>=|<=|==|=|>|<|~)\s*(.+)$/))) {
+        const op = { "=": "eq", "==": "eq", "!=": "neq", ">": "gt", ">=": "gte", "<": "lt", "<=": "lte", "~": "contains" }[m[2]];
+        const raw = m[3].trim().replace(/^["']|["']$/g, "");
+        const value = ["gt", "gte", "lt", "lte"].includes(op) && raw !== "" && !Number.isNaN(Number(raw)) ? Number(raw) : raw;
+        return { field: m[1], op, value };
+      }
+      throw new Error(`can't read the filter ${JSON.stringify(p)}: write field = value, field != value, field > 10, field ~ text, field in a,b, field present or field absent, joined with "and"`);
+    });
+}
+
+/** The query from `what` (a model, events or contacts) and the flags. */
+export function queryFromFlags(what, flags) {
+  if (!what) throw new Error("what to count? a model's name, events or contacts");
+  const q = what === "events" ? { source: "event" } : what === "contacts" ? { source: "contact" } : { source: "model", table: what };
+  if (typeof flags.event === "string") {
+    if (q.source !== "event") throw new Error("--event is for events");
+    q.event = flags.event;
+  }
+  const measures = MEASURES.filter((m) => flags[m] !== undefined);
+  if (measures.length > 1) throw new Error(`one measure at a time, not --${measures.join(" and --")}`);
+  if (measures.length) {
+    if (typeof flags[measures[0]] !== "string") throw new Error(`--${measures[0]} needs a field`);
+    q.measure = measures[0];
+    q.field = flags[measures[0]];
+  }
+  if (typeof flags.by === "string") q.by = flags.by;
+  if (flags.every !== undefined) {
+    if (!["day", "week", "month"].includes(flags.every)) throw new Error("--every is day, week or month");
+    q.every = flags.every;
+  }
+  if (flags.days !== undefined) {
+    const d = Number(flags.days);
+    if (!Number.isInteger(d) || d < 1) throw new Error("--days is a whole number of days");
+    q.days = d;
+  }
+  if (typeof flags.time === "string") q.time = flags.time;
+  if (flags.compare) q.compare = true;
+  if (flags.env === "dev" || flags.env === "prod") q.env = flags.env;
+  const where = parseWhere(flags.where);
+  if (where.length) q.where = where;
+  return q;
+}
+
+export async function metrics(flags, rest, opts = {}) {
+  let query;
+  try {
+    query = queryFromFlags(rest[1], flags);
+  } catch (e) {
+    return fail(`${e.message}\n\n${METRICS_USAGE}`, 2);
+  }
+  const r = await call("metrics:query", { query }, flags, opts);
+  if (!r) return;
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  printResult(r);
+}
+
+export async function dashboards(flags, rest, opts = {}) {
+  const sub = rest[1] || "list";
+  if (sub === "list") {
+    const r = await call("dashboards:list", {}, flags, opts);
+    if (!r) return;
+    if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+    for (const d of r.dashboards || []) console.log(`${d.name}  ${dim(`${d.widget_count} widget${d.widget_count === 1 ? "" : "s"}${d.app_id ? ", on an app" : ""}`)}`);
+    return;
+  }
+  if (sub !== "add") return fail(`unknown dashboards command: ${sub}\n\n${DASHBOARDS_USAGE}`, 2);
+
+  const [name, what] = [rest[2], rest[3]];
+  if (!name) return fail(`which dashboard? its name (made when there's none)\n\n${DASHBOARDS_USAGE}`, 2);
+  if (typeof flags.title !== "string" || !flags.title.trim()) return fail('what is the chart called? --title "Orders per week"', 2);
+  if (!KINDS.includes(flags.kind)) return fail(`--kind is ${KINDS.join(", ")}`, 2);
+
+  let query;
+  try {
+    if (flags.kind === "funnel") {
+      if (typeof flags.steps !== "string") throw new Error("a funnel needs --steps a,b,c (event types, in order)");
+      query = { steps: flags.steps.split(",").map((s) => s.trim()).filter(Boolean), ...(flags.days ? { days: Number(flags.days) } : {}) };
+    } else query = queryFromFlags(what, flags);
+  } catch (e) {
+    return fail(`${e.message}\n\n${DASHBOARDS_USAGE}`, 2);
+  }
+
+  const widget = { title: flags.title.trim(), kind: flags.kind, query, ...(flags.width ? { width: Number(flags.width) } : {}) };
+  const r = await call("dashboards:put_widget", { dashboard: name, ...(typeof flags.app === "string" ? { app: flags.app } : {}), widget }, flags, opts);
+  if (!r) return;
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  console.log(`${r.replaced ? "Replaced" : "Added"} "${r.widget.title}" on ${r.dashboard.name}${r.made ? " (a new dashboard)" : ""}.`);
+  printResult(r.result);
+}
+
+const METRICS_USAGE = [
+  "usage: oalo metrics <model | events | contacts> [--sum|--avg|--min|--max|--distinct <field>] [--by <field>]",
+  "         [--every day|week|month] [--days N] [--where 'status = paid and total > 10'] [--event <type>] [--time created|changed|<date field>] [--compare] [--env dev] [--json]",
+].join("\n");
+
+const DASHBOARDS_USAGE = [
+  "usage: oalo dashboards",
+  '       oalo dashboards add <dashboard> <model | events | contacts> --title "<title>" --kind number|line|bars|table [metrics flags] [--app <slug>] [--width 1|2|3]',
+  '       oalo dashboards add <dashboard> --title "<title>" --kind funnel --steps a,b,c [--days N]',
+].join("\n");
+
+function printResult(r) {
+  if (r.steps) {
+    for (const s of r.steps) console.log(`${s.step}  ${s.contacts}${s.rate != null ? dim(`  ${Math.round(s.rate * 100)}%`) : ""}`);
+    return;
+  }
+  const fmt = (v) => (Number.isInteger(v) ? String(v) : v.toFixed(2));
+  const single = r.rows.length === 1 && r.rows[0].bucket == null && r.rows[0].group == null;
+  if (!single) for (const x of r.rows) console.log(`${[x.bucket, x.group].filter((v) => v != null).join("  ")}  ${fmt(x.value)}`);
+  console.log(`${single ? "" : dim("total ")}${fmt(r.total)}${r.previous != null ? dim(`  (the window before: ${fmt(r.previous)})`) : ""}`);
+  if (r.more_groups) console.log(dim("more groups than listed: the largest are shown"));
+  if (r.untracked > 0) console.log(dim(`${r.untracked} older row${r.untracked === 1 ? " has" : "s have"} no created time and aren't counted (they're from before Oalo stamped it)`));
+}
+
+async function call(event, params, flags, opts) {
+  const { url, token } = controlPlane(resolveConfig(flags));
+  if (!url || !token) return fail(`this needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  try {
+    await ch.connect();
+    return await ch.call(event, params, 20000);
+  } catch (e) {
+    fail(e.message, 1);
+    return null;
+  } finally {
+    ch.close();
+  }
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+  return null;
+}

package/src/commands/products.js

@@ -0,0 +1,169 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo products`: what the workspace sells (Oalo commerce, on the
+ * workspace's own Stripe account).
+ *
+ *   oalo products                                       list them
+ *   oalo products create premium --name "Premium" --price 9.99 --monthly
+ *   oalo products edit premium --name "Premium plan"
+ *   oalo products price premium 12.99                   a new price; the old one is archived
+ *   oalo products archive premium --yes                 no longer sold; buyers keep access
+ *   oalo products delete premium --yes                  an archived one nobody bought; frees the id
+ *   oalo products orders [premium] [--limit 50]
+ *
+ * The id (`premium`) is what code uses: BuyButton, a row's product_id, a
+ * member's purchased_products. `oalo typegen` writes them as PRODUCTS and
+ * ProductId so the compiler checks them.
+ *
+ * Live keys and amounts over $500 need --yes: the Base's commerce guardrail
+ * asks for it, the same one the dashboard and the builder go through.
+ */
+export async function products(flags, rest, opts = {}) {
+  const sub = rest[1] || "list";
+  const id = rest[2];
+  if (!["list", "create", "edit", "price", "archive", "delete", "orders"].includes(sub)) return fail(`unknown products command: ${sub}\n\n${USAGE}`, 2);
+  if (["create", "edit", "price", "archive", "delete"].includes(sub) && !id) return fail(`which product? give its id\n\n${USAGE}`, 2);
+
+  let event;
+  let params;
+  if (sub === "list") [event, params] = ["commerce:products:list", {}];
+  else if (sub === "orders") [event, params] = ["commerce:orders:list", { limit: limit(flags) }];
+  else if (sub === "archive") {
+    if (!flags.yes) return fail(`archiving ${id} stops it being sold at once. Its orders stay, and the people who bought it keep their access. Run it again with --yes to go ahead.`, 2);
+    [event, params] = ["commerce:products:delete", { id }];
+  } else if (sub === "delete") {
+    if (!flags.yes) return fail(`deleting ${id} removes it for good and frees its id. Only an archived product nobody bought can be deleted. Run it again with --yes to go ahead.`, 2);
+    [event, params] = ["commerce:products:hard_delete", { id }];
+  } else if (sub === "price") {
+    const cents = toCents(rest[3]);
+    if (cents == null) return fail(`what price? oalo products price ${id} 12.99`, 2);
+    [event, params] = ["commerce:products:set_price", { id, price_cents: cents, confirmed: !!flags.yes }];
+  } else if (sub === "edit") {
+    const patch = {};
+    if (typeof flags.name === "string") patch.title = flags.name;
+    if (typeof flags.description === "string") patch.description = flags.description;
+    if (!Object.keys(patch).length) return fail("what changes? --name <name> and/or --description <text> (the price: oalo products price)", 2);
+    [event, params] = ["commerce:products:update", { id, ...patch }];
+  } else {
+    const made = createParams(id, flags);
+    if (typeof made === "string") return fail(made, 2);
+    [event, params] = ["commerce:products:create", made];
+  }
+
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo products needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  let r;
+  try {
+    await ch.connect();
+    r = await ch.call(event, params, ["create", "price"].includes(sub) ? 60000 : 20000);
+  } catch (e) {
+    const msg = e.message || String(e);
+    if (e.code === "confirm" || /^Needs your confirmation/.test(msg)) return fail(`${msg}\nRun it again with --yes to go ahead.`, 2);
+    if (e.code === "not_found") return fail(`no product ${id} (oalo products lists them)`, 1);
+    if (e.code === "not_archived") return fail(`${id} is still on sale. Archive it first: oalo products archive ${id} --yes`, 1);
+    return fail(msg, 1);
+  } finally {
+    ch.close();
+  }
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  print(sub, id, r, flags);
+}
+
+const USAGE = [
+  "usage: oalo products",
+  '       oalo products create <id> --name "<name>" --price <amount> --once|--monthly|--yearly [--trial <days>] [--currency <code>] [--description <text>] [--live] [--yes]',
+  '       oalo products edit <id> [--name "<name>"] [--description <text>]',
+  "       oalo products price <id> <amount> [--yes]",
+  "       oalo products archive <id> --yes",
+  "       oalo products delete <id> --yes",
+  "       oalo products orders [<id>] [--limit N]",
+].join("\n");
+
+/** "9.99" → 999. Null for anything that isn't a positive amount with at most 2 decimals. */
+export function toCents(s) {
+  if (typeof s !== "string" || !/^\d+(\.\d{1,2})?$/.test(s.trim())) return null;
+  const cents = Math.round(parseFloat(s) * 100);
+  return cents > 0 ? cents : null;
+}
+
+function limit(flags) {
+  const n = parseInt(flags.limit, 10);
+  return Number.isFinite(n) && n > 0 ? Math.min(n, 500) : 50;
+}
+
+/** The create params, or a message saying what's missing. */
+export function createParams(id, flags) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,62}$/.test(id)) return `the id is what code uses: lowercase letters, digits, _ and -, like premium or pro_yearly. Not ${JSON.stringify(id)}.`;
+  if (typeof flags.name !== "string" || !flags.name.trim()) return 'what is it called? --name "Premium"';
+  const cents = toCents(typeof flags.price === "string" ? flags.price : "");
+  if (cents == null) return "what does it cost? --price 9.99";
+  const every = ["once", "monthly", "yearly"].filter((k) => flags[k]);
+  if (every.length !== 1) return "one of --once (paid once), --monthly or --yearly (a subscription)";
+  const trial = flags.trial === undefined ? 0 : parseInt(flags.trial, 10);
+  if (!Number.isInteger(trial) || trial < 0) return "--trial is a number of days";
+  if (trial && every[0] === "once") return "--trial is for a subscription";
+
+  const p = {
+    id,
+    display_name: flags.name.trim(),
+    price_cents: cents,
+    type: every[0] === "once" ? "onetime" : "subscription",
+    platforms: ["stripe"],
+    live: !!flags.live,
+    confirmed: !!flags.yes,
+  };
+  if (typeof flags.description === "string") p.description = flags.description;
+  if (typeof flags.currency === "string") p.currency = flags.currency.toUpperCase();
+  if (p.type === "subscription") p.recurring = { interval: every[0] === "yearly" ? "year" : "month", interval_count: 1, trial_period_days: trial };
+  return p;
+}
+
+const money = (cents, currency) => (cents == null ? "" : `${(cents / 100).toFixed(2)} ${currency || "USD"}`);
+
+function priceText(p) {
+  const each = p.unit_price_cents ? `${money(p.unit_price_cents, p.currency)} per ${p.unit_label || "unit"}` : money(p.price_cents, p.currency);
+  return p.type === "subscription" ? `${each}, a subscription` : `${each}, once`;
+}
+
+function print(sub, id, r, flags) {
+  if (sub === "list") {
+    const list = (r.products || []).filter((p) => flags.all || p.active !== false);
+    if (!list.length) return void console.log(`No products yet. Make one: oalo products create premium --name "Premium" --price 9.99 --monthly`);
+    for (const p of list) {
+      const env = p.env === "live" ? "LIVE" : p.env === "test" ? "test" : "mode unknown";
+      console.log(`${p.id}  ${p.title}  ${dim(`${priceText(p)}, ${env}${p.active === false ? ", archived" : ""}${p.stripe_price_id ? "" : ", no Stripe price"}`)}`);
+    }
+    if (!flags.all && list.length < (r.products || []).length) console.log(dim(`(archived ones hidden: --all shows them)`));
+    return;
+  }
+  if (sub === "orders") {
+    const list = (r.orders || []).filter((o) => !id || o.product_id === id);
+    if (!list.length) return void console.log(id ? `No orders for ${id}.` : "No orders yet.");
+    for (const o of list) {
+      console.log(`${String(o.created_at).slice(0, 16).replace("T", " ")}  ${o.product_id}  ${money(o.amount_cents, o.currency)}  ${dim(`${o.status || ""}${o.email ? `, ${o.email}` : ""}${o.platform ? `, ${o.platform}` : ""}`)}`);
+    }
+    return;
+  }
+  if (sub === "archive") return void console.log(`${id} archived: it isn't sold any more. The people who bought it keep their access.`);
+  if (sub === "delete") return void console.log(`${id} deleted. The id is free for a new product.`);
+  const p = r.product;
+  if (sub === "create" && !p) return void console.log(r.message || `${id} created.`);
+  if (sub === "create") {
+    console.log(`${p.id} created: ${p.title}, ${priceText(p)}${p.env === "live" ? ", LIVE" : ", test mode"}.`);
+    console.log(dim(`Use the id in code: BuyButton productId="${p.id}", or a row's product_id. Run oalo typegen to get it as a ProductId.`));
+    return;
+  }
+  if (sub === "price") return void console.log(`${p.id} now costs ${priceText(p)}. New buyers pay it; existing subscriptions keep their price.`);
+  console.log(`${p.id} updated: ${p.title}.`);
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}

package/src/commands/qa.js

@@ -0,0 +1,98 @@
+import { readFileSync } from "node:fs";
+import { openWorkspace } from "../workspace.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo qa`: a scripted test conversation with a bot, printed as a transcript.
+ *
+ *   oalo qa <bot> "hola" "tela boss, color gris" --channel whatsapp
+ *   oalo qa <bot> --script quote.json          {"channel": "...", "messages": [...]}
+ *
+ * The server (chat:bots:qa_run) opens a preview conversation with no phone
+ * number or external id, so nothing is sent to WhatsApp, Instagram or SMS;
+ * `--channel` only changes how the bot behaves (text mode vs pickers). The
+ * bot's tools and flows run for real. Each turn is streamed as it finishes
+ * (`qa:turn`), and the reply carries the whole run: replies per turn, flow
+ * state, the path of flow steps, and the cost.
+ */
+
+function printTurn(t) {
+  console.log(`\n> ${t.user}`);
+  for (const r of t.replies || []) {
+    const extra = [r.tool && `tool: ${r.tool}`, r.widget && `widget: ${r.widget.widget_name || r.widget.kind}`].filter(Boolean);
+    const text = (r.text || "").trim();
+    if (text) console.log(`  ${r.role === "assistant" ? "bot" : r.role}: ${text}`);
+    if (extra.length) console.log(dim(`  [${extra.join(", ")}]`));
+  }
+  if ((t.replies || []).length === 0) console.log(dim("  (no reply)"));
+  for (const f of t.flows || []) {
+    console.log(dim(`  flow ${f.flow}: ${f.status} at ${f.at}${f.waiting_for ? `, waiting for ${f.waiting_for}` : ""}`));
+  }
+  const secs = (t.ms / 1000).toFixed(1);
+  console.log(dim(`  ${t.settled === "ok" ? "" : `${t.settled}, `}${secs}s${t.error ? `, error: ${t.error}` : ""}`));
+}
+
+export async function qa(flags, rest) {
+  const bot = rest[1];
+  let messages = rest.slice(2);
+  let channel = flags.channel || "web";
+  // A flow to start with the first message, even one that's off, so a new
+  // flow can be tested before anyone turns it on.
+  let flow = typeof flags.flow === "string" ? flags.flow : undefined;
+
+  if (flags.script) {
+    try {
+      const script = JSON.parse(readFileSync(flags.script, "utf8"));
+      messages = script.messages || [];
+      channel = flags.channel || script.channel || channel;
+      flow = flow || (typeof script.flow === "string" ? script.flow : undefined);
+    } catch (e) {
+      console.error(`could not read --script ${flags.script}: ${e.message}`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+
+  if (!bot || messages.length === 0) {
+    console.error('usage: oalo qa <bot> "<message>" ["<message>" ...] [--channel web|whatsapp|instagram|sms] [--flow <name>] [--json]\n       oalo qa <bot> --script <file.json>');
+    process.exitCode = 2;
+    return;
+  }
+
+  const turnTimeout = Number(flags.timeout) > 0 ? Number(flags.timeout) : 90;
+  const ws = await openWorkspace(flags, "qa").catch((e) => (console.error(`qa failed: ${e.message}`), null));
+  if (!ws) return void (process.exitCode = process.exitCode || 2);
+  const { ch } = ws;
+
+  if (!flags.json) {
+    console.error(dim(`test conversation with ${bot} as ${channel}: preview only, nothing is sent to customers; tools and flows run for real`));
+    ch.onEvent((event, payload) => {
+      if (event === "qa:turn") printTurn(payload);
+    });
+  }
+
+  try {
+    // One call for the whole script; the server replies when the last turn
+    // settles, so the window is generous: every turn's own timeout plus slack.
+    const windowMs = (messages.length * (turnTimeout + 15) + 30) * 1000;
+    const result = await ch.call(
+      "chat:bots:qa_run",
+      { bot_id: bot, messages, channel, turn_timeout_s: turnTimeout, label: flags.label || "cli", ...(flow ? { flow } : {}) },
+      windowMs,
+    );
+
+    if (flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const path = (result.flow_path || []).join(" > ");
+      console.log(`\n${path ? `flow path: ${path}\n` : ""}cost: $${result.cost_usd} (conversation ${result.conversation_id}, closed)`);
+    }
+
+    if ((result.turns || []).some((t) => t.settled !== "ok")) process.exitCode = 1;
+  } catch (e) {
+    console.error(`qa failed: ${e.message}`);
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}

package/src/commands/rehearse.js

@@ -0,0 +1,100 @@
+import { readFileSync } from "node:fs";
+import { openWorkspace } from "../workspace.js";
+import { dim, bold } from "../events.js";
+
+/**
+ * `oalo rehearse`: rehearse inbound WhatsApp conversations end to end.
+ *
+ *   oalo rehearse                         the standard scenarios for this workspace
+ *   oalo rehearse --script cases.json     {"scenarios": [...]} (see AppBuilder.Chat.Rehearsal)
+ *
+ * The server (chat:bots:rehearse) has a fictional customer write to one of the
+ * org's numbers and runs the real inbound path: routing, triage loops, moves,
+ * the bot's reply. Sends to the fictional number are recorded, never posted,
+ * the threads stay out of the Inbox and nobody on the team is notified. Each
+ * scenario is printed as it finishes (`rehearse:scenario`).
+ */
+
+function printScenario(s) {
+  const mark = s.pass ? "PASS" : "FAIL";
+  console.log(`\n${bold(mark)} ${s.name}`);
+  if (s.error) return void console.log(`  error: ${s.error}`);
+
+  for (const t of s.turns || []) {
+    console.log(`  > ${t.customer}`);
+    for (const m of t.sent || []) console.log(`    bot: ${(m.text || "").trim()}`);
+    if ((t.sent || []).length === 0) console.log(dim("    (nothing sent)"));
+    if (t.settled !== "ok") console.log(dim(`    ${t.settled} after ${(t.ms / 1000).toFixed(1)}s`));
+  }
+
+  const th = s.thread;
+  if (th) {
+    const who = th.assigned_user_id ? `, assigned to ${th.assigned_user_id}` : "";
+    console.log(dim(`  thread #${th.id} on ${th.bot} (bot ${th.bot_id}), autopilot ${th.autopilot ? "on" : "off"}${who}, tags: ${(th.tags || []).join(", ") || "none"}`));
+  }
+  for (const other of (s.threads || []).filter((t) => t.superseded_by)) {
+    console.log(dim(`  thread #${other.id} on ${other.bot} closed: superseded by #${other.superseded_by}`));
+  }
+  for (const run of s.loop_runs || []) {
+    const steps = (run.steps || []).map((st) => {
+      const r = st.result || {};
+      const detail = typeof r === "string" ? r : [r.category, r.status, r.error, r.reason].filter(Boolean).join(" ");
+      return `${st.step}${detail ? ` (${detail})` : ""}`;
+    });
+    console.log(dim(`  loop ${run.loop}: ${run.status}: ${steps.join(" > ")}`));
+  }
+  if (s.why_silent) console.log(`  silent because: ${s.why_silent}`);
+  for (const c of s.checks || []) console.log(`  ${c.pass ? "ok  " : "FAIL"} ${c.check}`);
+  console.log(dim(`  cost $${s.cost_usd}, customer ${s.customer_number}`));
+}
+
+export async function rehearse(flags) {
+  const params = { suite: true };
+
+  if (flags.script) {
+    try {
+      const script = JSON.parse(readFileSync(flags.script, "utf8"));
+      params.suite = false;
+      params.scenarios = Array.isArray(script) ? script : script.scenarios || [];
+    } catch (e) {
+      console.error(`could not read --script ${flags.script}: ${e.message}`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+  if (flags.number) params.number = String(flags.number);
+  // The bot's public id (bot_...), as `oalo bots` shows it. The Base resolves it
+  // and refuses one it can't find.
+  if (typeof flags.responder === "string") params.responder_bot_id = flags.responder;
+
+  const turnTimeout = Number(flags.timeout) > 0 ? Number(flags.timeout) : 120;
+  params.turn_timeout_s = turnTimeout;
+
+  const ws = await openWorkspace(flags, "rehearse").catch((e) => (console.error(`rehearse failed: ${e.message}`), null));
+  if (!ws) return void (process.exitCode = process.exitCode || 2);
+  const { ch } = ws;
+
+  if (!flags.json) {
+    console.error(dim("rehearsal: a fictional customer writes to your WhatsApp number; nothing is sent, the Inbox and the team see nothing; LLM calls are real"));
+    ch.onEvent((event, payload) => {
+      if (event === "rehearse:scenario") printScenario(payload);
+    });
+  }
+
+  try {
+    // At most 10 messages per scenario; the standard suite has up to 8 scenarios.
+    const count = params.scenarios ? params.scenarios.length : 8;
+    const windowMs = count * 3 * (turnTimeout + 15) * 1000 + 60_000;
+    const result = await ch.call("chat:bots:rehearse", params, windowMs);
+
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`\n${result.passed} passed, ${result.failed} failed`);
+
+    if (result.failed > 0) process.exitCode = 1;
+  } catch (e) {
+    console.error(`rehearse failed: ${e.message}`);
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}