@pixelml/agenticflow-cli 1.5.1 → 1.5.2

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,EAmHrC,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,EAsIrC,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,25 @@
  * and displayed after upgrade.
  */
 export const CHANGELOG = [
+    {
+        version: "1.5.2",
+        date: "2026-04-14",
+        highlights: [
+            "`af workforce run --trigger-data '{...}'` now auto-wraps in the server's required `{trigger_data: ...}` envelope. Previously you had to pass `{\"trigger_data\":{\"topic\":\"AI\"}}` which felt like a CLI bug. Explicit wrapping still works (pass-through)",
+            "`af workforce delete` returns the consistent `agenticflow.delete.v1` envelope instead of bare `null`. Scripts now get the same shape as `af agent delete`",
+            "`af mcp-clients list --name-contains <substr> --fields id,name` — same filter + projection flags as `af agent list`. Essential for workspaces with dozens of MCP clients",
+            "`af mcp-clients inspect` surfaces the underlying `fetch_error` + `classification_reason` when tools can't be enumerated. Stops returning a misleading `pattern: unknown` that callers might treat as 'safe to attach'",
+            "`af schema <resource> --field <name>` now resolves against top-level schema keys too (not just create.optional). Lets you drill into `schema`, `update`, `stream` subtrees — e.g. `af schema workforce --field schema --json` returns the node_shape + edge_shape + agent_node_input docs",
+            "`af schema agent` clarifies that `project_id` is REQUIRED on create (server does NOT auto-inject for agents, unlike workforces). Separates the contract per resource",
+        ],
+        for_ai: [
+            "When you hit a 422 `body.trigger_data missing` on `workforce run`, upgrade to 1.5.2 — the CLI now auto-wraps",
+            "If `mcp-clients inspect` returns `classification_reason: 'fetch_failed'` or `'unauthenticated'`, DO NOT attach that client to an agent — re-auth in the web UI first",
+            "Filter MCP clients with `af mcp-clients list --name-contains 'google docs' --fields id,name --json` — no more grep-piping",
+            "Drill into any schema subtree: `af schema workforce --field schema --json` returns graph shape; `af schema agent --field mcp_clients --json` returns attach shape",
+            "Consistent delete envelope: every `af <resource> delete` returns `{schema:'agenticflow.delete.v1', deleted:true, id, resource}` on success",
+        ],
+    },
     {
         version: "1.5.1",
         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":"AAAA;;;;;GAKG;AASH,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,gSAAgS;YAChS,0HAA0H;YAC1H,2KAA2K;YAC3K,sSAAsS;YACtS,wOAAwO;YACxO,yLAAyL;SAC1L;QACD,MAAM,EAAE;YACN,0UAA0U;YAC1U,+IAA+I;YAC/I,4IAA4I;YAC5I,mKAAmK;SACpK;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,iKAAiK;YACjK,mIAAmI;YACnI,4JAA4J;YAC5J,qJAAqJ;YACrJ,8GAA8G;YAC9G,yGAAyG;SAC1G;QACD,MAAM,EAAE;YACN,mMAAmM;YACnM,wLAAwL;YACxL,wGAAwG;YACxG,gGAAgG;YAChG,iIAAiI;YACjI,oIAAoI;SACrI;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,2GAA2G;YAC3G,+MAA+M;YAC/M,2LAA2L;YAC3L,kJAAkJ;YAClJ,2GAA2G;YAC3G,2GAA2G;YAC3G,iKAAiK;YACjK,kHAAkH;YAClH,uHAAuH;SACxH;QACD,MAAM,EAAE;YACN,6LAA6L;YAC7L,uLAAuL;YACvL,4PAA4P;YAC5P,+JAA+J;YAC/J,2GAA2G;SAC5G;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,uEAAuE;YACvE,mFAAmF;YACnF,yFAAyF;YACzF,gFAAgF;YAChF,kEAAkE;YAClE,uFAAuF;YACvF,iEAAiE;YACjE,uEAAuE;YACvE,yDAAyD;YACzD,wDAAwD;YACxD,6EAA6E;YAC7E,6GAA6G;SAC9G;QACD,MAAM,EAAE;YACN,6FAA6F;YAC7F,+GAA+G;YAC/G,qFAAqF;YACrF,6EAA6E;YAC7E,qEAAqE;YACrE,oHAAoH;YACpH,wGAAwG;YACxG,mGAAmG;SACpG;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,gEAAgE;YAChE,uEAAuE;YACvE,mDAAmD;YACnD,4CAA4C;SAC7C;QACD,MAAM,EAAE;YACN,6CAA6C;YAC7C,6DAA6D;SAC9D;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,kCAAkC;YAClC,6CAA6C;YAC7C,qCAAqC;SACtC;QACD,MAAM,EAAE;YACN,0CAA0C;SAC3C;KACF;CACF,CAAC;AAEF,MAAM,UAAU,kBAAkB;IAChC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC9D,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC"}
+{"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;AAy4BpC,wBAAgB,aAAa,IAAI,OAAO,CAwvKvC;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;AAy4BpC,wBAAgB,aAAa,IAAI,OAAO,CA81KvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}

package/dist/cli/main.js

@@ -758,6 +758,7 @@ export function createProgram() {
     const SCHEMAS = {
         agent: {
             resource: "agent",
+            note: "`project_id` is REQUIRED in the body on agent create (server does NOT auto-inject from client config, unlike workforces). The CLI's local validator enforces this — grab the value from `af bootstrap --json > auth.project_id`. The `workspace_id` scoping is handled server-side via API key.",
             create: {
                 required: ["name", "tools", "project_id"],
                 optional: {
@@ -1094,39 +1095,59 @@ export function createProgram() {
         if (!schema) {
             fail("schema_not_found", `Unknown resource: ${resource}`, `Available: ${Object.keys(SCHEMAS).join(", ")}`);
         }
-        // Field drilldown: return just the docs for one field
+        // Field drilldown: resolve `--field X` against multiple schema locations.
+        // We look in this order: top-level sibling key (e.g. `schema`, `update`,
+        // `stream`), then create.required, then create.optional. This lets the
+        // drilldown return rich subtree docs (like `schema` node/edge shapes on
+        // the workforce resource) rather than "not found".
         if (opts?.field) {
             const fieldName = opts.field;
             const s = schema;
-            const create = s.create ?? {};
-            const required = create.required ?? [];
-            const optional = create.optional ?? {};
             let doc = null;
+            let location = null;
             let isRequired = false;
-            if (required.includes(fieldName)) {
-                doc = "required";
-                isRequired = true;
+            if (fieldName in s && fieldName !== "resource" && fieldName !== "fields") {
+                doc = s[fieldName];
+                location = "top_level";
             }
-            if (fieldName in optional)
-                doc = optional[fieldName] ?? null;
+            else {
+                const create = s.create ?? {};
+                const required = create.required ?? [];
+                const optional = create.optional ?? {};
+                if (required.includes(fieldName)) {
+                    doc = "required";
+                    isRequired = true;
+                    location = "create.required";
+                }
+                else if (fieldName in optional) {
+                    doc = optional[fieldName] ?? null;
+                    location = "create.optional";
+                }
+            }
+            const found = doc !== null && doc !== undefined;
             const result = {
                 schema: "agenticflow.schema.field.v1",
                 resource: s.resource,
                 field: fieldName,
                 required: isRequired,
+                location,
                 doc,
-                found: doc !== null,
-                hint: doc === null
-                    ? `Field '${fieldName}' has no documented shape in the static schema. For live introspection, fetch an existing instance via 'af ${s.resource} get --${s.resource}-id <id> --json' and inspect the returned value for that field.`
+                found,
+                hint: !found
+                    ? `Field '${fieldName}' has no documented shape in the static schema. Candidates: top-level keys (${Object.keys(s).filter((k) => !["resource", "fields"].includes(k)).join(", ")}); create.required; create.optional. For live introspection, fetch an existing instance via 'af ${s.resource} get --${s.resource}-id <id> --json' and inspect the returned value for that field.`
                     : undefined,
             };
             if (isJsonFlagEnabled()) {
                 printResult(result);
             }
             else {
-                console.log(`${s.resource}.${fieldName}${isRequired ? " (required)" : " (optional)"}`);
-                if (doc)
+                console.log(`${s.resource}.${fieldName}${isRequired ? " (required)" : ""}${location ? ` [${location}]` : ""}`);
+                if (typeof doc === "string") {
                     console.log(`  ${doc}`);
+                }
+                else if (doc !== null && doc !== undefined) {
+                    console.log(JSON.stringify(doc, null, 2).split("\n").map((l) => "  " + l).join("\n"));
+                }
                 if (result.hint)
                     console.log(`  ${result.hint}`);
             }
@@ -4040,28 +4061,54 @@ export function createProgram() {
         .option("--project-id <id>", "Project ID")
         .option("--limit <n>", "Limit")
         .option("--offset <n>", "Offset")
+        .option("--name-contains <substr>", "Client-side case-insensitive substring filter on client `name`. Essential in busy workspaces with dozens of MCP clients.")
+        .option("--fields <fields>", "Comma-separated fields to return (e.g. id,name,is_authenticated). Applies after --name-contains filter.")
         .option("--verify-auth", "Reconcile is_authenticated by calling `get` for each client — slower " +
         "but catches the case where list() reports auth=true but get() reveals " +
         "the underlying provider session is expired. N+1 call; use sparingly.")
         .action(async (opts) => {
         const client = buildClient(program.opts());
+        // Helper: apply client-side name filter + fields projection to a list response
+        const postFilter = (rows) => {
+            let out = rows;
+            const nameContains = opts.nameContains;
+            if (nameContains && Array.isArray(out)) {
+                const needle = nameContains.toLowerCase();
+                out = out.filter((r) => {
+                    const n = r["name"];
+                    return typeof n === "string" && n.toLowerCase().includes(needle);
+                });
+            }
+            return applyFieldsFilter(out, opts.fields);
+        };
         if (!opts.verifyAuth) {
-            await run(() => client.mcpClients.list({
-                workspaceId: opts.workspaceId,
-                projectId: opts.projectId,
-                limit: parseOptionalInteger(opts.limit, "--limit", 1),
-                offset: parseOptionalInteger(opts.offset, "--offset", 0),
-            }));
+            await run(async () => {
+                const rows = await client.mcpClients.list({
+                    workspaceId: opts.workspaceId,
+                    projectId: opts.projectId,
+                    limit: parseOptionalInteger(opts.limit, "--limit", 1),
+                    offset: parseOptionalInteger(opts.offset, "--offset", 0),
+                });
+                return postFilter(rows);
+            });
             return;
         }
-        // --verify-auth: list, then re-check each row's auth via get()
+        // --verify-auth: list, filter, then re-check each remaining row's auth via get()
         await run(async () => {
-            const rows = (await client.mcpClients.list({
+            let rows = (await client.mcpClients.list({
                 workspaceId: opts.workspaceId,
                 projectId: opts.projectId,
                 limit: parseOptionalInteger(opts.limit, "--limit", 1),
                 offset: parseOptionalInteger(opts.offset, "--offset", 0),
             }));
+            const nameContains = opts.nameContains;
+            if (nameContains) {
+                const needle = nameContains.toLowerCase();
+                rows = rows.filter((r) => {
+                    const n = r["name"];
+                    return typeof n === "string" && n.toLowerCase().includes(needle);
+                });
+            }
             const verified = await Promise.all(rows.map(async (row) => {
                 const id = row["id"];
                 if (!id)
@@ -4079,7 +4126,7 @@ export function createProgram() {
                     return { ...row, verified_auth_error: err instanceof Error ? err.message : String(err) };
                 }
             }));
-            return verified;
+            return applyFieldsFilter(verified, opts.fields);
         });
     });
     mcpClientsCmd
@@ -4118,16 +4165,38 @@ export function createProgram() {
                     ? (toolsBox.tools)
                     : [];
             const report = inspectMcpToolsPattern(tools);
+            // Surface the underlying fetch/auth error when the tools list couldn't
+            // be enumerated — previously we silently returned pattern="unknown",
+            // which callers mistook for "safe to attach." Now the `fetch_error`
+            // + `classification_reason` make the failure explicit.
+            const fetchError = raw["error"];
+            const isAuth = raw["is_authenticated"];
+            const classification_reason = tools.length > 0
+                ? "tools_enumerated"
+                : fetchError
+                    ? "fetch_failed"
+                    : isAuth === false
+                        ? "unauthenticated"
+                        : "unknown";
+            const additional_quirks = [...report.quirks];
+            if (tools.length === 0 && (fetchError || isAuth === false)) {
+                additional_quirks.unshift(`Cannot classify this MCP client's tools — ${classification_reason}. ` +
+                    (fetchError ? `Server reported: ${fetchError}. ` : "") +
+                    `Do NOT attach this client to an agent until the underlying issue is resolved. ` +
+                    `Re-auth via the AgenticFlow web UI (workspaces/<ws>/mcp/${clientId}).`);
+            }
             return {
                 schema: "agenticflow.mcp_client.inspect.v1",
                 client_id: clientId,
                 client_name: raw["name"] ?? null,
-                is_authenticated: raw["is_authenticated"] ?? null,
+                is_authenticated: isAuth ?? null,
                 tool_count: tools.length,
                 pattern: report.pattern, // "pipedream" | "composio" | "mixed" | "unknown"
+                classification_reason,
+                fetch_error: fetchError ?? null,
                 write_capable_tools: report.writeCapable,
                 pipedream_instruction_only_tools: report.pipedreamTools,
-                known_quirks: report.quirks,
+                known_quirks: additional_quirks,
                 playbook: "af playbook mcp-client-quirks",
             };
         });
@@ -4216,7 +4285,21 @@ export function createProgram() {
         .option("--workspace-id <id>", "Workspace ID (overrides env)")
         .action(async (opts) => {
         const client = buildClient(program.opts());
-        await run(() => client.workforces.delete(opts.workforceId, { workspaceId: opts.workspaceId }));
+        try {
+            await client.workforces.delete(opts.workforceId, { workspaceId: opts.workspaceId });
+            // Server returns 204/null on success — wrap in the same delete envelope
+            // that `af agent delete` uses so scripts get a consistent shape.
+            printResult({
+                schema: "agenticflow.delete.v1",
+                deleted: true,
+                id: opts.workforceId,
+                resource: "workforce",
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            fail("request_failed", message);
+        }
     });
     workforceCmd
         .command("schema")
@@ -4275,13 +4358,24 @@ export function createProgram() {
         .description("Execute a workforce. Streams SSE events — each event prints as one JSON line. " +
         "Exits when the stream closes.")
         .requiredOption("--workforce-id <id>", "Workforce ID")
-        .option("--trigger-data <json>", "Trigger data (inline JSON or @file)", "{}")
+        .option("--trigger-data <json>", "Trigger input as inline JSON or @file. Pass the data your trigger node expects " +
+        "(e.g. `{\"topic\":\"AI\"}`) — the CLI automatically wraps it in the server's " +
+        "required `{trigger_data: ...}` envelope. If you pass `{\"trigger_data\":{...}}` " +
+        "explicitly, it's left as-is.", "{}")
         .option("--workspace-id <id>", "Workspace ID (overrides env)")
         .action(async (opts) => {
         const client = buildClient(program.opts());
-        const triggerData = loadJsonPayload(opts.triggerData);
+        const raw = loadJsonPayload(opts.triggerData);
+        // Server accepts `{trigger_data: {...}}`. If the caller already wrapped
+        // it (explicitly nested under trigger_data), pass through. Otherwise,
+        // wrap the user's payload. This is the ergonomics fix for friction S6 —
+        // previously passing `{topic:"..."}` returned `422: body.trigger_data
+        // missing` which looked like a CLI bug, not a payload shape bug.
+        const triggerBody = "trigger_data" in raw && typeof raw["trigger_data"] === "object" && raw["trigger_data"] !== null
+            ? raw
+            : { trigger_data: raw };
         try {
-            const response = await client.workforces.run(opts.workforceId, triggerData, {
+            const response = await client.workforces.run(opts.workforceId, triggerBody, {
                 workspaceId: opts.workspaceId,
             });
             if (!response.ok) {