@pixelml/agenticflow-cli 1.6.2 → 1.6.4

package/README.md

@@ -32,10 +32,14 @@ af workforce init --blueprint dev-shop --name "My Dev Team" --json
 
 ## What you can build
 
-- **Single agents** — `af agent create/run/update/delete`, with `--patch` for surgical iteration
-- **Multi-agent workforces** — `af workforce init --blueprint <id>` deploys a runnable DAG (trigger → coordinator → workers → output) with real agents auto-created and wired up
-- **Workflows** — `af workflow create/run/run-status` for DAG-style workflow automation
-- **MCP tool integrations** — `af mcp-clients list/inspect` to audit + attach Google Docs/Sheets, Notion, Slack, GitHub, etc.
+| You want… | Use | Because |
+|---|---|---|
+| A single chat endpoint / customer-facing bot / one assistant | **`af agent create`** then `af agent run` | One prompt handles routing. Iterate with `af agent update --patch` |
+| Multiple agents that hand off (research → write, triage → specialist, dev shop, marketing agency, Amazon seller team, …) | **`af workforce init --blueprint <id>`** | Creates workforce + N agents + wired DAG in one command. Atomic rollback on failure |
+| A DAG of prompt/tool/logic nodes (not necessarily multi-agent) | **`af workflow create`** then `af workflow run` | Classic workflow engine |
+| Attach Google Docs/Sheets/Slack/Notion to an agent | **`af mcp-clients list/inspect`** then `af agent update --patch` | Inspect before attach to avoid Pipedream write-capability traps |
+
+Don't reach for a workforce when a single agent suffices — the 6 built-in workforce blueprints are for genuine multi-agent orchestration (dev-shop, marketing-agency, sales-team, content-studio, support-center, amazon-seller).
 
 ## Authentication
 

package/dist/cli/changelog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAoMrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAkOrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}

package/dist/cli/changelog.js

