@flowapt/flowiq-cli 0.1.11 → 0.1.12

package/README.md

@@ -137,6 +137,28 @@ flowiq knowledge list
 - **Object-shape guard:** some agents use `additional_config` for Flowapt-managed config (`external_woo_build`, …) rather than text sources — a pull flags that, and a push is **refused** (never clobbers managed config).
 - `--agent` + filenames behave like `prompts` (a non-active agent saves to `<org-slug>-<agent-slug>.json`). The file carries `agent_id`, so `push` targets the agent it was pulled from.
 
+### Custom tools — `flowiq custom-tools pull|push|enable|disable|list` (alias `ct`)
+
+Round-trips an agent's **custom tools** — the `agents.additional_tools` array
+of "any API call → tool" definitions (the "Custom Tools" panel in the UI:
+`get_more_answers`, CRM wrappers, loyalty tools, …). These define real HTTP
+calls the agent can execute, so treat pushes with care.
+
+```bash
+flowiq custom-tools pull <org_id>               # → ./.flowiq/custom-tools/<slug>.json (tools[])
+flowiq ct pull <org_id> --agent <id>            # a specific (non-active) agent
+flowiq ct push <slug> --dry-run                 # validate + per-tool diff, writes NOTHING
+flowiq ct push <slug>                            # FULL-REPLACE tools[] onto the agent
+flowiq ct enable <org_id> <tool_name>            # flip one tool on (no round-trip)
+flowiq ct disable <org_id> <tool_name>           # flip one tool off
+flowiq ct list
+```
+
+- **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
+- 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`. 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: `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `supabase_anon_key`, `openai_api_key`, …).
+- `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
+
 ### Messages — `flowiq messages pull <contact_id>` (alias `m`)
 
 Read-only pull of a contact's `helpdesk_messages` history. Anchors on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "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/custom-tools.js

@@ -0,0 +1,197 @@
+// `flowiq custom-tools pull <org_id> [--agent <id>]` / `push <slug> [--dry-run]`
+// / `enable|disable <org_id> <tool_name>` / `list`.
+// Round-trips an agent's CUSTOM TOOLS — the `agents.additional_tools` array of
+// "any API call → tool" definitions (get_more_answers, zoho_* wrappers, …).
+// Via /cli/custom-tools; no DB creds on disk.
+//
+// These define real HTTP calls the agent can execute, so push is validated
+// hard server-side and `--dry-run` prints the per-tool diff without writing.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const CT_DIR = path.resolve(process.cwd(), ".flowiq", "custom-tools");
+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 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; }
+}
+
+async function resolvePushPath(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) {
+    candidates.push(identifier);
+  } else if (identifier.includes("/") || identifier.includes("\\")) {
+    candidates.push(path.resolve(identifier));
+  } else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(CT_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) {
+    if (await fileExists(c)) return c;
+  }
+  throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+function printWarnings(warnings) {
+  for (const w of warnings || []) console.log(`  ⚠ ${w}`);
+}
+
+function printDiff(diff) {
+  if (!diff) return;
+  const parts = [];
+  if (diff.added?.length) parts.push(`+${diff.added.length} added (${diff.added.join(", ")})`);
+  if (diff.removed?.length) parts.push(`-${diff.removed.length} removed (${diff.removed.join(", ")})`);
+  if (diff.changed?.length) parts.push(`~${diff.changed.length} changed (${diff.changed.join(", ")})`);
+  parts.push(`${diff.unchanged ?? 0} unchanged`);
+  console.log(`  diff:      ${parts.join("; ")}`);
+}
+
+export async function pull(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("custom-tools", { organization_id: orgId, agent_id: opts.agent });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(CT_DIR, { recursive: true });
+  // Non-active agents get an agent-suffixed filename (same as prompts) so
+  // pulling multiple agents from one org doesn't clobber each other.
+  const orgSlug = slugify(resp.organization_name, resp.organization_id);
+  const slug = resp.is_active === false
+    ? `${orgSlug}-${slugify(resp.agent_name, resp.agent_id.slice(0, 8))}`
+    : orgSlug;
+  const filePath = path.join(CT_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  agent:     ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
+  console.log(`  tools:     ${resp.tool_count} (${resp.enabled_count} enabled)`);
+  for (const t of resp.tools || []) {
+    const flags = [
+      t.enabled === false ? "DISABLED" : null,
+      t.super_admin_only ? "super-admin" : null,
+      t.channels?.length ? `channels: ${t.channels.join(",")}` : null,
+    ].filter(Boolean).join(", ");
+    let host = t.endpoint;
+    try { host = new URL(t.endpoint).host; } catch { /* keep raw */ }
+    console.log(`    ${String(t.name).padEnd(32)} ${String(t.method || "?").padEnd(6)} ${host}${flags ? `  [${flags}]` : ""}`);
+  }
+}
+
+export async function push(identifier, opts = {}) {
+  let filePath;
+  try {
+    filePath = await resolvePushPath(identifier);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+  const raw = await fs.readFile(filePath, "utf8");
+  let data;
+  try { data = JSON.parse(raw); }
+  catch (e) {
+    console.error(`Invalid JSON in ${filePath}: ${e.message}`);
+    process.exit(1);
+  }
+  if (!data.organization_id || !UUID_RE.test(data.organization_id)) {
+    console.error(`${filePath}: organization_id missing or invalid`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data.tools)) {
+    console.error(`${filePath}: tools must be an array of tool definitions`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("custom-tools", {
+      organization_id: data.organization_id,
+      agent_id: data.agent_id, // push back to the agent this file was pulled from
+      tools: data.tools,
+      dry_run: !!opts.dryRun,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`${resp.dry_run ? "DRY RUN (nothing written) —" : "Pushed"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${data.organization_id})`);
+  console.log(`  agent:     ${resp.agent_name}${resp.is_active === false ? " [NON-active]" : ""}`);
+  console.log(`  tools:     ${resp.tool_count}`);
+  printDiff(resp.diff);
+  printWarnings(resp.warnings);
+  if (resp.dry_run) console.log("  re-run without --dry-run to apply.");
+}
+
+async function toggle(orgId, toolName, enabled, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("custom-tools", {
+      organization_id: orgId,
+      agent_id: opts.agent,
+      toggle: { name: toolName, enabled },
+    });
+  } catch (e) {
+    console.error(`${enabled ? "Enable" : "Disable"} failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+  console.log(`${enabled ? "Enabled" : "Disabled"} "${resp.name}" on ${resp.agent_name} (${resp.organization_name})${resp.is_active === false ? " [NON-active]" : ""}`);
+}
+
+export const enable = (orgId, toolName, opts) => toggle(orgId, toolName, true, opts);
+export const disable = (orgId, toolName, opts) => toggle(orgId, toolName, false, opts);
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(CT_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local custom-tools files; run `custom-tools pull <org_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local custom-tools files; run `custom-tools pull <org_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(CT_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(`  agent:     ${d.agent_name ?? "?"} (${d.agent_id ?? "?"})`);
+      console.log(`  tools:     ${d.tool_count ?? (Array.isArray(d.tools) ? d.tools.length : "?")}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/index.js

@@ -23,6 +23,7 @@ import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
+import * as customToolsCmd from "./commands/custom-tools.js";
 
 // Read version from package.json so it stays in sync with the published npm
 // version automatically (single source of truth — bumping package.json on each
@@ -310,5 +311,29 @@ export function run(argv) {
     .description("List local knowledge snapshots")
     .action(() => knowledgeCmd.list());
 
+  // custom-tools (agent custom tools: additional_tools — the "any API call → tool" defs)
+  const customTools = program.command("custom-tools")
+    .alias("ct")
+    .description("Round-trip an agent's CUSTOM TOOLS (additional_tools — the \"any API call → tool\" definitions)");
+  customTools.command("pull <organization_id>")
+    .description("Fetch the agent's custom tools into a local JSON file (default: active agent)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, opts) => customToolsCmd.pull(orgId, opts));
+  customTools.command("push <slug-or-path>")
+    .description("FULL-REPLACE the agent's custom tools with the local JSON's tools[] (validated server-side)")
+    .option("--dry-run", "validate + print the per-tool diff WITHOUT writing")
+    .action((id, opts) => customToolsCmd.push(id, opts));
+  customTools.command("enable <organization_id> <tool_name>")
+    .description("Enable one custom tool by name (no round-trip)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, name, opts) => customToolsCmd.enable(orgId, name, opts));
+  customTools.command("disable <organization_id> <tool_name>")
+    .description("Disable one custom tool by name (no round-trip)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, name, opts) => customToolsCmd.disable(orgId, name, opts));
+  customTools.command("list")
+    .description("List local custom-tools snapshots")
+    .action(() => customToolsCmd.list());
+
   program.parseAsync(argv);
 }