feat(v1.5.3): round-3 subagent iteration — preflight, hints, null-strip notice

Dispatched a third clean-state subagent with an iteration-heavy scenario
(Amira's Kopi Junction support agent with escalation rules). The subagent
confirmed v1.5.1/1.5.2 fixes work as advertised — `--patch` iteration took
just 2 commands to go from V1 wrong to V2 correct — and flagged 3 new
actionable friction points addressed here.

Fixes:

1. (F1) Model preflight on agent create/update
   Previously `{"model":"not-a-real-model"}` saved successfully and only
   blew up at next `agent run`. Now fails fast with a structured error +
   hint listing known models. Plausible-but-unknown (`vendor/name` shape)
   models warn to stderr but proceed — so brand-new models work between
   CLI releases.

2. (F2) Status-hint enrichment on API errors
   401 → "Run af whoami / af login --api-key"
   403 → "Check workspace/project or API key scopes"
   404 → "Run the matching `list` command to see available IDs"
   409 → "Fetch current state and reconcile before retrying"
   422 → "Check details.payload for field-level errors"
   429 → "Rate limited; back off"
   Every API error in --json output now carries an actionable `hint`.

3. (F3) Null-strip visibility
   `af agent update` emits a stderr [info] line listing which null-valued
   fields got auto-stripped — closes the footgun where bots thought they
   cleared a field but the server never saw null. Silenced under --json
   (keeps stdout clean for pipes).

Tests: 385 pass (+7 from new utils-models.test.ts), same 14 skipped + 10
todo. Full regression: no behavior change on the green path.

Quote from the round-3 subagent after using v1.5.2: "--patch made
iteration feel like editing code, not re-creating a resource. Consistent
schema: discriminators on every JSON response make scripting trivial.
This is the right trajectory."

Author: seanphan

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelml/agenticflow-cli",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "AgenticFlow CLI for agent-native API operations.",
   "license": "Apache-2.0",
   "repository": {

packages/cli/src/cli/changelog.ts

@@ -13,6 +13,20 @@ export interface ChangelogEntry {
 }
 
 export const CHANGELOG: ChangelogEntry[] = [
+  {
+    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",

packages/cli/src/cli/main.ts

@@ -27,9 +27,10 @@ import { WebhookConnector } from "./gateway/connectors/webhook.js";
 import type { ChannelConnector } from "./gateway/connector.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,
@@ -601,6 +602,20 @@ function buildClient(parentOpts: {
   });
 }
 
+/**
+ * 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: Record<number, string> = {
+  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: () => Promise<unknown>): Promise<void> {
   try {
@@ -618,12 +633,53 @@ async function run(fn: () => Promise<unknown>): Promise<void> {
       };
       if (err.requestId) 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: Record<string, unknown>, context: string): void {
+  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: Record<string, unknown>,
+  stripped: Record<string, unknown>,
+): void {
+  if (isJsonFlagEnabled()) return; // don't pollute stderr on bot-driven runs
+  const dropped: string[] = [];
+  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)
 // ═══════════════════════════════════════════════════════════════════
@@ -3956,6 +4012,7 @@ export function createProgram(): Command {
       const body = loadJsonPayload(opts.body);
       hardenInput(JSON.stringify(body), "agent create body");
       ensureLocalValidation("agent.create", validateAgentCreatePayload(body));
+      preflightModel(body as Record<string, unknown>, "agent create");
       if (opts.dryRun) {
         printResult({ schema: "agenticflow.dry_run.v1", valid: true, target: "agent.create", payload: body });
         return;
@@ -3977,16 +4034,23 @@ export function createProgram(): Command {
       const client = buildClient(program.opts());
       const body = loadJsonPayload(opts.body);
       ensureLocalValidation("agent.update", validateAgentUpdatePayload(body));
+      preflightModel(body as Record<string, unknown>, "agent update");
       if (opts.patch) {
         await run(() =>
           client.agents.patch(opts.agentId, body as Record<string, unknown>, {
-            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 as Record<string, unknown>);
+        const original = body as Record<string, unknown>;
+        const prepared = stripNullFields(original);
+        warnOnStrippedNulls(original, prepared);
         await run(() => client.agents.update(opts.agentId, prepared));
       }
     });

packages/cli/src/cli/utils/models.ts

@@ -0,0 +1,65 @@
+/**
+ * Known model identifiers the AgenticFlow platform serves.
+ *
+ * Kept here so CLI-side validation can fail-fast on typos BEFORE a bogus
+ * `model` string gets saved to an agent and only blows up at next run time.
+ *
+ * Stay in sync with the `models` array in `af bootstrap --json` and the
+ * backend model registry. When you add a model here, also add it to
+ * main.ts's bootstrap output.
+ *
+ * If this list drifts, `validateModel()` returns a soft-warning (not a hard
+ * fail) so callers can still use brand-new models before the CLI is bumped.
+ */
+
+export const KNOWN_MODELS: ReadonlyArray<string> = [
+  "agenticflow/gemma-4-31b-it",
+  "agenticflow/gemma-4-26b-a4b-it",
+  "agenticflow/gemini-2.0-flash",
+  "agenticflow/gpt-4o-mini",
+  "agenticflow/deepseek-v3.2",
+  "agenticflow/qwen-3.5-flash",
+];
+
+export interface ModelValidation {
+  valid: boolean;
+  known: boolean;
+  suggestion?: string;
+}
+
+/**
+ * Lightweight validator — flags bogus model strings before they reach the
+ * server. Three outcomes:
+ *   - model in KNOWN_MODELS: `{valid: true, known: true}` — pass through.
+ *   - plausible format (`vendor/model-name`) but not in the list: `{valid:
+ *     true, known: false}` — warn but allow (new models ship between CLI
+ *     releases; don't hard-block).
+ *   - implausible format (no slash, empty, suspiciously short): `{valid:
+ *     false, known: false, suggestion}` — fail fast with a hint.
+ */
+export function validateModel(model: unknown): ModelValidation {
+  if (typeof model !== "string" || model.trim().length === 0) {
+    return {
+      valid: false,
+      known: false,
+      suggestion: `Model must be a non-empty string like "agenticflow/gemini-2.0-flash". Available: ${KNOWN_MODELS.join(", ")}`,
+    };
+  }
+  const trimmed = model.trim();
+  if (KNOWN_MODELS.includes(trimmed)) {
+    return { valid: true, known: true };
+  }
+  // Looks like `vendor/model-name`? Permit with warning.
+  if (/^[a-z0-9_-]+\/[a-z0-9][a-z0-9._-]*$/i.test(trimmed)) {
+    return {
+      valid: true,
+      known: false,
+      suggestion: `Model "${trimmed}" is not in the CLI's known list. If this is a new model, proceed — but double-check the spelling. Known: ${KNOWN_MODELS.join(", ")}`,
+    };
+  }
+  return {
+    valid: false,
+    known: false,
+    suggestion: `Model "${trimmed}" has an invalid shape (expected "vendor/model-name"). Available: ${KNOWN_MODELS.join(", ")}`,
+  };
+}

packages/cli/tests/utils-models.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { validateModel, KNOWN_MODELS } from "../src/cli/utils/models.js";
+
+describe("validateModel", () => {
+  it("accepts a known model as valid + known", () => {
+    const r = validateModel("agenticflow/gemma-4-31b-it");
+    expect(r.valid).toBe(true);
+    expect(r.known).toBe(true);
+    expect(r.suggestion).toBeUndefined();
+  });
+
+  it("accepts every shipped model", () => {
+    for (const m of KNOWN_MODELS) {
+      const r = validateModel(m);
+      expect(r.valid).toBe(true);
+      expect(r.known).toBe(true);
+    }
+  });
+
+  it("warns on plausible-but-unknown vendor/model string", () => {
+    const r = validateModel("agenticflow/brand-new-model-2027");
+    expect(r.valid).toBe(true); // allow — don't block brand-new models
+    expect(r.known).toBe(false);
+    expect(r.suggestion).toMatch(/not in the CLI's known list/);
+  });
+
+  it("fails on a plain token with no slash (subagent's F1 bug)", () => {
+    const r = validateModel("not-a-real-model");
+    expect(r.valid).toBe(false);
+    expect(r.suggestion).toMatch(/invalid shape/);
+  });
+
+  it("fails on empty / whitespace", () => {
+    expect(validateModel("").valid).toBe(false);
+    expect(validateModel("   ").valid).toBe(false);
+  });
+
+  it("fails on non-string input", () => {
+    expect(validateModel(null).valid).toBe(false);
+    expect(validateModel(42).valid).toBe(false);
+    expect(validateModel(undefined).valid).toBe(false);
+  });
+
+  it("trims whitespace before validating", () => {
+    const r = validateModel("  agenticflow/gemini-2.0-flash  ");
+    expect(r.valid).toBe(true);
+    expect(r.known).toBe(true);
+  });
+});