@@ -5,6 +5,36 @@
  * and displayed after upgrade.
  */
 export const CHANGELOG = [
+    {
+        version: "1.6.4",
+        date: "2026-04-14",
+        highlights: [
+            "`af bootstrap` now surfaces a `data_fresh` boolean and `data_fresh_hint` when the backend health check fails — empty `agents`/`workforces` arrays no longer look identical to 'workspace is empty'. Also added `auth.health_error` with the underlying fetch error message",
+            "`af bootstrap --strict` exits non-zero when backend health is false — use in CI to prevent downstream mutations against a degraded workspace",
+            "`af workforce list --name-contains <substr> --fields id,name --json` — same client-side filter + projection as `af agent list` and `af mcp-clients list`. Closes a documentation lie where the flag was advertised but not implemented",
+            "`af workforce init --blueprint --help` no longer references the deprecated `af paperclip blueprints` as the canonical list source. Points at `af bootstrap --json > blueprints[]` with inline slug names",
+            "README + CONTEXT.md + the gitbook-hosted `docs/09-developers/cli/` pages updated to v1.6 surface (native workforce lead, `--patch`, MCP inspect, paperclip deprecation notice, error-envelope shape)",
+        ],
+        for_ai: [
+            "After `af bootstrap --json`, check `data_fresh`. If false, the empty lists are UNVERIFIED — don't assume the workspace is empty. Fix network/auth before mutating",
+            "In CI, run `af bootstrap --strict` instead of the bare form — non-zero exit guards the rest of the pipeline",
+            "`af workforce list --fields id,name --name-contains <substr> --json` now works (was documented but broken in prior versions) — use it to find your own test workforces before bulk delete",
+        ],
+    },
+    {
+        version: "1.6.3",
+        date: "2026-04-14",
+        highlights: [
+            "`af schema agent --field suggested_messages` now shows the real shape: `array of { title, label, action }` (object, not strings). Previously the CLI doc said 'array of strings' and the server 422'd — verified against the AgenticFlow `AgentSuggestedMessage` pydantic model in workflow_chef",
+            "New agent-vs-workforce decision table added to README (top-of-page) + CONTEXT.md + `af context` invariants. A single customer-facing bot should be `af agent create` with rules in the system prompt — not a `support-center` workforce",
+            "`af playbook first-touch` STEP 2 fixed: no longer references `af paperclip blueprints` (was a stale leak from the v1.6.1 playbook pass). Points at `af bootstrap > blueprints[]` instead",
+        ],
+        for_ai: [
+            "If you need `suggested_messages` on an agent, each item is `{title: string, label: string, action: string}` — `title` shows as the button text, `action` is the message sent on click",
+            "DECISION HEURISTIC: one chat endpoint → `af agent create`. Multiple agents with hand-off → `af workforce init --blueprint <id>`. When in doubt, start with agent — you can always graduate to a workforce later",
+            "`af context --json` invariants now include the agent-vs-workforce choice explicitly — it used to over-rotate operators toward workforce",
+        ],
+    },
     {
         version: "1.6.2",
         date: "2026-04-14",

package/dist/cli/changelog.js.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAi8BpC,wBAAgB,aAAa,IAAI,OAAO,CA2gLvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAi8BpC,wBAAgB,aAAa,IAAI,OAAO,CA6iLvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}

package/dist/cli/main.js

@@ -830,7 +830,7 @@ export function createProgram() {
                     suggest_replies: "bool (default: true) — generate suggested follow-up replies",
                     auto_generate_title: "bool (default: true) — auto-title new threads",
                     welcome_message: "string — greeting on new thread",
-                    suggested_messages: "array of strings — pre-populated example prompts shown to users",
+                    suggested_messages: "array of { title: string, label: string, action: string } — pre-populated example prompts shown to users. `title` is the short display text; `label` is the sub-text; `action` is the message body sent on click. NOT an array of strings — server rejects strings",
                     sub_agents: "array — sub-agent configurations for agent teams",
                     plugins: "array — plugin configurations",
                 },
@@ -937,22 +937,28 @@ export function createProgram() {
     program
         .command("bootstrap")
         .description("Single-command AI agent setup: verify auth, list agents, return schemas. Combines context + doctor + schema + agent list.")
-        .action(async () => {
+        .option("--strict", "Exit non-zero when the backend health check fails. Useful in CI / for scripts that shouldn't proceed into a degraded workspace.")
+        .action(async (opts) => {
         // Combine everything an AI needs in one response
         const client = buildClient(program.opts());
         const token = resolveToken(program.opts());
         let health = false;
+        let healthError = null;
         let agents = [];
         try {
             const sdk = client.sdk;
             const resp = await sdk.get("/v1/health");
             health = resp.ok;
+            if (!resp.ok)
+                healthError = `HTTP ${resp.statusCode}`;
+        }
+        catch (err) {
+            healthError = err instanceof Error ? err.message : String(err);
         }
-        catch { /* unhealthy */ }
         try {
             agents = (await client.agents.list({ limit: 10 }));
         }
-        catch { /* no agents or unauth */ }
+        catch { /* no agents or unauth — list stays empty */ }
         // Workforces are the AgenticFlow-native multi-agent primitive. Fetch
         // the first 10 for the bootstrap snapshot. Tolerate failure (endpoint
         // may 404 in very old backends).
@@ -961,14 +967,24 @@ export function createProgram() {
             workforces = (await client.workforces.list({ limit: 10 }));
         }
         catch { /* no workforces or unauth */ }
+        // Annotate data-freshness so callers know whether the empty arrays mean
+        // "nothing there" or "couldn't verify because backend was unreachable".
+        // Matches codex-round-1 friction point F1 — previously an empty agents[]
+        // looked identical whether the workspace was empty or the API was down.
+        const dataFresh = health;
         printResult({
             schema: "agenticflow.bootstrap.v1",
             auth: {
                 authenticated: !!token,
                 health,
+                health_error: healthError,
                 workspace_id: client.sdk.workspaceId,
                 project_id: client.sdk.projectId,
             },
+            data_fresh: dataFresh,
+            data_fresh_hint: dataFresh
+                ? undefined
+                : "Backend unreachable — `agents`, `workforces`, and the `blueprints` array are the local/bundled shape only. Empty lists DO NOT mean 'nothing in your workspace'. Fix network/auth before mutating.",
             agents: Array.isArray(agents)
                 ? agents.slice(0, 10).map((a) => {
                     const ag = a;
@@ -1025,6 +1041,11 @@ export function createProgram() {
                 datasets: webUrl("datasets", { workspaceId: client.sdk.workspaceId }),
             },
         });
+        // --strict turns degraded-backend into a non-zero exit so CI / automation
+        // doesn't race ahead into mutations against an unreachable API.
+        if (opts.strict && !health) {
+            process.exit(1);
+        }
     });
     // ═════════════════════════════════════════════════════════════════
     // changelog
@@ -1065,9 +1086,10 @@ export function createProgram() {
                     "ALWAYS use --json for machine-readable output in automation",
                     "ALWAYS use --dry-run before mutating create/deploy commands you're not 100% sure about",
                     "ALWAYS use --fields on list commands (saves context window)",
+                    "CHOOSE agent vs workforce by orchestration need: single chat endpoint / one assistant → `af agent create`. Multiple agents with hand-off (research → write, triage → specialist, the 6 built-in blueprints) → `af workforce init --blueprint <id>`. Don't use a workforce for single-bot use cases",
                     "PREFER `af agent update --patch` over full-body PUT — preserves MCP clients + tools + code_exec while changing only the fields you supply",
-                    "PREFER `af workforce init --blueprint <id>` over wiring agents manually — one command = runnable team (v1.6+)",
-                    "USE `af schema <resource> --field <name>` to drill into nested payload shapes (e.g. mcp_clients, response_format) instead of guessing",
+                    "PREFER `af workforce init --blueprint <id>` over wiring a workforce's agents manually — one command creates workforce + agents + wired DAG (v1.6+)",
+                    "USE `af schema <resource> --field <name>` to drill into nested payload shapes (e.g. mcp_clients, suggested_messages, response_format) instead of guessing",
                     "BEFORE attaching an MCP client, run `af mcp-clients inspect --id <id>` — pattern=pipedream with write_capable_tools is likely to fail on execute. See `af playbook mcp-client-quirks`",
                     "ON errors, check `hint` and `details.payload` — the CLI tells you exactly what to fix before you retry",
                     "NEVER hard-code IDs — fetch dynamically via list/get",
@@ -4293,13 +4315,26 @@ export function createProgram() {
         .option("--workspace-id <id>", "Workspace ID (overrides env)")
         .option("--limit <n>", "Limit")
         .option("--offset <n>", "Offset")
+        .option("--name-contains <substr>", "Client-side case-insensitive substring filter on workforce `name`.")
+        .option("--fields <fields>", "Comma-separated fields to return (e.g. id,name,is_public). Applies after --name-contains.")
         .action(async (opts) => {
         const client = buildClient(program.opts());
-        await run(() => client.workforces.list({
-            workspaceId: opts.workspaceId,
-            limit: parseOptionalInteger(opts.limit, "--limit", 1),
-            offset: parseOptionalInteger(opts.offset, "--offset", 0),
-        }));
+        await run(async () => {
+            const rows = await client.workforces.list({
+                workspaceId: opts.workspaceId,
+                limit: parseOptionalInteger(opts.limit, "--limit", 1),
+                offset: parseOptionalInteger(opts.offset, "--offset", 0),
+            });
+            let out = rows;
+            const needle = opts.nameContains?.toLowerCase();
+            if (needle && Array.isArray(out)) {
+                out = out.filter((r) => {
+                    const n = r["name"];
+                    return typeof n === "string" && n.toLowerCase().includes(needle);
+                });
+            }
+            return applyFieldsFilter(out, opts.fields);
+        });
     });
     workforceCmd
         .command("get")
@@ -4628,7 +4663,7 @@ export function createProgram() {
         "(v1.6+): creates a real agent per non-optional blueprint slot, then wires " +
         "them into a runnable DAG. Use --skeleton-only for the old v1.5 behavior " +
         "(trigger + output + blueprint metadata, no agents).")
-        .requiredOption("--blueprint <slug>", "Blueprint id (run `af paperclip blueprints` to list)")
+        .requiredOption("--blueprint <slug>", "Blueprint id. See `af bootstrap --json > blueprints[]` for available ids (dev-shop, marketing-agency, sales-team, content-studio, support-center, amazon-seller).")
         .option("--name <name>", "Workforce name (defaults to blueprint name)")
         .option("--workspace-id <id>", "Workspace ID (overrides env)")
         .option("--project-id <id>", "Project ID to use for agent creation (defaults to env / client config)")