@flowapt/flowiq-cli 0.6.5 → 0.6.7

package/README.md

@@ -187,8 +187,8 @@ flowiq ct list
 
 - **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
 - **Destructive pushes are blocked by default**: a push that removes a tool, disables one, or sends an empty `tools[]` (wiping everything) writes nothing and shows you exactly what it would strip — re-run with `--confirm` if intentional. Additive/no-op pushes are unaffected.
-- Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Recursive JSON schemas are supported, including arrays of objects and integer/min/max constraints. Bad payloads are rejected before anything writes.
-- **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime; known values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `supabase_anon_key`, `openai_api_key`).
+- Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates or built-in collisions), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, scalar headers, object-typed `parameters`/`injected_parameters`, valid auth/channels, timeout and response caps. Recursive schemas support strict nested objects, typed arrays, enums and numeric/string/item limits. Unknown tool/schema keys are rejected before anything writes.
+- **Warnings (non-blocking):** an object with properties but no required fields. Unknown `{{placeholder}}` values are hard errors; injected parameters may additionally reference a declared top-level model parameter. Known runtime values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `text`, `unique_message_id`, `unix_timestamp`, `operation_idempotency_key`, `supabase_anon_key`, and `openai_api_key`.
 - **Retailer gateway credential:** `{{retailer_tools_internal_key}}` is super-admin-only and resolves only as the `x-api-key` value for `https://express.chatcart.io/retailer-tools/*` (or loopback in local tests). Validation and runtime both reject putting it in a body or sending it to any other host.
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
 
@@ -1227,6 +1227,8 @@ flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.6-luna
   --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
 flowiq agent config <organization_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"
 flowiq agent config <organization_id> --model gpt-5.6-luna --reasoning-effort high
+flowiq agent config <organization_id> --disable-base-tool get_product_info
+flowiq agent config <organization_id> --enable-base-tool get_product_info
 ```
 
 Settable: `settings.use_settings_prompt`, `settings.model`,
@@ -1240,6 +1242,10 @@ the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
 
+`--disable-base-tool` / `--enable-base-tool` can be repeated. They manage only the
+allowlisted discovery/commerce built-ins; opt-out, human handover and channel-send
+tools cannot be disabled.
+
 **`--tool product_lookup=true` (added 11 Aug 2026).** Turns on the `product_lookup`
 tool: a typo-tolerant **pg_trgm fuzzy match on `product_title`** (plus badge/tag
 search), as opposed to `get_product_info`, which is **semantic**. This matters far
@@ -1327,6 +1333,22 @@ flowiq test cleanup <organization_id> --confirm      # delete the stress contact
 `--agent <id>` targets a specific (non-active) agent. `test stress cleanup` is
 destructive and requires `--confirm`.
 
+**Scenario pack shape.** `{scenarios:[{id, title, turns:[{text, expect?, expectNot?}]}]}`.
+`expect` / `expectNot` are case-insensitive substring checks (informational —
+reported and summed, never a hard fail) and accept **either a single string or an
+array of strings**:
+
+```json
+{ "text": "What investment options do I have?",
+  "expect": "depend on your fund rules",
+  "expectNot": ["Destiny offers", "guaranteed return"] }
+```
+
+Before v0.6.7 a bare string was iterated character by character, so
+`"expect": "fund rules"` reported ten single-letter checks that all trivially
+passed — a wrong pass/fail signal that still looked like a real result. Write
+either form now.
+
 ### Guide — `flowiq guide`
 
 Read the bundled docs in the terminal — no digging through node_modules.
@@ -1378,3 +1400,8 @@ interactive terminal. Silence it with `FLOWIQ_NO_UPDATE_CHECK=1`.
 
 UNLICENSED. Internal staff tool — install requires a valid `fiq_staff_…`
 key issued by a FlowIQ super-admin.
+
+ChatCart rollout: Pick n Pay uses retailer `pnp` and the private connection link.
+Enable its gateway before adding it to the agent tools. Cart retries use
+`{{operation_idempotency_key}}`; configure `timeout_ms` up to 30000 and
+`max_response_bytes` up to 1048576 for bounded batch results.

package/TEAM-GUIDE.md

@@ -98,10 +98,12 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` — a new agent arrives ready to work (gpt-5.6-luna, high reasoning, prompt switched ON); no follow-up `agent config` needed |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Set the house model + reasoning tier | `flowiq agent config <org_id> --model gpt-5.6-luna --reasoning-effort high` |
+| Remove a conflicting built-in tool from one agent | `flowiq agent config <org_id> --disable-base-tool get_product_info` (repeatable; safety/delivery tools cannot be disabled) |
 | Agent says an in-stock product "isn't showing" | `flowiq agent config <org_id> --tool collapse_product_variants=true` — the search cap counts VARIANT rows until this is on |
 | Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
