@flowapt/flowiq-cli 0.1.5 → 0.1.7

package/README.md

@@ -1,9 +1,11 @@
 # flowiq
 
 FlowIQ staff CLI. Round-trips agent prompts, questionnaires, fine-tuning,
-contact chats, platform webhooks, and outbound messaging webhooks through
-`https://api.flowiq.live/cli/*` so the Supabase service role never leaves
-the server.
+contact chats, platform webhooks, outbound messaging webhooks, FlowMod
+master-group prompts, Pin Board tasks, WhatsApp templates, agent-update
+requests, full chat exports, and live agent testing through
+`https://api.flowiq.live/cli/*` so the Supabase service role never leaves the
+server.
 
 ## Install
 
@@ -150,12 +152,174 @@ Validation: `platform` ∈ `{whatsapp, web}`, `type` from the per-platform
 allowed enum, valid http(s) URL, no duplicate (platform, type, url)
 tuples.
 
+### FlowMod prompts — `flowiq flowmod pull|push <slug>` (alias `fm`)
+
+Round-trips a FlowMod org's **master-group** prompts + config. FlowMod groups
+are a separate system from regular WhatsApp agents — their prompts live in the
+`flowmod_master_groups` (model/pre-filter/config/signatures/custom_tools) and
+`flowmod_prompts` (the `main` / `extra` prompt rows, keyed by `master_group_id`)
+tables, read per-message by the `flowmod-group-*` webhooks.
+
+```bash
+flowiq flowmod pull <organization_id>
+# edit ./.flowiq/flowmod/<slug>.json
+flowiq fm push <slug>
+```
+
+The pulled JSON has a `master_groups[]` array; each entry carries its editable
+fields plus a `prompts[]` array (`{ id, type, group_ids, text, data }`). Push
+updates only editable columns — prompt `text`/`data`/`group_ids`/`type`, and
+master-group `name`/`description`/`config`/`pre_filter_prompt`/`events_markdown`/
+`custom_signature*`/`custom_tools` — scoped by row id; it never touches PKs,
+FKs, or timestamps, and there's no `system_prompt` regeneration (FlowMod reads
+the prompt rows directly).
+
+Common uses: edit a master-group's moderator prompt, or flip its reasoning
+effort via `config.reasoningEffort` (`none` / `low` / `medium` / `high`).
+
+### Group chats — `flowiq groups list|pull <name-or-jid>` (alias `grp`)
+
+Read-only pull of **WhatsApp group** chat history (e.g. the `… x Flowapt`
+client comms groups) straight out of the FlowMod **Evolution** Postgres. This
+is the analogue of `messages pull`, but for a group instead of a contact, so
+you can pull a window and summarise it.
+
+> ⚠️ Unlike every other command, this talks to a database **directly** (the
+> Evolution DB is not Supabase and not the `fiq_staff_…` API). To keep this
+> published package secret-free, the connection string comes from your shell
+> environment — set `FLOWMOD_EVO_DB_URL` (or the five `FLOWMOD_DB_*` vars the
+> `flowmod-copilot` edge fn uses) before running. No auth token is needed.
+
+```bash
+export FLOWMOD_EVO_DB_URL='postgres://user:pass@app.flowmod.ai:5555/flowiq-db'
+
+flowiq groups list                               # default instance: flowapt
+flowiq groups list --instance FlowMod            # the other connected instance
+
+flowiq groups pull "Phytoceutics x Flowapt" --last 7d
+flowiq groups pull "Zorora x Flowapt" --since 2026-06-24 --until "2026-06-25 12:00"
+flowiq grp pull 120363408455897717@g.us --last 48h   # or pass the group JID
+# writes ./.flowiq/groups/<instance>-<group-slug>.json + prints a timeline
+```
+
+- Group is matched by JID, exact name, or a unique case-insensitive substring
+  (ambiguous matches list the candidates and exit — pass the JID to disambiguate).
+- Window: `--last <48h|7d|2w|90m>` (default `48h`), or an explicit
+  `--since`/`--until` (SAST; `--until` defaults to now). `--limit` (default
+  1000) keeps the most-recent N in the window.
+- `--json` prints the full payload to stdout instead of the timeline.
+- Read-only — there is no `push`; group history is a system of record.
+  View-once/disappearing messages and raw media bodies can't be read (captions
+  and text come through); history before the instance joined a group may be gappy.
+
+### Pin Board tasks — `flowiq pinboard pull|push|list|list-remote` (alias `pin`)
+
+Round-trips a single internal Pin Board task (`flowapt_tasks` row).
+
+```bash
+flowiq pin list-remote open          # find the task id you want
+flowiq pin pull <task_id>            # → ./.flowiq/pinboard/<slug>.json
+flowiq pin push <slug>               # writes editable fields back, stamps updated_at
+```
+
+Editable fields: `name`, `description`, `status` (open / in_progress / done),
+`urgency` (low / normal / high / critical), `preferred_due_date` (YYYY-MM-DD or
+null), `organizations[]`, `media[]`, `messages[]`, `created_by`. Array columns
+are full-replace within the row.
+
+### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
+
+Read an org's live templates straight from Meta (read-only), and submit new
+ones through the `create-meta-template` edge function.
+
+```bash
+flowiq templates pull <organization_id>   # → ./.flowiq/templates/<slug>.json (Meta-side truth)
+flowiq templates create <organization_id> --request-file req.json
+flowiq templates status <organization_id> --name booking   # poll approval
+```
+
+`req.json` holds `{ template_request, template_data?, media_header?, cards_media? }`.
+Media headers: pass `media_header.file_url` (a public URL) — the edge function
+uploads it to Meta server-side. Approval is async; re-`pull` for the
+authoritative Meta status.
+
+### Org info — `flowiq org info <organization_id>`
+
+Read-only platform detect + active-agent lookup for an org (raw store/Meta
+credentials are stripped server-side).
+
+```bash
+flowiq org info <organization_id>       # platform, storefront url, active agent
+```
+
+### Agent config — `flowiq agent config <organization_id> [flags]`
+
+Set an allowlisted set of the active agent's config fields (the prompt-builder
+"Step 5"). With no flags, prints the current config.
+
+```bash
+flowiq agent config <organization_id>                        # show current
+flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.4-mini \
+  --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
+```
+
+Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
+the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
+`view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
+`shopify_products_web_chat`), and `discount.enabled`. Anything else is rejected;
+every change is reported before → after.
+
+### Agent updates — `flowiq agent-updates pull|list` (alias `au`)
+
+Read-only pull of an org's client-raised "change the agent" requests
+(`agent_updates`), each with the chat context around the triggering message +
+the linked contact. Attachments are downloaded locally.
+
+```bash
+flowiq au pull <organization_id>                       # pending, with context
+flowiq au pull <organization_id> --status all --titles "EFT, bank"
+flowiq au pull <organization_id> --before 20 --after 10 --no-files
+# → ./.flowiq/agent-updates/<slug>.json + files/<update-id>/<attachment>
+```
+
+### Chat export — `flowiq export chats <organization_id> [--out <path>]`
+
+Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"
+(keyset-paginated server-side so it can't time out on big orgs).
+
+```bash
+flowiq export chats <organization_id>                      # → ./.flowiq/exports/<slug>-chats.txt
+flowiq export chats <organization_id> --out ./phyto-chats.txt
+```
+
+### Agent testing — `flowiq test <subcommand>`
+
+Drive an org's **live** agent through the web/test channel and read the reply
+back — **never sends a real WhatsApp** (the web branch only inserts the reply).
+
+```bash
+flowiq test send <organization_id> "What are your bestsellers?" --clear
+flowiq test send <organization_id> "What is this?" --image https://…/photo.jpg
+flowiq test qa <organization_id>                     # bundled generic smoke pack
+flowiq test scenario <organization_id> ./pack.json   # your own pack (expect/expectNot)
+flowiq test clear <organization_id>
+# phase 2 — adversarial parallel stress:
+flowiq test stress <organization_id> ./stress.json --concurrency 6
+flowiq test extract <organization_id>                # rebuild transcripts for a judge
+flowiq test cleanup <organization_id> --confirm      # delete the stress contacts
+```
+
+`--agent <id>` targets a specific (non-active) agent. `test stress cleanup` is
+destructive and requires `--confirm`.
+
 ## Environment variable overrides
 
 | Var | Default | Use |
 |---|---|---|
 | `FLOWIQ_API_URL` | `https://api.flowiq.live` | Override the API host (local dev, staging). |
 | `FLOWIQ_TOKEN` | (saved in `~/.config/flowiq/auth.json`) | Override the auth token, useful for CI. |
