@pixelml/agenticflow-cli 1.5.1 → 1.5.3

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,EAoJrC,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,39 @@
  * and displayed after upgrade.
  */
 export const CHANGELOG = [
+    {
+        version: "1.5.3",
+        date: "2026-04-14",
+        highlights: [
+            "Model preflight on `af agent create/update` — invalid model strings (typos, missing slash) fail fast BEFORE the agent gets created with a broken config. Unknown-but-plausible models warn but proceed (so new models work between CLI releases)",
+            "Structured error hints on 401/403/404/409/422/429 — every common HTTP failure now carries an actionable `hint` in --json output pointing at the right recovery command (`af whoami`, `af agent list`, fetch-and-reconcile, etc.)",
+            "`af agent update` emits a stderr `[info]` line naming which null-valued fields got auto-stripped. Closes the footgun where bots thought they'd cleared a field but the server never saw null. Silenced with --json (keeps stdout clean for piping)",
+        ],
+        for_ai: [
+            "If you're iterating on an agent's system prompt with `--patch`, don't also clear optional fields by sending null — the CLI strips them and the stderr info line tells you which ones were dropped",
+            "When a command fails, check the `hint` field in the error envelope before retrying — 404s point you at the matching `list` command, 422s point you at `details.payload` for field-level errors",
+            "Pass only models from `af bootstrap --json > models[]` — typos fail at validation time, not at next `agent run`. If you're trying a brand-new model and hit a warning, you can proceed (CLI is conservative — warns but doesn't block)",
+        ],
+    },
+    {
+        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;AAi8BpC,wBAAgB,aAAa,IAAI,OAAO,CAs2KvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}

package/dist/cli/main.js

@@ -17,9 +17,10 @@ import { LinearConnector } from "./gateway/connectors/linear.js";
 import { WebhookConnector } from "./gateway/connectors/webhook.js";
 import { listBlueprints, getBlueprint } from "./company-blueprints.js";
 import { CHANGELOG, getLatestChangelog } from "./changelog.js";
-import { stripNullFields } from "./utils/patch.js";
+import { stripNullFields, AGENT_UPDATE_STRIP_NULL_FIELDS } from "./utils/patch.js";
 import { inspectMcpToolsPattern } from "./utils/mcp-inspect.js";
 import { emitDeprecation } from "./utils/deprecation.js";
+import { validateModel } from "./utils/models.js";
 import { OperationRegistry, defaultSpecPath, loadOpenapiSpec, isPublic, } from "./spec.js";
 import { listPlaybooks, getPlaybook } from "./playbooks.js";
 import { loadPolicy, writeDefaultPolicy, policyFilePath, } from "./policy.js";
@@ -438,6 +439,19 @@ function buildClient(parentOpts) {
         projectId: resolveProjectId(parentOpts.projectId),
     });
 }
+/**
+ * Map of HTTP status codes to actionable hints AI operators can follow without
+ * additional context. Keeps error responses useful when the server's error
+ * message is terse (e.g. "Agent not found" with no follow-up).
+ */
+const STATUS_HINT_MAP = {
+    401: "Authentication failed. Run `af whoami` to check current auth, or `af login --api-key <key>` to refresh.",
+    403: "You don't have permission for this operation. Check the resource's workspace/project or your API key's scopes.",
+    404: "Resource not found. Run the matching `list` command (e.g. `af agent list --json`) to see available IDs, or double-check the ID you passed.",
+    409: "Conflict — the resource state disagrees with your request. Fetch the current state with `get` and reconcile before retrying.",
+    422: "Validation failed. Check `details.payload` for the specific field errors — pydantic returns a list with field name + expected type per issue.",
+    429: "Rate limited. Back off and retry with exponential delay.",
+};
 /** Wrap an async SDK call with error handling. */
 async function run(fn) {
     try {
@@ -458,11 +472,47 @@ async function run(fn) {
                 details["request_id"] = err.requestId;
             if (err.payload !== null && err.payload !== undefined)
                 details["payload"] = err.payload;
-            fail("request_failed", message, undefined, details);
+            const hint = STATUS_HINT_MAP[err.statusCode];
+            fail("request_failed", message, hint, details);
         }
         fail("request_failed", message);
     }
 }
+/**
+ * Validate the `model` field on an agent create/update payload, if present.
+ * Fail-fast on implausible strings; warn (stderr) on plausible-but-unknown
+ * strings so new models work without CLI updates.
+ */
+function preflightModel(payload, context) {
+    if (!("model" in payload))
+        return;
+    const res = validateModel(payload["model"]);
+    if (!res.valid) {
+        fail("invalid_option_value", `Invalid model in ${context}: ${String(payload["model"])}.`, res.suggestion);
+    }
+    if (!res.known && res.suggestion && !isJsonFlagEnabled()) {
+        console.error(`[warn] ${res.suggestion}`);
+    }
+}
+/**
+ * Report which keys got stripped by stripNullFields() so callers don't think
+ * they successfully cleared a field when the CLI silently dropped it.
+ * Emitted to stderr only (keeps stdout JSON clean for piping).
+ */
+function warnOnStrippedNulls(original, stripped) {
+    if (isJsonFlagEnabled())
+        return; // don't pollute stderr on bot-driven runs
+    const dropped = [];
+    for (const key of AGENT_UPDATE_STRIP_NULL_FIELDS) {
+        if (key in original && original[key] === null && !(key in stripped)) {
+            dropped.push(key);
+        }
+    }
+    if (dropped.length > 0) {
+        console.error(`[info] Stripped ${dropped.length} null-valued field(s) the server rejects on update: ${dropped.join(", ")}. ` +
+            "This is expected — server-required shape. See `af schema agent --field update --json` for the full list.");
+    }
+}
 // ═══════════════════════════════════════════════════════════════════
 // Spec-based helpers (for generic commands: call, ops, catalog, doctor)
 // ═══════════════════════════════════════════════════════════════════
@@ -758,6 +808,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 +1145,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}`);
             }
@@ -3466,6 +3537,7 @@ export function createProgram() {
         const body = loadJsonPayload(opts.body);
         hardenInput(JSON.stringify(body), "agent create body");
         ensureLocalValidation("agent.create", validateAgentCreatePayload(body));
+        preflightModel(body, "agent create");
         if (opts.dryRun) {
             printResult({ schema: "agenticflow.dry_run.v1", valid: true, target: "agent.create", payload: body });
             return;
@@ -3483,15 +3555,22 @@ export function createProgram() {
         const client = buildClient(program.opts());
         const body = loadJsonPayload(opts.body);
         ensureLocalValidation("agent.update", validateAgentUpdatePayload(body));
+        preflightModel(body, "agent update");
         if (opts.patch) {
             await run(() => client.agents.patch(opts.agentId, body, {
-                prepare: (merged) => stripNullFields(merged),
+                prepare: (merged) => {
+                    const stripped = stripNullFields(merged);
+                    warnOnStrippedNulls(merged, stripped);
+                    return stripped;
+                },
             }));
         }
         else {
             // Full replace, but strip server-rejected nulls so a round-tripped
             // `af agent get | af agent update --body @-` workflow doesn't 422.
-            const prepared = stripNullFields(body);
+            const original = body;
+            const prepared = stripNullFields(original);
+            warnOnStrippedNulls(original, prepared);
             await run(() => client.agents.update(opts.agentId, prepared));
         }
     });
@@ -4040,28 +4119,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 +4184,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 +4223,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 +4343,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 +4416,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) {