@flowapt/flowiq-cli 0.9.6 → 0.9.8

package/src/commands/agent-config.js

@@ -1,8 +1,11 @@
 // `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.
+// (use_settings_prompt, model, tool flags, discount.enabled, rename, tool
+// instructions, link shortening, email identity / request recipients, send
+// success rules, after-escalation text, knowledge search, human_notify /
+// order_notify) via /cli/agent-config. With no write flags, prints the current config.
 
+import { readFileSync } from "node:fs";
 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;
@@ -29,10 +32,77 @@ export function collectToolName(val, acc) {
   return acc;
 }
 
-function printSnapshot(title, snap) {
+// "@path" reads the file; anything else is the literal text.
+export function readValue(v, label) {
+  if (typeof v !== "string" || !v.startsWith("@")) return v;
+  try {
+    return readFileSync(v.slice(1), "utf8").replace(/\r?\n$/, "");
+  } catch (e) {
+    console.error(`Error: ${label} could not read ${v.slice(1)}: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// "key=value" → [key, value]; the value may itself contain "=".
+export function splitPair(pair, label) {
+  const eq = pair.indexOf("=");
+  if (eq < 1) {
+    console.error(`Error: ${label} expects key=value (got "${pair}").`);
+    process.exit(1);
+  }
+  return [pair.slice(0, eq).trim(), pair.slice(eq + 1)];
+}
+
+export function parseShorten(v, label) {
+  const s = String(v).trim().toLowerCase();
+  if (["on", "true", "yes", "1"].includes(s)) return true;
+  if (["off", "false", "no", "0"].includes(s)) return false;
+  if (s === "default") return null;
+  console.error(`Error: ${label} must be on, off or default (got "${v}").`);
+  process.exit(1);
+}
+
+// --knowledge enabled=true,match_count=8,min_similarity=0.3 ("default" clears a key)
+export function parseKnowledge(v) {
+  const out = {};
+  for (const part of String(v).split(",").map((p) => p.trim()).filter(Boolean)) {
+    const [k, raw] = splitPair(part, "--knowledge");
+    const val = raw.trim();
+    if (val === "default" || val === "") out[k] = null;
+    else if (k === "enabled") out[k] = parseBool(val, "--knowledge enabled");
+    else if (!Number.isNaN(Number(val))) out[k] = Number(val);
+    else out[k] = val; // the server names the bad value
+  }
+  return out;
+}
+
+export function parseJsonObject(v, label) {
+  const text = readValue(v, label);
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch (e) {
+    console.error(`Error: ${label} must be a JSON object or @file.json (${e.message}).`);
+    process.exit(1);
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    console.error(`Error: ${label} must be a JSON object (keys are merged; null deletes a key).`);
+    process.exit(1);
+  }
+  return obj;
+}
+
+function short(v, full) {
+  if (v === null || v === undefined) return "(unset)";
+  const s = String(v).replace(/\s+/g, " ");
+  if (full) return String(v);
+  return s.length <= 140 ? s : `${s.slice(0, 137)}… (${String(v).length} chars; --full shows all)`;
+}
+
+function printSnapshot(title, snap, full = false) {
   console.log(`  ${title}:`);
   for (const [k, v] of Object.entries(snap)) {
-    console.log(`    ${k.padEnd(30)} ${v === null ? "(unset)" : v}`);
+    console.log(`    ${k.padEnd(38)} ${short(v, full)}`);
   }
 }
 
@@ -60,6 +130,47 @@ export async function config(orgId, opts = {}) {
     };
   }
 
+  if (opts.toolInstruction?.length) {
+    body.tool_instructions = {};
+    for (const pair of opts.toolInstruction) {
+      const [tool, text] = splitPair(pair, "--tool-instruction");
+      body.tool_instructions[tool] = readValue(text, `--tool-instruction ${tool}`);
+    }
+  }
+  if (opts.shortenLinks?.length) {
+    body.url_shortening = {};
+    for (const pair of opts.shortenLinks) {
+      const [ch, v] = splitPair(pair, "--shorten-links");
+      body.url_shortening[ch] = parseShorten(v, `--shorten-links ${ch}`);
+    }
+  }
+  const identity = {};
+  if (opts.emailFromName !== undefined) identity.from_name = opts.emailFromName;
+  if (opts.emailSignatureName !== undefined) identity.signature_name = opts.emailSignatureName;
+  if (opts.emailSignatureTitle !== undefined) identity.signature_title = opts.emailSignatureTitle;
+  if (Object.keys(identity).length) body.email_identity = identity;
+  const emailRequest = {};
+  if (opts.emailRequestTo !== undefined) {
+    emailRequest.to = String(opts.emailRequestTo).split(/[,;\s]+/).map((e) => e.trim()).filter(Boolean);
+  }
+  if (opts.emailRequestSubjectPrefix !== undefined) emailRequest.subject_prefix = opts.emailRequestSubjectPrefix;
+  if (Object.keys(emailRequest).length) body.email_request = emailRequest;
+  if (opts.sendSuccessRule?.length || opts.sendSuccess !== undefined) {
+    body.send_success = {};
+    if (opts.sendSuccess !== undefined) body.send_success.enabled = parseBool(opts.sendSuccess, "--send-success");
+    if (opts.sendSuccessRule?.length) {
+      body.send_success.rules = {};
+      for (const pair of opts.sendSuccessRule) {
+        const [when, text] = splitPair(pair, "--send-success-rule");
+        body.send_success.rules[when] = readValue(text, `--send-success-rule ${when}`);
+      }
+    }
+  }
+  if (opts.afterEscalation !== undefined) body.after_escalation = readValue(opts.afterEscalation, "--after-escalation");
+  if (opts.knowledge !== undefined) body.knowledge = parseKnowledge(opts.knowledge);
+  if (opts.humanNotify !== undefined) body.human_notify = parseJsonObject(opts.humanNotify, "--human-notify");
+  if (opts.orderNotify !== undefined) body.order_notify = parseJsonObject(opts.orderNotify, "--order-notify");
+
   if (opts.tool && opts.tool.length) {
     const flags = {};
     for (const pair of opts.tool) {
@@ -74,8 +185,12 @@ export async function config(orgId, opts = {}) {
     body.tool_flags = flags;
   }
 
-  const hasWrite =
-    body.settings || body.name !== undefined || body.tool_flags || body.base_tool_changes || body.discount_enabled !== undefined;
+  const WRITE_KEYS = [
+    "settings", "name", "tool_flags", "base_tool_changes", "discount_enabled", "tool_instructions",
+    "url_shortening", "email_identity", "email_request", "send_success", "after_escalation",
+    "knowledge", "human_notify", "order_notify",
+  ];
+  const hasWrite = WRITE_KEYS.some((k) => body[k] !== undefined);
 
   // No write flags → just show current config.
   if (!hasWrite) {
@@ -86,9 +201,26 @@ export async function config(orgId, opts = {}) {
       console.error(`Lookup failed: ${e.message}`);
       process.exit(1);
     }
+    if (opts.json) {
+      console.log(JSON.stringify(resp, null, 2));
+      return;
+    }
     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 / --reasoning-effort / --rename / --tool / --disable-base-tool / --enable-base-tool / --discount / --test-contact-number / --test-contact-name to change)");
+    printSnapshot("current", resp.current, opts.full);
+    console.log(`
+Settable (flowiq agent config --help for the value formats):
+  --use-settings-prompt  --model  --reasoning-effort  --rename  --discount
+  --tool <flag=bool>  --disable-base-tool / --enable-base-tool <name>
+  --test-contact-number / --test-contact-name
+  --tool-instruction <tool=text|@file>       settings.tool_instructions ("" removes)
+  --shorten-links <channel=on|off|default>   disable_url_shortening
+  --email-from-name / --email-signature-name / --email-signature-title
+  --email-request-to <a,b> / --email-request-subject-prefix
+  --send-success-rule <when=text|@file>  --send-success <bool>
+  --after-escalation <text|@file>            human_notify.success_instructions
+  --knowledge enabled=…,match_count=…,min_similarity=…
+  --human-notify / --order-notify <json|@file.json>  (merged; null deletes a key)
+Not settable here yet: additional_config (use \`flowiq knowledge\`), additional_tools (\`flowiq ct\`).`);
     return;
   }
 
@@ -106,7 +238,7 @@ export async function config(orgId, opts = {}) {
   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}`);
+    console.log(`    ${k.padEnd(38)} ${short(b, opts.full)} → ${short(a, opts.full)}`);
   }
   for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
 }

package/src/commands/agent-test.js

@@ -4,10 +4,10 @@
 // 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 send     <org_id> <message...> [--agent] [--clear] [--sender] [--image] [--timeout] [--json] [--force]
 //   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 clear    <org_id> [--agent] [--force]
 //   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)
@@ -28,7 +28,9 @@ function requireOrg(orgId) {
   }
 }
 
-async function runTurn(orgId, { agent, message, image, clear, sender, timeout }) {
+// force: the server refuses send / clear on a test contact that had real
+// (non-web) inbound in the last 6 h, i.e. a live customer conversation.
+async function runTurn(orgId, { agent, message, image, clear, sender, timeout, force }) {
   return http.post("agent-test", {
     action: "send",
     organization_id: orgId,
@@ -38,11 +40,18 @@ async function runTurn(orgId, { agent, message, image, clear, sender, timeout })
     clear: !!clear,
     sender,
     timeout_ms: timeout,
+    force: !!force,
   });
 }
 
-async function clearConv(orgId, agent) {
-  return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent });
+async function clearConv(orgId, agent, force) {
+  return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent, force: !!force });
+}
+
+let warned = false;
+function printWarnings(r) {
+  if (warned) return;
+  for (const w of r?.warnings || []) { console.error(`⚠ ${w}`); warned = true; }
 }
 
 // A bare string is ONE needle, not a list of characters. Iterating a string
@@ -88,9 +97,11 @@ export async function send(orgId, messageParts, opts = {}) {
   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 });
+    r = await runTurn(orgId, { agent: opts.agent, message, image: opts.image, clear: opts.clear, sender: opts.sender, timeout: opts.timeout, force: opts.force });
   } catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
   if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  printWarnings(r);
+  if (opts.clear && r.previous_memory_cutoff !== undefined) console.log(`# cleared first; previous memory_cutoff: ${r.previous_memory_cutoff ?? "(none)"}`);
   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, []);
 }
@@ -103,14 +114,15 @@ async function runPack(orgId, pack, opts) {
   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})`); }
+      try { printWarnings(await clearConv(orgId, opts.agent, opts.force)); } 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 });
+        r = await runTurn(orgId, { agent: opts.agent, message: turn.text, sender: opts.sender, timeout: opts.timeout, force: opts.force });
+        printWarnings(r);
       } catch (e) {
         r = { status: "error", reply: null, tool_calls: [], raw: { error: e.message } };
       }
@@ -144,10 +156,12 @@ export async function qa(orgId, opts = {}) {
 export async function clear(orgId, opts = {}) {
   requireOrg(orgId);
   let resp;
-  try { resp = await clearConv(orgId, opts.agent); }
+  try { resp = await clearConv(orgId, opts.agent, opts.force); }
   catch (e) { console.error(`Clear failed: ${e.message}`); process.exit(1); }
+  printWarnings(resp);
   const tools = Number(resp.tools_cleared || 0);
   console.log(`Cleared web conversation for contact ${resp.contact_id} (history hidden via memory_cutoff; ${tools} remembered tool result(s) set aside in more_data.tool_usage_history_cleared; onboarding/disclaimer state NOT reset).`);
+  console.log(`Previous memory_cutoff: ${resp.previous_memory_cutoff ?? "(none)"}${resp.previous_memory_cutoff ? " (to undo, set contacts.memory_cutoff back to it)" : ""}`);
 }
 
 // ---------- phase 2: stress + extract ----------

package/src/commands/agent-updates.js

@@ -320,8 +320,8 @@ export async function resolve(updateId, opts = {}) {
     process.exit(1);
   }
   const status = opts.status || "resolved";
-  if (!["resolved", "declined"].includes(status)) {
-    console.error(`Error: --status must be resolved or declined (got "${status}").`);
+  if (!["resolved", "declined", "in_progress"].includes(status)) {
+    console.error(`Error: --status must be resolved, declined or in_progress (got "${status}").`);
     process.exit(1);
   }
   // R-3: a client-facing note is mandatory on resolve (--yes does NOT waive it).
@@ -332,7 +332,7 @@ export async function resolve(updateId, opts = {}) {
   }
 
   if (!opts.yes) {
-    console.log(`About to mark update ${updateId} as ${status.toUpperCase()}.`);
+    console.log(`About to mark update ${updateId} as ${status.toUpperCase()}${status === "in_progress" ? " (not closed: no resolution stamp)" : ""}.`);
     if (opts.note) console.log(`The client will read:  FlowIQ: ${opts.note}`);
     if (opts.internal) console.log(`Staff-only note:       ${opts.internal}`);
     const answer = await confirmPrompt("Type y to confirm: ");
@@ -363,6 +363,7 @@ export async function resolve(updateId, opts = {}) {
   console.log(`  title:     ${resp.title}`);
   console.log(`  was:       ${resp.previous_status}`);
   console.log(`  by:        ${resp.resolved_by_email ?? resp.resolved_by}`);
+  if (resp.status === "in_progress") console.log(`  still open: resolve it later with --note once the fix is proven.`);
   if (resp.superadmin_comment) console.log(`  client:    FlowIQ: ${resp.superadmin_comment}`);
   if (resp.internal_notes) console.log(`  internal:  ${resp.internal_notes}`);
   if (resp.already_resolved) console.log(`  ⚠ was already terminal (${resp.previous_status}) — note/status overwritten.`);

package/src/commands/audit.js

@@ -61,6 +61,7 @@ export async function list(orgId, opts = {}) {
       user: opts.user,
       since: opts.since,
       until: opts.until,
+      before: opts.before,
       limit: opts.limit,
     });
   } catch (e) {
@@ -80,7 +81,10 @@ export async function list(orgId, opts = {}) {
   }
 
   console.log("");
-  console.log(`${entries.length} entr${entries.length === 1 ? "y" : "ies"} (newest first)`);
+  const total = resp.total ?? entries.length;
+  console.log(resp.capped
+    ? `${entries.length} of ${total.toLocaleString()} matching entries (newest first; limit ${resp.limit}${resp.requested_limit > resp.limit ? `, the most one call returns — you asked for ${resp.requested_limit}` : ""})`
+    : `${entries.length} entr${entries.length === 1 ? "y" : "ies"} (newest first)`);
   console.log("");
   console.log(`  ${pad("WHEN (SAST)", 17)} ${pad("WHO", 24)} ${pad("WHAT", 26)} SUMMARY`);
   console.log(`  ${"-".repeat(17)} ${"-".repeat(24)} ${"-".repeat(26)} ${"-".repeat(40)}`);
@@ -101,6 +105,9 @@ export async function list(orgId, opts = {}) {
   for (const e of entries) {
     console.log(`    ${e.id}  ${e.endpoint} ${e.action}`);
   }
+  if (resp.capped && resp.next_before) {
+    console.log(`\n  ${(total - entries.length).toLocaleString()} older match(es) not shown: add --before ${resp.next_before}`);
+  }
   console.log("");
 }
 

package/src/commands/broadcast.js

@@ -1935,15 +1935,19 @@ export async function listRemote(orgId, opts = {}) {
       ...(opts.limit ? { limit: Number(opts.limit) } : {}),
       ...(opts.template ? { template: opts.template } : {}),
       ...(opts.since ? { since: opts.since } : {}),
+      ...(opts.minRecipients ? { min_recipients: Number(opts.minRecipients) } : {}),
     });
   } catch (e) { console.error(`Listing failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
   const rows = resp.broadcasts || [];
