@flowapt/flowiq-cli 0.1.6 → 0.1.8

package/README.md

@@ -1,9 +1,11 @@
 # flowiq
 
 FlowIQ staff CLI. Round-trips agent prompts, questionnaires, fine-tuning,
-contact chats, platform webhooks, outbound messaging webhooks, and FlowMod
-master-group prompts 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
 
@@ -210,6 +212,137 @@ flowiq grp pull 120363408455897717@g.us --last 48h   # or pass the group JID
   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
+```
+
+### Agents — `flowiq agent list|create <org>`
+
+List an org's agents (to discover ids) and create a new one.
+
+```bash
+flowiq agent list <organization_id>        # ★ marks the active agent; shows each id
+flowiq agent create <organization_id> --name "Zara" \
+  --system-prompt-file ./zara-prompt.txt --make-active
+```
+
+`create` inserts a new agent (`created_by` = your staff-key identity), optionally
+seeds its prompt into a single "Main" section, and — with `--make-active` — sets
+it as the org's `active_whatsapp_agent`. New agents start on the app default
+model; set the house model afterwards with `agent config … --model gpt-5.4-mini
+--use-settings-prompt`.
+
+### Targeting a specific agent — `--agent <id>`
+
+By default `prompts`, `questionnaires`, `fine-tuning`, and `agent config` all act
+on the org's **active** agent. To target a **different** agent, pass `--agent <id>`
+(get ids from `agent list`):
+
+```bash
+flowiq prompts pull <org> --agent <agent_id>      # pull a NON-active agent's prompt
+flowiq prompts push <slug>                          # pushes back to that same agent (id is in the file)
+flowiq agent config <org> --agent <agent_id> --model gpt-5.4-mini
+```
+
+`pull` records the agent id in the JSON, so `push` always writes back to the exact
+agent you pulled from (never "whatever is active now").
+
+### 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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.6",
-  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, FlowMod master-group prompts, webhooks, and more without ever touching service-role credentials.",
+  "version": "0.1.8",
+  "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"

package/src/commands/agent-config.js

@@ -0,0 +1,96 @@
+// `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 };
+  if (opts.agent !== undefined) body.agent_id = opts.agent;
+  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, agent_id: opts.agent });
+    } catch (e) {
+      console.error(`Lookup failed: ${e.message}`);
+      process.exit(1);
+    }
+    console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
+    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})${resp.is_active === false ? " [NON-active]" : ""}`);
+  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"}.`);
+}

package/src/commands/agent-updates.js

