@eigenpal/cli 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @eigenpal/cli
 
+## 0.20.0
+
+### Minor Changes
+
+- 0ce2092: `eigenpal workflow dataset review-request` (and the `eigenpal agents dataset` mirror) is the agent-friendly review loop: create a request with reviewer instructions, `--focus` / `--focus-reason` paths, `--ignore` paths reviewers can skip, and per-example `--item-note` / `--field-note` comments; `list`/`get`/`events` expose `progress.complete`, `fieldDecisions`, and `inputDrifted`; `item --action` records approve/reject/comment/edit plus per-field `field-decision` (clear with `--clear` / `--decision null`); `update --status closed` finishes the request. There is no auto-apply — pull and reconcile examples manually. Reject is recommendation-only; nothing is deleted.
+
 ## 0.17.5
 
 ### Patch Changes

package/dist/cli.js

@@ -7738,6 +7738,9 @@ var init_common = __esm(() => {
     VERIFICATION: "vrf",
     DATASET: "ds",
     DATASET_EXAMPLE: "dex",
+    DATASET_REVIEW_REQUEST: "dsr",
+    DATASET_REVIEW_ITEM: "dsri",
+    DATASET_REVIEW_EVENT: "dsre",
     EXPERIMENT: "exp",
     EXPERIMENT_RUN: "exr",
     EXPERIMENT_EVALUATION: "evl",
@@ -15451,15 +15454,21 @@ var require_dist = __commonJS(function(exports, module) {
 });
 
 // ../types/src/validation/ajv.ts
-var import_ajv, import_ajv_formats, import_json_schema_draft_07, eigenpalAjv;
+function getEigenpalAjv() {
+  if (!sharedAjv) {
+    const ajv = new import_ajv.default({ allErrors: true, strict: false, verbose: true });
+    import_ajv_formats.default(ajv);
+    ajv.addKeyword({ keyword: "x-eigenpal-type", metaSchema: { type: "string" } });
+    ajv.addMetaSchema({ ...import_json_schema_draft_07.default, $id: "https://json-schema.org/draft-07/schema#" });
+    sharedAjv = ajv;
+  }
+  return sharedAjv;
+}
+var import_ajv, import_ajv_formats, import_json_schema_draft_07, sharedAjv = null;
 var init_ajv = __esm(() => {
   import_ajv = __toESM(require_ajv(), 1);
   import_ajv_formats = __toESM(require_dist(), 1);
   import_json_schema_draft_07 = __toESM(require_json_schema_draft_07(), 1);
-  eigenpalAjv = new import_ajv.default({ allErrors: true, strict: false, verbose: true });
-  import_ajv_formats.default(eigenpalAjv);
-  eigenpalAjv.addKeyword({ keyword: "x-eigenpal-type", metaSchema: { type: "string" } });
-  eigenpalAjv.addMetaSchema({ ...import_json_schema_draft_07.default, $id: "https://json-schema.org/draft-07/schema#" });
 });
 
 // ../types/src/validation/workspace-schema.ts
@@ -15481,8 +15490,9 @@ function validateWorkspaceSchema(content, _filename) {
   if (schema.type !== "object") {
     errors.push('Root "type" must be "object"');
   }
-  if (!eigenpalAjv.validateSchema(schema)) {
-    const metaErrors = eigenpalAjv.errors ?? [];
+  const ajv = getEigenpalAjv();
+  if (!ajv.validateSchema(schema)) {
+    const metaErrors = ajv.errors ?? [];
     for (const err of metaErrors) {
       errors.push(`${err.instancePath || "/"}: ${err.message ?? "invalid schema"}`);
     }
@@ -206380,7 +206390,7 @@ import { fileURLToPath as fileURLToPath8 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.19.1",
+  version: "0.20.0",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",
@@ -210037,6 +210047,393 @@ function toCsv(rows, columns) {
 `);
 }
 
+// src/commands/dataset-review-request-briefing.ts
+function splitOnce(value, separator) {
+  const index = value.indexOf(separator);
+  if (index < 0)
+    return [value, undefined];
+  return [value.slice(0, index), value.slice(index + separator.length)];
+}
+function parseFocusReasonFlag(value) {
+  const [path, reason] = splitOnce(value, "=");
+  const trimmedPath = path.trim();
+  if (!trimmedPath) {
+    throw new Error("--focus-reason requires path=reason");
+  }
+  const trimmedReason = reason?.trim();
+  if (!trimmedReason) {
+    throw new Error("--focus-reason requires path=reason");
+  }
+  return { path: trimmedPath, reason: trimmedReason };
+}
+function parseItemNoteFlag(value) {
+  const [exampleName, comment] = splitOnce(value, "=");
+  const trimmedName = exampleName.trim();
+  const trimmedComment = comment?.trim();
+  if (!trimmedName || !trimmedComment) {
+    throw new Error("--item-note requires exampleName=comment");
+  }
+  return { exampleName: trimmedName, comment: trimmedComment };
+}
+function parseFieldNoteFlag(value) {
+  const [left, comment] = splitOnce(value, "=");
+  const trimmedComment = comment?.trim();
+  const dot = left.indexOf(".");
+  const exampleName = (dot < 0 ? left : left.slice(0, dot)).trim();
+  const path = (dot < 0 ? "" : left.slice(dot + 1)).trim();
+  if (!exampleName || !path || !trimmedComment) {
+    throw new Error("--field-note requires exampleName.path=comment");
+  }
+  return { exampleName, fields: [{ path, comment: trimmedComment }] };
+}
+function mergeFocusFields(paths, reasons) {
+  const byPath = new Map;
+  for (const path of paths) {
+    const trimmed = path.trim();
+    if (!trimmed)
+      continue;
+    byPath.set(trimmed, { path: trimmed, reason: null });
+  }
+  for (const field of reasons) {
+    byPath.set(field.path, field);
+  }
+  return [...byPath.values()];
+}
+function mergeItemNotes(notes) {
+  const byName = new Map;
+  for (const note of notes) {
+    const current = byName.get(note.exampleName) ?? { exampleName: note.exampleName };
+    if (note.comment)
+      current.comment = note.comment;
+    if (note.fields?.length) {
+      current.fields = [...current.fields ?? [], ...note.fields];
+    }
+    byName.set(note.exampleName, current);
+  }
+  return [...byName.values()];
+}
+function parseJsonObjectFlag(raw, flag) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`${flag} must be valid JSON`);
+  }
+}
+
+// src/commands/dataset-review-request.ts
+function datasetReviewRequestsPath(automationId, reviewId) {
+  const base = `/v1/automations/${automationId}/dataset-review-requests`;
+  return reviewId ? `${base}/${reviewId}` : base;
+}
+function datasetReviewRequestEventsPath(automationId, reviewId) {
+  return `${datasetReviewRequestsPath(automationId, reviewId)}/events`;
+}
+function datasetReviewRequestItemsPath(automationId, reviewId, itemId) {
+  const base = `${datasetReviewRequestsPath(automationId, reviewId)}/items`;
+  return itemId ? `${base}/${itemId}` : base;
+}
+function collectRepeatable(val2, prev) {
+  return [...prev, val2];
+}
+function formatProgress(progress) {
+  if (!progress)
+    return "-";
+  if (progress.complete) {
+    return progress.rejected ? `complete (${progress.rejected} rejected)` : "complete";
+  }
+  const remaining = progress.remaining ?? 0;
+  const total = progress.total ?? remaining;
+  return `${remaining}/${total} remaining`;
+}
+function parseFieldDecision(opts) {
+  if (opts.clear) {
+    if (opts.decision !== undefined) {
+      throw new Error("pass either --clear or --decision, not both");
+    }
+    return null;
+  }
+  if (opts.decision === undefined) {
+    throw new Error("--decision or --clear is required when --action field-decision");
+  }
+  const normalized = opts.decision.trim().toLowerCase();
+  if (normalized === "null" || normalized === "clear") {
+    return null;
+  }
+  if (normalized === "approved" || normalized === "rejected") {
+    return normalized;
+  }
+  throw new Error("--decision must be approved, rejected, null, or clear");
+}
+function buildReviewItemPatchBody(action, opts) {
+  const body = {
+    action,
+    expectedUpdatedAt: opts.expectedUpdatedAt
+  };
+  if (opts.comment !== undefined)
+    body.comment = opts.comment;
+  if (opts.fieldPath !== undefined)
+    body.fieldPath = opts.fieldPath;
+  if (action === "edit") {
+    if (opts.expectedJson === undefined) {
+      throw new Error("--expected-json is required when --action edit");
+    }
+    body.expected = parseJsonObjectFlag(opts.expectedJson, "--expected-json");
+  } else if (opts.expectedJson !== undefined) {
+    throw new Error("--expected-json is only valid with --action edit");
+  }
+  if (action === "field-decision") {
+    if (!opts.fieldPath?.trim()) {
+      throw new Error("--field-path is required when --action field-decision");
+    }
+    body.decision = parseFieldDecision({ decision: opts.decision, clear: opts.clear });
+  } else if (opts.decision !== undefined || opts.clear) {
+    throw new Error("--decision / --clear are only valid with --action field-decision");
+  }
+  return body;
+}
+function registerDatasetReviewRequestCommands(dataset, resolveAutomation) {
+  const reviewRequest = dataset.command("review-request").description("Review dataset ground truth with a human. Snapshot examples for review and poll progress until reviewers finish.").action(() => {
+    process.stderr.write("`dataset review-request` requires a subcommand. Run `dataset review-request --help`.\n");
+    process.exit(2);
+  });
+  addJsonFlag(withPagination(withBaseUrl(reviewRequest.command("list <automation-id>")).option("--status <csv>", "Filter by review status (comma-separated: draft,open,paused,closed)"), 50)).action(action(async (automationRef, opts) => {
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const params = {
+      limit: String(opts.limit),
+      offset: String(opts.offset)
+    };
+    if (opts.status)
+      params.status = opts.status;
+    const raw = await client.get(datasetReviewRequestsPath(automationId), params);
+    renderListResult(raw, [
+      { key: "id", header: "id" },
+      { key: "title", header: "title" },
+      { key: "status", header: "status" },
+      {
+        key: "progress",
+        header: "progress",
+        format: (value) => formatProgress(value)
+      },
+      { key: "createdAt", header: "createdAt", format: formatTimestamp }
+    ], { ...opts, entityLabel: "review request" });
+  }));
+  addJsonFlag(withBaseUrl(reviewRequest.command("create <automation-id>"))).description("Request human review of dataset ground truth. Snapshot examples and poll progress until review is complete.").requiredOption("--title <title>", "Review request title").requiredOption("--example-name <name>", "Example folder name to include (repeatable)", collectRepeatable, []).option("--instructions <text>", "Note shown to the reviewer for the whole request").option("--focus <path>", "Expected-output path to highlight (repeatable)", collectRepeatable, []).option("--focus-reason <spec>", "Reason a focus path needs review, as path=reason (repeatable)", collectRepeatable, []).option("--ignore <path>", "Expected-output path reviewers can skip (repeatable)", collectRepeatable, []).option("--item-note <spec>", "Example-level note seeded at create time, as exampleName=comment (repeatable)", collectRepeatable, []).option("--field-note <spec>", "Field-level note seeded at create time, as exampleName.path=comment (repeatable)", collectRepeatable, []).option("--focus-json <json>", "JSON array of { path, reason? } focus fields").option("--notes-json <json>", "JSON array of { exampleName, comment?, fields?: [{ path, comment }] }").option("--status <draft|open|paused>", "Initial lifecycle status (default: draft)").addHelpText("after", `
+Examples:
+  $ eigenpal workflow dataset review-request create wf_abc123 \\
+      --title "Q1 invoice GT review" \\
+      --example-name invoice-foo --example-name invoice-bar \\
+      --instructions "Check IBAN checksums and totals." \\
+      --focus vendor.iban --focus-reason 'vendor.iban=OCR often mangles IBANs' \\
+      --ignore currency \\
+      --field-note 'invoice-foo.total=off by 0.01 last run' \\
+      --status open --json
+
+  $ eigenpal workflow dataset review-request list wf_abc123 --status open --json
+  $ eigenpal workflow dataset review-request get wf_abc123 dsr_... --json
+
+Agent loop: create with focus/ignore and per-example notes → poll \`get --json\`
+until \`.progress.complete\` → record per-field decisions and per-example
+approve/reject with comments → read \`events\` → \`dataset pull\` and MANUAL
+per-example reconcile into the live dataset (no auto-apply exists by design;
+reviewers can err) → \`update --status closed\`.
+
+\`reject\` is a recommendation only — nothing is deleted by any review endpoint.
+Use \`--json\` from agents; API errors exit non-zero.
+`).action(action(async (automationRef, opts) => {
+    if (opts.exampleName.length === 0) {
+      throw new Error("pass at least one --example-name");
+    }
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const focusFromFlags = mergeFocusFields(opts.focus ?? [], (opts.focusReason ?? []).map(parseFocusReasonFlag));
+    const focusFromJson = opts.focusJson ? parseJsonObjectFlag(opts.focusJson, "--focus-json") : [];
+    if (opts.focusJson && !Array.isArray(focusFromJson)) {
+      throw new Error("--focus-json must be a JSON array");
+    }
+    const notesFromFlags = mergeItemNotes([
+      ...(opts.itemNote ?? []).map(parseItemNoteFlag),
+      ...(opts.fieldNote ?? []).map(parseFieldNoteFlag)
+    ]);
+    const notesFromJson = opts.notesJson ? parseJsonObjectFlag(opts.notesJson, "--notes-json") : [];
+    if (opts.notesJson && !Array.isArray(notesFromJson)) {
+      throw new Error("--notes-json must be a JSON array");
+    }
+    const body = {
+      title: opts.title,
+      exampleNames: opts.exampleName
+    };
+    if (opts.instructions !== undefined)
+      body.instructions = opts.instructions;
+    if (opts.status !== undefined)
+      body.status = opts.status;
+    const focusFields = [...focusFromFlags, ...focusFromJson];
+    if (focusFields.length > 0)
+      body.focusFields = focusFields;
+    const ignoredFields = [
+      ...new Set((opts.ignore ?? []).map((path) => path.trim()).filter(Boolean))
+    ];
+    if (ignoredFields.length > 0)
+      body.ignoredFields = ignoredFields;
+    const itemNotes = mergeItemNotes([...notesFromFlags, ...notesFromJson]);
+    if (itemNotes.length > 0)
+      body.itemNotes = itemNotes;
+    const payload = await client.post(datasetReviewRequestsPath(automationId), body);
+    if (opts.json)
+      return printJson2(payload);
+    const created = payload;
+    success(`Created review request ${ui.bold(created.id ?? "(unknown id)")}` + (created.status ? ` ${ui.dim(`(${created.status})`)}` : ""));
+  }));
+  addJsonFlag(withBaseUrl(reviewRequest.command("get <automation-id> <review-id>"))).description("Fetch one dataset review request with items, progress, focus fields, ignored fields, and events.").action(action(async (automationRef, reviewId, opts) => {
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const payload = await client.get(datasetReviewRequestsPath(automationId, reviewId));
+    if (opts.json)
+      return printJson2(payload);
+    const detail = payload;
+    console.log(table([
+      { field: "id", value: detail.id },
+      { field: "title", value: detail.title },
+      { field: "status", value: detail.status },
+      { field: "progress", value: formatProgress(detail.progress) },
+      { field: "instructions", value: detail.instructions ?? "-" },
+      {
+        field: "focus",
+        value: detail.focusFields?.map((field) => field.reason ? `${field.path} (${field.reason})` : field.path).join(", ") || "-"
+      },
+      {
+        field: "ignored",
+        value: detail.ignoredFields?.join(", ") || "-"
+      }
+    ], [
+      { key: "field", header: "field" },
+      { key: "value", header: "value" }
+    ]));
+    if (detail.items?.length) {
+      console.log(table(detail.items.map((item) => ({
+        exampleName: item.exampleName,
+        status: item.status,
+        inputDrifted: item.inputDrifted ? "yes" : "no"
+      })), [
+        { key: "exampleName", header: "example" },
+        { key: "status", header: "status" },
+        { key: "inputDrifted", header: "inputDrifted" }
+      ]));
+    }
+  }));
+  addJsonFlag(withBaseUrl(reviewRequest.command("update <automation-id> <review-id>"))).description("Update review metadata or lifecycle status. Set --status closed when review is finished.").option("--title <title>", "New review request title").option("--instructions <text>", "Note shown to the reviewer for the whole request").option("--focus <path>", "Replace focus paths (repeatable; use with --focus-reason / --focus-json)", collectRepeatable, []).option("--focus-reason <spec>", "Reason a focus path needs review, as path=reason (repeatable)", collectRepeatable, []).option("--focus-json <json>", "JSON array of { path, reason? } focus fields (replaces focus)").option("--ignore <path>", "Replace ignored paths (repeatable)", collectRepeatable).option("--status <draft|open|paused|closed>", "Lifecycle status").addHelpText("after", `
+Examples:
+  $ eigenpal workflow dataset review-request update wf_abc123 dsr_... \\
+      --status closed --json
+  $ eigenpal workflow dataset review-request update wf_abc123 dsr_... \\
+      --title "Q1 GT review (round 2)" --instructions "Re-check totals." --json
+
+At least one of --title, --instructions, --focus/--focus-json, --ignore, or
+--status is required. Closing a request does not write expected outputs back
+to the dataset — reconcile manually after \`dataset pull\`.
+`).action(action(async (automationRef, reviewId, opts) => {
+    const body = {};
+    if (opts.title !== undefined)
+      body.title = opts.title;
+    if (opts.instructions !== undefined)
+      body.instructions = opts.instructions;
+    if (opts.status !== undefined)
+      body.status = opts.status;
+    const focusFlagCount = (opts.focus ?? []).length + (opts.focusReason ?? []).length;
+    const hasFocusInput = focusFlagCount > 0 || opts.focusJson !== undefined;
+    if (hasFocusInput) {
+      const focusFromFlags = mergeFocusFields(opts.focus ?? [], (opts.focusReason ?? []).map(parseFocusReasonFlag));
+      const focusFromJson = opts.focusJson ? parseJsonObjectFlag(opts.focusJson, "--focus-json") : [];
+      if (opts.focusJson && !Array.isArray(focusFromJson)) {
+        throw new Error("--focus-json must be a JSON array");
+      }
+      body.focusFields = [...focusFromFlags, ...focusFromJson];
+    }
+    if (opts.ignore !== undefined) {
+      body.ignoredFields = [
+        ...new Set(opts.ignore.map((path) => path.trim()).filter(Boolean))
+      ];
+    }
+    if (Object.keys(body).length === 0) {
+      throw new Error("pass at least one of --title, --instructions, --focus/--focus-json, --ignore, or --status");
+    }
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const payload = await client.patch(datasetReviewRequestsPath(automationId, reviewId), body);
+    if (opts.json)
+      return printJson2(payload);
+    const updated = payload;
+    success(`Updated review request ${ui.bold(updated.id ?? reviewId)}` + (updated.status ? ` ${ui.dim(`(${updated.status})`)}` : ""));
+  }));
+  addJsonFlag(withBaseUrl(reviewRequest.command("items <automation-id> <review-id>"))).description("List snapshotted review items and their statuses.").option("--status <csv>", "Filter by item status (pending,approved,edited,rejected)").action(action(async (automationRef, reviewId, opts) => {
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const params = {};
+    if (opts.status)
+      params.status = opts.status;
+    const payload = await client.get(datasetReviewRequestItemsPath(automationId, reviewId), params);
+    if (opts.json)
+      return printJson2(payload);
+    const items = payload.items ?? [];
+    console.log(table(items.map((item) => ({
+      exampleName: item.exampleName,
+      status: item.status,
+      inputDrifted: item.inputDrifted ? "yes" : "no"
+    })), [
+      { key: "exampleName", header: "example" },
+      { key: "status", header: "status" },
+      { key: "inputDrifted", header: "inputDrifted" }
+    ]));
+  }));
+  addJsonFlag(withBaseUrl(reviewRequest.command("events <automation-id> <review-id>"))).description("List review activity, including example and field notes.").action(action(async (automationRef, reviewId, opts) => {
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const payload = await client.get(datasetReviewRequestEventsPath(automationId, reviewId));
+    if (opts.json)
+      return printJson2(payload);
+    const events = payload.events ?? [];
+    console.log(table(events.map((event) => ({
+      action: event.action,
+      itemId: event.itemId ?? "-",
+      field: event.diffSummary?.fieldPath ?? "-",
+      comment: event.diffSummary?.comment ?? "-",
+      createdAt: event.createdAt ? formatTimestamp(event.createdAt) : "-"
+    })), [
+      { key: "action", header: "action" },
+      { key: "itemId", header: "item" },
+      { key: "field", header: "field" },
+      { key: "comment", header: "comment" },
+      { key: "createdAt", header: "createdAt" }
+    ]));
+  }));
+  addJsonFlag(withBaseUrl(reviewRequest.command("item <automation-id> <review-id> <item-id>"))).description("Approve, reject, reopen, comment, edit, or record a field-decision on one review item.").requiredOption("--action <approve|reject|reopen|comment|edit|field-decision>", "Item action").requiredOption("--expected-updated-at <iso>", "Item updatedAt the client last observed (optimistic concurrency)").option("--comment <text>", "Note stored on the item or field").option("--field-path <path>", "Dotted expected-output path for comment or field-decision").option("--decision <approved|rejected|null>", "Field decision for --action field-decision (null/clear removes it)").option("--clear", "Clear a field decision (sends decision: null)", false).option("--expected-json <json>", "Replacement expected JSON when --action edit").addHelpText("after", `
+Examples:
+  $ eigenpal workflow dataset review-request item wf_abc123 dsr_... dsri_... \\
+      --action field-decision --field-path vendor.iban --decision approved \\
+      --expected-updated-at 2026-01-01T00:00:00.000Z --json
+  $ eigenpal workflow dataset review-request item wf_abc123 dsr_... dsri_... \\
+      --action field-decision --field-path vendor.iban --clear \\
+      --expected-updated-at 2026-01-01T00:00:00.000Z --json
+  $ eigenpal workflow dataset review-request item wf_abc123 dsr_... dsri_... \\
+      --action reject --comment "wrong vendor" \\
+      --expected-updated-at 2026-01-01T00:00:00.000Z --json
+
+\`reject\` marks the example as not recommended for the dataset; it does not
+delete anything. \`--clear\` / \`--decision null\` removes a prior field
+decision (API: decision: null). Always pass \`--expected-updated-at\` from
+the item payload you last observed.
+`).action(action(async (automationRef, reviewId, itemId, opts) => {
+    const { client, automationId } = await resolveAutomation(automationRef, opts);
+    const body = buildReviewItemPatchBody(opts.action, {
+      expectedUpdatedAt: opts.expectedUpdatedAt,
+      comment: opts.comment,
+      fieldPath: opts.fieldPath,
+      decision: opts.decision,
+      clear: opts.clear,
+      expectedJson: opts.expectedJson
+    });
+    const payload = await client.patch(datasetReviewRequestItemsPath(automationId, reviewId, itemId), body);
+    if (opts.json)
+      return printJson2(payload);
+    const item = payload.item;
+    success(`Updated ${ui.bold(item?.exampleName ?? itemId)}` + (item?.status ? ` ${ui.dim(`(${item.status})`)}` : ""));
+  }));
+}
+
 // src/commands/agents/validation.ts
 init_src();
 import { existsSync as existsSync7, promises as fs2 } from "node:fs";
@@ -210342,7 +210739,7 @@ function validateValuesAgainstSchemaProps(data, schema, label) {
 }
 function validateValueAgainstSchema(value, schema, label) {
   try {
-    const validate = eigenpalAjv.compile(schema);
+    const validate = getEigenpalAjv().compile(schema);
     if (validate(value))
       return [];
     return (validate.errors ?? []).map((err) => {
@@ -210377,6 +210774,11 @@ Layout
   (referenced via { "$file": "input/<path>" }), plus optional
   expected.json, expected/<file>, and meta.json.
   Run \`eigenpal agents dataset validate\` first to check locally.
+
+  After pushing examples for a new agent, request a dataset review before
+  iterating to perfection: \`agents dataset review-request create <agent>
+  --title ... --example-name ... --status open\`, poll \`.progress.complete\`,
+  then close the request when review is finished.
 `).action(action(pushDataset));
   withBaseUrl(dataset.command("pull <agent-id-or-slug>")).description("Download an agent dataset as a .zip archive.").option("--out <path>", "Output .zip path (default: dataset.zip)", DATASET_DIR).action(action(pullDataset));
   addJsonFlag(dataset.command("validate [path]")).description("Validate a local dataset directory against the canonical examples/<name> layout. Defaults to ./dataset/.").option("--agent-dir <dir>", "Agent package directory with optional input/output schemas for extra value-level checks", ".").addHelpText("after", `
@@ -210394,6 +210796,10 @@ Layout (mirrors the server import rules)
 ` + `  workflow-only and rejected for agent datasets: agent runs are evaluated
 ` + `  only when they complete.
 `).action(action(validateDatasetCommand));
+  registerDatasetReviewRequestCommands(dataset, async (agentId, opts) => {
+    const client = buildClient2(opts);
+    return { client, automationId: agentAutomationId(agentId) };
+  });
 }
 async function listDataset(agentId, opts) {
   const client = buildClient2(opts);
@@ -247249,6 +247655,11 @@ Examples:
 \`--mode append\` is the default; \`--mode replace\` deletes every existing example
 + its files first and prompts a typed-slug confirmation in TTY (use \`--yes\` to
 skip in CI). Folder layout reference: \`packages/cli/src/skill/reference/dataset-format.md\`.
+
+After pushing examples for a new workflow, request a dataset review before
+iterating to perfection: \`dataset review-request create <workflow-id>
+--title ... --example-name ... --status open\`, poll \`.progress.complete\`,
+then close the request when review is finished.
 `);
   addJsonFlag(withBaseUrl(pushCmd)).action(action(async (workflow, opts) => {
     if (opts.mode !== "append" && opts.mode !== "replace") {
@@ -247340,7 +247751,12 @@ skip in CI). Folder layout reference: \`packages/cli/src/skill/reference/dataset
   }));
   registerDatasetCrudCommands(dataset);
   registerDatasetValidateCommand(dataset);
+  registerDatasetReviewRequestCommands(dataset, resolveAutomationForReviewRequest);
 }
+var resolveAutomationForReviewRequest = async (workflow, opts) => {
+  const { client, workflowId } = await buildClientForWorkflow(workflow, opts);
+  return { client, automationId: workflowId };
+};
 async function readJsonInput(literal, filePath, flagName) {
   if (literal !== undefined && filePath !== undefined) {
     throw new Error(`pass either --${flagName}-json or --${flagName}-file, not both`);