-  if (!rows.length) { console.log(`No broadcasts found for ${resp.organization_name}${opts.template || opts.since ? " matching the filters" : ""}.`); return; }
+  if (!rows.length) { console.log(`No broadcasts found for ${resp.organization_name}${opts.template || opts.since || opts.minRecipients ? " matching the filters" : ""}.`); return; }
   // Full ids one per row, deliberately — an id you can't paste into `bc status`
   // is useless (the same lesson the audit listing learned).
   const sast = (iso) => { try { return new Date(iso).toLocaleString("sv-SE", { timeZone: "Africa/Johannesburg" }).slice(0, 16); } catch { return iso; } };
-  console.log(`Broadcasts — ${resp.organization_name} (${rows.length} shown, newest first; times SAST)`);
+  const shown = resp.capped
+    ? `${rows.length} of ${resp.total.toLocaleString()} shown`
+    : `${rows.length} shown`;
+  console.log(`Broadcasts — ${resp.organization_name} (${shown}${resp.min_recipients ? `, ${resp.min_recipients}+ recipients` : ""}, newest first; times SAST)`);
   for (const b of rows) {
     console.log("");
     console.log(`  ${b.id}`);
@@ -1951,6 +1955,9 @@ export async function listRemote(orgId, opts = {}) {
     console.log(`    status ${b.status ?? "?"} · ${b.total_recipients ?? "?"} recipient(s)`);
   }
   console.log("");
+  if (resp.capped) {
+    console.log(`⚠ ${(resp.total - rows.length).toLocaleString()} older broadcast(s) not shown (limit ${resp.limit}). Narrow with --since, --template${resp.min_recipients ? "" : " or --min-recipients 2 (hides one-recipient sends like welcomes and cart reminders)"}.`);
+  }
   console.log(`Delivery detail: flowiq bc status ${orgId} <broadcast_id> [--failures]`);
 }
 