@@ -0,0 +1,186 @@
+// `flowiq agent-updates pull <org_id> [flags]` / `list`.
+// Read-only: fetches an org's agent_updates + chat context via /cli/agent-updates,
+// then downloads any attachments client-side into ./.flowiq/agent-updates/files/.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const AU_DIR = path.resolve(process.cwd(), ".flowiq", "agent-updates");
+const FILES_DIRNAME = "files";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_MAX_MB = 25;
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+function oneLine(s, n = 120) {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+// Filesystem-safe filename (strip path, control chars, separators).
+function safeFilename(name, fallback) {
+  const base = String(name || "").split("?")[0].split(/[\\/]/).pop().trim();
+  const cleaned = base.replace(/[\x00-\x1f]/g, "").replace(/[\\/]/g, "_");
+  return cleaned || fallback;
+}
+
+// Download one URL to destPath, respecting a byte cap. Never throws.
+async function downloadOne(url, destPath, maxBytes) {
+  let res;
+  try { res = await fetch(url); }
+  catch (e) { return { ok: false, reason: `fetch error: ${e.message}` }; }
+  if (!res.ok) return { ok: false, reason: `http ${res.status}` };
+  const len = Number(res.headers.get("content-length") || 0);
+  if (len && len > maxBytes) return { ok: false, reason: `too large (${len} bytes > cap)` };
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length > maxBytes) return { ok: false, reason: `too large (${buf.length} bytes > cap)` };
+  await fs.mkdir(path.dirname(destPath), { recursive: true });
+  await fs.writeFile(destPath, buf);
+  return { ok: true, bytes: buf.length };
+}
+
+async function downloadUpdateFiles(update, maxBytes) {
+  const baseDir = path.join(AU_DIR, FILES_DIRNAME, update.id);
+  const atts = Array.isArray(update.attachments) ? update.attachments : [];
+  for (let i = 0; i < atts.length; i++) {
+    const a = atts[i];
+    if (!a || !a.url) continue;
+    const fname = safeFilename(a.filename, `attachment-${i + 1}`);
+    if (a.size && a.size > maxBytes) {
+      a.download = { ok: false, reason: `declared size ${a.size} bytes > cap` };
+      continue;
+    }
+    const r = await downloadOne(a.url, path.join(baseDir, fname), maxBytes);
+    a.download = r;
+    if (r.ok) a.local_path = path.join(baseDir, fname);
+  }
+  if (update.superadmin_response_image) {
+    const fname = "admin-" + safeFilename(update.superadmin_response_image, "response-image");
+    const r = await downloadOne(update.superadmin_response_image, path.join(baseDir, fname), maxBytes);
+    update.superadmin_response_image_download = r;
+    if (r.ok) update.superadmin_response_image_local = path.join(baseDir, fname);
+  }
+}
+
+export async function pull(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+
+  const downloadFiles = !opts.noFiles;
+  const maxMb = opts.maxMb != null ? Number.parseFloat(opts.maxMb) : DEFAULT_MAX_MB;
+  if (!Number.isFinite(maxMb) || maxMb <= 0) {
+    console.error(`Invalid --max-mb: ${opts.maxMb}`);
+    process.exit(1);
+  }
+  const maxBytes = Math.round(maxMb * 1024 * 1024);
+
+  const query = { organization_id: orgId };
+  if (opts.status) query.status = opts.status;
+  if (opts.titles) query.titles = opts.titles;
+  if (opts.before != null) query.before = String(opts.before);
+  if (opts.after != null) query.after = String(opts.after);
+  if (opts.recent != null) query.recent = String(opts.recent);
+
+  let resp;
+  try {
+    resp = await http.get("agent-updates", query);
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Download attachments client-side (mutates the update objects with local_path).
+  if (downloadFiles) {
+    for (const u of resp.updates || []) {
+      try { await downloadUpdateFiles(u, maxBytes); }
+      catch (e) { u._file_download_error = e.message; }
+    }
+  }
+  resp.attachments_downloaded = downloadFiles;
+  resp.attachment_max_mb = maxMb;
+
+  await fs.mkdir(AU_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(AU_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const updates = resp.updates || [];
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:            ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  status filter:  ${resp.status_filter}`);
+  console.log(`  title filter:   ${resp.title_filter ? resp.title_filter.join(" | ") : "(none — all)"}`);
+  console.log(`  attachments:    ${downloadFiles ? `auto-download ON (cap ${maxMb}MB)` : "OFF (--no-files)"}`);
+  console.log(`  updates:        ${updates.length}`);
+  if (!updates.length) {
+    console.log("  (no matching updates)");
+    return;
+  }
+  console.log("");
+  updates.forEach((u, i) => {
+    const date = String(u.created_at || "").slice(0, 16).replace("T", " ");
+    console.log(`  [${i + 1}] ${u.title}`);
+    console.log(`      priority=${u.priority}  status=${u.status}  raised=${date}${u.created_by_name ? ` by ${u.created_by_name}` : ""}`);
+    console.log(`      desc: ${oneLine(u.description, 140)}`);
+    if (u.contact) console.log(`      contact: ${u.contact.full_name ?? "(no name)"} (${u.contact.whatsapp_id ?? u.contact.id})`);
+    if (u.attachments && u.attachments.length) {
+      console.log(`      attachments: ${u.attachments.length} (${u.attachments.map((a) => a.filename || a.type || "file").join(", ")})`);
+      for (const a of u.attachments) {
+        if (a.local_path) console.log(`        ↓ ${a.local_path}`);
+        else if (a.download && !a.download.ok) console.log(`        ✗ ${a.filename || "file"}: ${a.download.reason}`);
+      }
+    }
+    if (u.superadmin_response_image_local) console.log(`      admin response image: ↓ ${u.superadmin_response_image_local}`);
+    if (u.context && u.context.messages && u.context.messages.length) {
+      const trig = u.context.messages.find((m) => m.is_trigger);
+      console.log(`      context: ${u.context.total} msgs (anchor=${u.context.anchor})${trig ? ` · trigger: "${oneLine(trig.message, 80)}"` : ""}`);
+    } else {
+      console.log(`      context: (none linked)`);
+    }
+    console.log("");
+  });
+  console.log("Read the JSON for full update text + chat context. Attachments (paths marked ↓) were downloaded to");
+  console.log(`${path.join(AU_DIR, FILES_DIRNAME)}/<update-id>/ — Read those files for visual context, then act.`);
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(AU_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local snapshots — run `agent-updates pull <organization_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local snapshots — run `agent-updates pull <organization_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(AU_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  org:        ${d.organization_name ?? "(unknown)"} (${d.organization_id ?? "?"})`);
+      console.log(`  filter:     status=${d.status_filter ?? "?"} title=${d.title_filter ? d.title_filter.join("|") : "(all)"}`);
+      console.log(`  updates:    ${d.total_updates ?? "?"}`);
+      console.log(`  pulled:     ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}