+| `FLOWMOD_EVO_DB_URL` | (none) | Full `postgres://` URL for `groups` (Evolution DB). Required for `groups`. |
+| `FLOWMOD_DB_HOST/PORT/USER/PASS/NAME` | (none) | Alternative to `FLOWMOD_EVO_DB_URL` — assembled into a connection string. |
 
 ## Upgrading
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.5",
-  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, webhooks, and more without ever touching service-role credentials.",
+  "version": "0.1.7",
+  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {
     "flowiq": "bin/flowiq.js"
@@ -18,7 +18,8 @@
     "start": "node bin/flowiq.js"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "pg": "^8.22.0"
   },
   "homepage": "https://github.com/MattFlowapt/flow-v1/tree/main/cli",
   "repository": {

package/src/commands/agent-config.js

@@ -0,0 +1,95 @@
+// `flowiq agent config <organization_id> [flags]` — the prompt-builder skill's
+// Step 5 as a staff-key call. Writes an allowlisted set of agent fields
+// (use_settings_prompt, model, tool flags, discount.enabled, rename) via
+// /cli/agent-config. With no write flags, prints the current config.
+
+import { http } from "../http.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function parseBool(v, label) {
+  if (v === true) return true; // bare presence of an optional flag
+  const s = String(v).toLowerCase();
+  if (s === "true" || s === "1" || s === "yes" || s === "on") return true;
+  if (s === "false" || s === "0" || s === "no" || s === "off") return false;
+  console.error(`Error: ${label} must be true or false (got "${v}").`);
+  process.exit(1);
+}
+
+// commander collector for repeatable --tool woo_order_build=true
+export function collectTool(val, acc) {
+  acc = acc || [];
+  acc.push(val);
+  return acc;
+}
+
+function printSnapshot(title, snap) {
+  console.log(`  ${title}:`);
+  for (const [k, v] of Object.entries(snap)) {
+    console.log(`    ${k.padEnd(30)} ${v === null ? "(unset)" : v}`);
+  }
+}
+
+export async function config(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+
+  const body = { organization_id: orgId };
+  const settings = {};
+  if (opts.useSettingsPrompt !== undefined) settings.use_settings_prompt = parseBool(opts.useSettingsPrompt, "--use-settings-prompt");
+  if (opts.model !== undefined) settings.model = opts.model;
+  if (Object.keys(settings).length) body.settings = settings;
+  if (opts.rename !== undefined) body.name = opts.rename;
+  if (opts.discount !== undefined) body.discount_enabled = parseBool(opts.discount, "--discount");
+
+  if (opts.tool && opts.tool.length) {
+    const flags = {};
+    for (const pair of opts.tool) {
+      const eq = pair.indexOf("=");
+      if (eq < 0) {
+        console.error(`Error: --tool expects flag=bool (got "${pair}").`);
+        process.exit(1);
+      }
+      const key = pair.slice(0, eq).trim();
+      flags[key] = parseBool(pair.slice(eq + 1), `--tool ${key}`);
+    }
+    body.tool_flags = flags;
+  }
+
+  const hasWrite =
+    body.settings || body.name !== undefined || body.tool_flags || body.discount_enabled !== undefined;
+
+  // No write flags → just show current config.
+  if (!hasWrite) {
+    let resp;
+    try {
+      resp = await http.get("agent-config", { organization_id: orgId });
+    } catch (e) {
+      console.error(`Lookup failed: ${e.message}`);
+      process.exit(1);
+    }
+    console.log(`${resp.organization_name} → agent ${resp.agent_id}`);
+    printSnapshot("current", resp.current);
+    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount to change)");
+    return;
+  }
+
+  let resp;
+  try {
+    resp = await http.post("agent-config", body);
+  } catch (e) {
+    console.error(`Config update failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Updated agent ${resp.agent_id} (${resp.organization_name})`);
+  console.log(`  changed: ${resp.changed.join(", ") || "(nothing)"}`);
+  for (const k of resp.changed) {
+    const b = resp.before?.[k];
+    const a = resp.after?.[k];
+    console.log(`    ${k.padEnd(30)} ${b === null || b === undefined ? "(unset)" : b} → ${a === null || a === undefined ? "(unset)" : a}`);
+  }
+}