+| Prove a batch of fixes actually landed, in one run | `flowiq test scenario <org_id> ./pack.json` — pack is `{scenarios:[{id,title,turns:[{text,expect?,expectNot?}]}]}`. `expect`/`expectNot` are case-insensitive substring checks and take **a single string OR an array**. (Before v0.6.7 a bare string was checked letter by letter, so it always "passed" — if you wrote packs on an older version, re-run them.) |
 | **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign 13Aug_Seeds --content 13Aug_Seeds` (dry run) → `… --commit`. `utm_source`/`utm_medium` are set for you; campaign + content must be given together |
 | Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
 | Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
@@ -179,12 +181,15 @@ flowiq ct push <slug>
 ```
 
 Custom tools define real HTTP calls the agent can execute, so the server
-validates hard (names, URLs, methods, parameter shapes) and warns about typo'd
-keys or `{{placeholders}}` it doesn't recognise. Take the warnings seriously.
-Nested object/array schemas are supported. For ChatCart retailer tools, use
+validates names, URLs, methods and parameter shapes. Unknown keys and unresolved
+`{{placeholders}}` block the write; an
+object with no required fields remains a warning because it can be intentional.
+Nested object/array schemas are strict and supported. For ChatCart retailer tools, use
 `{{retailer_tools_internal_key}}` only as the `x-api-key` auth value on the
 trusted `express.chatcart.io/retailer-tools/*` gateway; org/contact identity is
-injected server-side and mutations use `{{whatsapp_message_id}}` for idempotency.
+injected server-side and mutations use `{{operation_idempotency_key}}` for stable,
+operation-scoped idempotency. Batch independent product requests in one
+`search_retailer_products.queries` array (1–12) instead of repeated search calls.
 
 ### Example: tag a segment of contacts (Advanced Tagging)
 
@@ -325,3 +330,8 @@ Three things worth knowing:
 | "Organization has no active_whatsapp_agent" | Target the agent directly: `--agent <id>` (ids from `flowiq agent list <org_id>`) |
 | Login browser page says the code expired | Codes live 10 minutes — just re-run `flowiq auth login` |
 | Pushed the wrong thing | Everything is pull→push, so re-pull an older copy if you have one, or check with Matt — server logs record every push with who/what/when |
+
+ChatCart rollout: Pick n Pay uses retailer `pnp` and the private connection link.
+Enable its gateway before adding it to the agent tools. Cart retries use
+`{{operation_idempotency_key}}`; configure `timeout_ms` up to 30000 and
+`max_response_bytes` up to 1048576 for bounded batch results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.6.5",
+  "version": "0.6.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": {

package/src/commands/agent-config.js

@@ -23,6 +23,12 @@ export function collectTool(val, acc) {
   return acc;
 }
 
+export function collectToolName(val, acc) {
+  acc = acc || [];
+  acc.push(val);
+  return acc;
+}
+
 function printSnapshot(title, snap) {
   console.log(`  ${title}:`);
   for (const [k, v] of Object.entries(snap)) {
@@ -47,6 +53,12 @@ export async function config(orgId, opts = {}) {
   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.disableBaseTool?.length || opts.enableBaseTool?.length) {
+    body.base_tool_changes = {
+      disable: opts.disableBaseTool || [],
+      enable: opts.enableBaseTool || [],
+    };
+  }
 
   if (opts.tool && opts.tool.length) {
     const flags = {};
@@ -63,7 +75,7 @@ export async function config(orgId, opts = {}) {
   }
 
   const hasWrite =
-    body.settings || body.name !== undefined || body.tool_flags || body.discount_enabled !== undefined;
+    body.settings || body.name !== undefined || body.tool_flags || body.base_tool_changes || body.discount_enabled !== undefined;
 
   // No write flags → just show current config.
   if (!hasWrite) {
@@ -76,7 +88,7 @@ export async function config(orgId, opts = {}) {
     }
     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 / --discount / --test-contact-number / --test-contact-name to change)");
+    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)");
     return;
   }
 

package/src/commands/agent-test.js

@@ -45,11 +45,21 @@ async function clearConv(orgId, agent) {
   return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent });
 }
 
+// A bare string is ONE needle, not a list of characters. Iterating a string
+// with for..of yields its characters, so a pack written as
+// `"expect": "fund rules"` used to report ten single-letter checks that all
+// trivially passed (and, for expectNot, all trivially failed) — a wrong
+// pass/fail signal that still looked like a real result.
+function needles(v) {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
 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()) });
+  for (const e of needles(turn.expect)) results.push({ kind: "expect", needle: e, ok: hay.includes(String(e).toLowerCase()) });
+  for (const e of needles(turn.expectNot)) results.push({ kind: "expectNot", needle: e, ok: !hay.includes(String(e).toLowerCase()) });
   return results;
 }
 

package/src/index.js

@@ -328,6 +328,8 @@ export function run(argv) {
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
     .option("--test-contact-number <number>", "settings.test_contact_number — the contact `flowiq test` uses (use a FAKE number; \"\" clears it → synthetic fallback)")
     .option("--test-contact-name <name>", "settings.test_contact_name — display name for the test contact (\"\" clears it)")
+    .option("--disable-base-tool <name>", "hide a disableable built-in tool from this agent (repeatable)", agentConfigCmd.collectToolName, [])
+    .option("--enable-base-tool <name>", "restore a previously disabled built-in tool (repeatable)", agentConfigCmd.collectToolName, [])
     .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
 
   // agent-updates (pending client change-requests + chat context; pull + resolve)