@@ -1984,6 +1991,15 @@ export async function status(orgId, broadcastId, opts = {}) {
   if (b.total_recipients) {
     console.log(`    ${((accepted / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients accepted${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
   }
+  const p = resp.payload;
+  if (p && (Object.keys(p.body_parameters || {}).length || Object.keys(p.button_parameters || {}).length || Object.keys(p.header_parameters || {}).length)) {
+    console.log(`  sent with:`);
+    const slot = (k) => String(k).replace(/^param/, "{{") + (String(k).startsWith("param") ? "}}" : "");
+    for (const [k, v] of Object.entries(p.header_parameters || {})) console.log(`    header ${slot(k)}  ${String(v).replace(/\s+/g, " ")}`);
+    for (const [k, v] of Object.entries(p.body_parameters || {})) console.log(`    body   ${slot(k)}  ${String(v).replace(/\s+/g, " ")}`);
+    for (const [k, v] of Object.entries(p.button_parameters || {})) console.log(`    button ${slot(k)}  ${v}`);
+    for (const l of p.links || []) console.log(`    link   ${l.short_code} → ${l.destination}  (${l.clicks} click${l.clicks === 1 ? "" : "s"})`);
+  }
   if (resp.reply_routing) {
     const rr = resp.reply_routing;
     console.log(`  replies →   ${describeRouting(rr)}${rr.enabled === false ? "  (switched OFF)" : ""}`);

package/src/commands/doctor.js

@@ -101,10 +101,19 @@ export async function doctor(opts = {}) {
       }
     } catch (e) {
       lines.push(`  ${BAD} auth       ${e.message.split("\n")[0]}`);
-      problems.push({
-        what: "the API rejected this key",
-        fix: e.status === 401 || e.status === 403 ? "flowiq auth login" : "check api_url / network, then retry",
-      });
+      if (e.code === "EVERCELCHALLENGE") {
+        problems.push({
+          what: "Vercel's bot protection is challenging this network; the key was never checked",
+          fix: "wait a few minutes or switch network (hotspot), then flowiq doctor again; do NOT re-login",
+        });
+      } else {
+        // Only a JSON 401/403 from our API means the key itself was refused.
+        const keyRefused = (e.status === 401 || e.status === 403) && e.code !== "ENONJSON";
+        problems.push({
+          what: keyRefused ? "the API rejected this key" : "the API could not be reached properly",
+          fix: keyRefused ? "flowiq auth login" : "check api_url / network, then retry",
+        });
+      }
     }
   }