package/src/commands/agent-test.js

@@ -0,0 +1,232 @@
+// `flowiq test <subcommand>` — drive an org's LIVE agent through the web/test
+// channel (never sends a real WhatsApp). The server (/cli/agent-test,
+// /cli/agent-stress) does one turn per request; this CLI loops turns, runs the
+// expect/expectNot checks client-side, and prints the transcript.
+//
+//   test resolve  <org_id> [--agent <id>]
+//   test send     <org_id> <message...> [--agent] [--clear] [--sender] [--image] [--timeout] [--json]
+//   test scenario <org_id> <file.json> [--agent] [--no-clear-between] [--json] [--sender] [--timeout]
+//   test qa       <org_id> [--agent] ...           (bundled generic smoke pack)
+//   test clear    <org_id> [--agent]
+//   test stress   <org_id> [pack.json] [--agent] [--concurrency 6] [--timeout] [--out] [--contact]
+//   test cleanup  <org_id> [--agent] --confirm     (deletes stress contacts)
+//   test extract  <org_id> [--out]                 (rebuild transcripts from DB)
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { http } from "../http.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const QA_PACK = path.resolve(__dirname, "..", "data", "scenarios.qa.json");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+}
+
+async function runTurn(orgId, { agent, message, image, clear, sender, timeout }) {
+  return http.post("agent-test", {
+    action: "send",
+    organization_id: orgId,
+    agent_id: agent,
+    message,
+    image_url: image,
+    clear: !!clear,
+    sender,
+    timeout_ms: timeout,
+  });
+}
+
+async function clearConv(orgId, agent) {
+  return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent });
+}
+
+function checkExpectations(turn, replyText) {
+  const results = [];
+  const hay = (replyText || "").toLowerCase();
+  for (const e of turn.expect || []) results.push({ kind: "expect", needle: e, ok: hay.includes(String(e).toLowerCase()) });
+  for (const e of turn.expectNot || []) results.push({ kind: "expectNot", needle: e, ok: !hay.includes(String(e).toLowerCase()) });
+  return results;
+}
+
+function printTurn(sc, t, userText, r, checks) {
+  if (t === 0) console.log(`\n━━ ${sc.tq ? sc.tq + " · " : ""}${sc.title || sc.id} ━━`);
+  console.log(`\n  🧑 ${userText}`);
+  if (r.tool_calls?.length) console.log(`  ⚙  tools: ${r.tool_calls.join(", ")}`);
+  if (r.reply) console.log(`  🤖 ${r.reply.split("\n").join("\n     ")}`);
+  else console.log(`  ⚠  no reply — status=${r.status}${r.raw?.error ? " (" + r.raw.error + ")" : ""}`);
+  for (const c of checks || []) {
+    console.log(`     ${c.ok ? "✅" : "❌"} ${c.kind === "expectNot" ? "must NOT contain" : "contains"} "${c.needle}"`);
+  }
+}
+
+export async function resolve(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("agent-test", { organization_id: orgId, agent_id: opts.agent }); }
+  catch (e) { console.error(`Resolve failed: ${e.message}`); process.exit(1); }
+  console.log(JSON.stringify(resp, null, 2));
+}
+
+export async function send(orgId, messageParts, opts = {}) {
+  requireOrg(orgId);
+  const message = (messageParts || []).join(" ");
+  if (!message) { console.error("usage: test send <org_id> <message...>"); process.exit(1); }
+  let r;
+  try {
+    r = await runTurn(orgId, { agent: opts.agent, message, image: opts.image, clear: opts.clear, sender: opts.sender, timeout: opts.timeout });
+  } catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`# org=${r.org?.name} agent=${r.agent?.name}${r.agent?.is_active ? " (active)" : " (override)"} contact=${r.contact?.id}`);
+  printTurn({ title: "send", tq: "" }, 0, message, r, []);
+}
+
+async function runPack(orgId, pack, opts) {
+  const scenarios = pack.scenarios || pack;
+  const clearBetween = !opts.noClearBetween;
+  console.log(`# ${pack.name || "pack"} — ${scenarios.length} scenarios · org ${orgId}`);
+  const results = [];
+  for (let s = 0; s < scenarios.length; s++) {
+    const sc = scenarios[s];
+    if (clearBetween) {
+      try { await clearConv(orgId, opts.agent); } catch (e) { console.error(`  (clear failed: ${e.message})`); }
+    }
+    const scResult = { id: sc.id, tq: sc.tq, title: sc.title, turns: [] };
+    for (let t = 0; t < sc.turns.length; t++) {
+      const turn = sc.turns[t];
+      let r;
+      try {
+        r = await runTurn(orgId, { agent: opts.agent, message: turn.text, sender: opts.sender, timeout: opts.timeout });
+      } catch (e) {
+        r = { status: "error", reply: null, tool_calls: [], raw: { error: e.message } };
+      }
+      const checks = checkExpectations(turn, r.reply);
+      scResult.turns.push({ ...r, checks });
+      if (!opts.json) printTurn(sc, t, turn.text, r, checks);
+    }
+    results.push(scResult);
+  }
+  let pass = 0, fail = 0;
+  for (const sc of results) for (const t of sc.turns) for (const c of t.checks || []) (c.ok ? pass++ : fail++);
+  if (opts.json) console.log(JSON.stringify(results, null, 2));
+  else console.log(`\n━━ assertions: ${pass} passed, ${fail} failed ━━`);
+}
+
+export async function scenario(orgId, file, opts = {}) {
+  requireOrg(orgId);
+  const filePath = path.isAbsolute(file) ? file : path.resolve(process.cwd(), file);
+  let pack;
+  try { pack = JSON.parse(await fs.readFile(filePath, "utf8")); }
+  catch (e) { console.error(`Cannot read scenario file ${filePath}: ${e.message}`); process.exit(1); }
+  await runPack(orgId, pack, opts);
+}
+
+export async function qa(orgId, opts = {}) {
+  requireOrg(orgId);
+  const pack = JSON.parse(await fs.readFile(QA_PACK, "utf8"));
+  await runPack(orgId, pack, opts);
+}
+
+export async function clear(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await clearConv(orgId, opts.agent); }
+  catch (e) { console.error(`Clear failed: ${e.message}`); process.exit(1); }
+  console.log(`Cleared web conversation for contact ${resp.contact_id} (history hidden via memory_cutoff; onboarding/disclaimer state NOT reset).`);
+}
+
+// ---------- phase 2: stress + extract ----------
+
+async function pool(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function lane() {
+    while (next < items.length) {
+      const i = next++;
+      try { results[i] = await worker(items[i], i); }
+      catch (e) { results[i] = { id: items[i].id, error: String(e?.message || e) }; }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
+  return results;
+}
+
+export async function stress(orgId, file, opts = {}) {
+  requireOrg(orgId);
+  const packFile = file || "scenarios.stress.json";
+  const filePath = path.isAbsolute(packFile) ? packFile : path.resolve(process.cwd(), packFile);
+  let pack;
+  try { pack = JSON.parse(await fs.readFile(filePath, "utf8")); }
+  catch (e) { console.error(`Cannot read stress pack ${filePath}: ${e.message}`); process.exit(1); }
+  const scenarios = pack.scenarios || pack;
+
+  let head;
+  try { head = await http.get("agent-stress", { organization_id: orgId, agent_id: opts.agent }); }
+  catch (e) { console.error(`Resolve failed: ${e.message}`); process.exit(1); }
+
+  const fixedContact = opts.contact || null;
+  const concurrency = fixedContact ? 1 : (opts.concurrency ? Number.parseInt(opts.concurrency, 10) : 6);
+  const timeout = opts.timeout;
+  const t0 = Date.now();
+  console.error(`# ${pack.name || packFile}: ${scenarios.length} scenarios · org=${head.org.name} agent=${head.agent.name} · concurrency=${concurrency}`);
+
+  let done = 0;
+  const results = await pool(scenarios, concurrency, async (sc) => {
+    let contactId = fixedContact;
+    if (!contactId) {
+      const ec = await http.post("agent-stress", { action: "ensure_contact", organization_id: orgId, agent_id: opts.agent, scenario_id: sc.id, fresh: !!sc.fresh });
+      contactId = ec.contact_id;
+    }
+    const turns = [];
+    for (let i = 0; i < sc.turns.length; i++) {
+      const r = await http.post("agent-stress", {
+        action: "turn", organization_id: orgId, agent_id: opts.agent, contact_id: contactId,
+        text: sc.turns[i].text, sender: "Stress Tester", idx: `${sc.id}_${i}`, timeout_ms: timeout, reenable_bot: !!fixedContact,
+      });
+      turns.push(r);
+    }
+    const rec = { id: sc.id, category: sc.category, severity: sc.severity || "medium", tq: sc.tq || null, title: sc.title, criteria: sc.criteria, fresh: !!sc.fresh, contactId, turns };
+    done++;
+    const last = rec.turns[rec.turns.length - 1];
+    const snippet = last?.reply ? last.reply.replace(/\s+/g, " ").slice(0, 70) : `⚠ ${last?.status}`;
+    console.error(`  [${done}/${scenarios.length}] ${String(rec.severity).toUpperCase().padEnd(8)} ${String(rec.id).padEnd(22)} ${snippet}`);
+    return rec;
+  });
+
+  const outPath = opts.out ? path.resolve(opts.out) : path.resolve(process.cwd(), ".flowiq", "agent-test", "stress-results.json");
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  const payload = {
+    org: head.org, agent: head.agent, ran_at: new Date().toISOString(),
+    duration_ms: Date.now() - t0, scenario_count: scenarios.length, results,
+  };
+  await fs.writeFile(outPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  const noReply = results.filter((r) => r.turns?.some((t) => !t.reply)).length;
+  console.error(`\n# done in ${Math.round((Date.now() - t0) / 1000)}s · ${results.length} scenarios · ${noReply} with a no-reply turn · → ${outPath}`);
+}
+
+export async function cleanup(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (!opts.confirm) {
+    console.error("Refusing to delete stress contacts without --confirm (this DELETEs contacts + their messages/sessions).");
+    process.exit(1);
+  }
+  let resp;
+  try { resp = await http.post("agent-stress", { action: "cleanup", organization_id: orgId, agent_id: opts.agent, confirm: true }); }
+  catch (e) { console.error(`Cleanup failed: ${e.message}`); process.exit(1); }
+  console.error(`Cleaned up ${resp.deleted} stress contact${resp.deleted === 1 ? "" : "s"} + their messages/sessions.`);
+}
+
+export async function extract(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.post("agent-stress", { action: "extract", organization_id: orgId, agent_id: opts.agent }); }
+  catch (e) { console.error(`Extract failed: ${e.message}`); process.exit(1); }
+  const outPath = opts.out ? path.resolve(opts.out) : path.resolve(process.cwd(), ".flowiq", "agent-test", "judge_input.json");
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  await fs.writeFile(outPath, JSON.stringify(resp.scenarios, null, 2) + "\n", "utf8");
+  console.log(`Wrote ${outPath} — ${resp.scenarios.length} scenario transcript${resp.scenarios.length === 1 ? "" : "s"}.`);
+}