primcli 3.0.0-preview.3 → 3.0.0-preview.4

package/dist/{api-command-DWjtyqH9.js → api-command-BFfgKPTp.js}

@@ -1,11 +1,13 @@
-import { $ as AutomatedFilterUnsupportedError, F as assertAwaitingFilterRows, G as WEBHOOK_EVENT_TYPES, I as awaitingRejectedError, Jt as getThread, L as ensureSearchReportsReplyState, Lt as getEmail, P as ReplyStateUnsupportedError, Pn as sdk_gen_exports, U as replyStateSurfaceForOperation, V as isAwaitingRejectedError, W as SENT_EMAIL_EVENT_TYPES, et as assertAutomatedVerdict, it as expectedAutomatedVerdicts, nt as automatedSurfaceForOperation, ot as isAutomatedRejectedError, rt as ensureSearchReportsAutomated, sn as listEndpoints, tt as automatedRejectedError, v as parseRetryAfter } from "./repeats-Dj_o6c-X-BKHiZsYv.js";
+import { F as ReplyStateUnsupportedError, G as SENT_EMAIL_EVENT_TYPES, H as isAwaitingRejectedError, I as assertAwaitingFilterRows, K as WEBHOOK_EVENT_TYPES, L as awaitingRejectedError, Ln as sdk_gen_exports, R as ensureSearchReportsReplyState, Rt as getEmail, W as replyStateSurfaceForOperation, Yt as getThread, at as expectedAutomatedVerdicts, et as AutomatedFilterUnsupportedError, it as ensureSearchReportsAutomated, ln as listEndpoints, nt as automatedRejectedError, rt as automatedSurfaceForOperation, st as isAutomatedRejectedError, tt as assertAutomatedVerdict, v as parseRetryAfter } from "./repeats-Dj_o6c-X-BwGkVE7e.js";
 import { C as saveCliCredentials, F as agentProfilesDirectory, H as requireDefaultLoginProfile, N as agentProfileDirectory, R as loadConnectedAgentProfile, S as resolveCliAuth, W as PrimitiveApiClient, _ as deleteCliCredentials, b as loadCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, i as loadCliConfig, j as AGENT_PROFILE_ENV, m as cliAccessTokenExpiresAt, p as acquireCliCredentialsLock, w as saveSignupCredentials, x as normalizeApiBaseUrl, y as detectPrimitiveKeyEnvMisname } from "./cli-config-Ms_0vNjq.js";
 import "./oclif/global-org-flag.js";
 import { d as readMailJson, h as writeMailJson, m as withMailLock, p as syncMailDirectory, u as privateMailPermissions } from "./shared-mail-files-BAQSGxxz.js";
-import { Command, Errors, Flags } from "@oclif/core";
+import { Args, Command, Errors, Flags } from "@oclif/core";
 import { existsSync, lstatSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { join } from "node:path";
+import { join, win32 } from "node:path";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 // src/oclif/user-grant.ts
 /**
 * CLI user logins: a login as the person, not bound to one organization,
@@ -51,7 +53,7 @@ var CliOrgRefusedError = class extends Errors.CLIError {
 		this.orgId = params.orgId;
 	}
 };
-function isRecord(value) {
+function isRecord$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function apiOrigin(apiBaseUrl) {
@@ -78,7 +80,7 @@ function isUuid(value) {
 	return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
 function isOrgAccessToken(value) {
-	return isRecord(value) && typeof value.access_token === "string" && value.access_token.length > 0 && value.token_type === "Bearer" && typeof value.expires_in === "number" && value.expires_in > 0 && typeof value.org_id === "string" && (value.org_name === null || typeof value.org_name === "string") && typeof value.oauth_grant_id === "string";
+	return isRecord$1(value) && typeof value.access_token === "string" && value.access_token.length > 0 && value.token_type === "Bearer" && typeof value.expires_in === "number" && value.expires_in > 0 && typeof value.org_id === "string" && (value.org_name === null || typeof value.org_name === "string") && typeof value.oauth_grant_id === "string";
 }
 function orgTokenFromResponse(token, now = Date.now) {
 	return {
@@ -125,7 +127,7 @@ async function postTokenEndpoint(params) {
 		throw new Errors.CLIError(`Could not reach the Primitive OAuth token endpoint: ${detail}`, { exit: 1 });
 	}
 	const payload = await response.json().catch(() => null);
-	if (response.ok && isRecord(payload)) return {
+	if (response.ok && isRecord$1(payload)) return {
 		ok: true,
 		payload
 	};
@@ -133,7 +135,7 @@ async function postTokenEndpoint(params) {
 		ok: true,
 		payload: {}
 	};
-	const record = isRecord(payload) ? payload : {};
+	const record = isRecord$1(payload) ? payload : {};
 	return {
 		ok: false,
 		status: response.status,
@@ -336,12 +338,12 @@ async function fetchCliOrgs(params) {
 	}
 	const payload = await response.json().catch(() => null);
 	if (!response.ok) {
-		const error = isRecord(payload) && isRecord(payload.error) ? payload.error : {};
+		const error = isRecord$1(payload) && isRecord$1(payload.error) ? payload.error : {};
 		if (response.status === 404 && error.code === "feature_disabled") throw new Errors.CLIError("This Primitive server does not support switching organizations for CLI logins.", { exit: 1 });
 		throw new Errors.CLIError(`Could not list organizations${typeof error.message === "string" ? `: ${error.message}` : ` (HTTP ${response.status}).`}`, { exit: 1 });
 	}
-	const data = isRecord(payload) ? payload.data : null;
-	if (!isRecord(data) || !Array.isArray(data.orgs)) throw new Errors.CLIError("Primitive API returned an unexpected organization list.", { exit: 1 });
+	const data = isRecord$1(payload) ? payload.data : null;
+	if (!isRecord$1(data) || !Array.isArray(data.orgs)) throw new Errors.CLIError("Primitive API returned an unexpected organization list.", { exit: 1 });
 	return data;
 }
 /** How long a command waits for another CLI process to finish with the saved login. */
@@ -914,6 +916,470 @@ async function withAttachmentWait(call, options) {
 	}
 	return result;
 }
+// src/oclif/email-rule-authoring.ts
+const EMAIL_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+/** Whether `id` has the shape of an email id (a UUID). */
+function isEmailId(id) {
+	return EMAIL_ID.test(id);
+}
+function usageError(message) {
+	return new Errors.CLIError(message, { exit: 2 });
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function errorDetail(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function checkEmailId(id, label) {
+	if (!isEmailId(id)) throw usageError(`${label} takes email ids (UUIDs, from \`primitive emails list\`); "${id}" is not one.`);
+	return id;
+}
+/**
+* The email ids in a repeatable, comma-separated flag, in the order given and
+* without repeats.
+*/
+function parseEmailIdList(values, flag) {
+	const ids = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of values) for (const raw of value.split(",")) {
+		const id = raw.trim();
+		if (id === "") continue;
+		checkEmailId(id, flag);
+		if (seen.has(id.toLowerCase())) continue;
+		seen.add(id.toLowerCase());
+		ids.push(id);
+	}
+	if (ids.length === 0) throw usageError(`${flag} needs at least one email id.`);
+	return ids;
+}
+function assertDisjoint(expectations, label) {
+	const match = new Set((expectations.match ?? []).map((id) => id.toLowerCase()));
+	const both = (expectations.no_match ?? []).find((id) => match.has(id.toLowerCase()));
+	if (both) throw usageError(`${label}: ${both} is expected both to match and not to match; give each email one way.`);
+}
+/**
+* Check a JSON value in the shape of a rule's expectations or a test's
+* `expect`: an object with `match` and `no_match`, each a list of email ids,
+* at least one id in all, and no id in both. Repeats are removed.
+*/
+function checkExpectations(value, label) {
+	if (!isRecord(value)) throw usageError(`${label} must hold a JSON object such as {"match": ["<email-id>"], "no_match": ["<email-id>"]}.`);
+	const expectations = {};
+	for (const [key, list] of Object.entries(value)) {
+		if (key !== "match" && key !== "no_match") throw usageError(`${label} takes only "match" and "no_match"; "${key}" is not one of them.`);
+		if (!Array.isArray(list) || list.some((id) => typeof id !== "string")) throw usageError(`${label}: "${key}" must be a list of email ids.`);
+		const ids = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const id of list) {
+			checkEmailId(id, label);
+			if (seen.has(id.toLowerCase())) continue;
+			seen.add(id.toLowerCase());
+			ids.push(id);
+		}
+		expectations[key] = ids;
+	}
+	if ((expectations.match?.length ?? 0) + (expectations.no_match?.length ?? 0) === 0) throw usageError(`${label} needs at least one email id in match or no_match.`);
+	assertDisjoint(expectations, label);
+	return expectations;
+}
+/** Read and parse a JSON file a flag names, failing like --body-file does. */
+function readJsonFileFlag(path, flag) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new Errors.CLIError(`Could not read ${flag} ${path}: ${errorDetail(error)}`, { exit: 1 });
+	}
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw new Errors.CLIError(`${flag} ${path} is not valid JSON: ${errorDetail(error)}`, { exit: 1 });
+	}
+}
+/** `expect` for test-email-rule, from --expect-file or the id flags. */
+function expectBodyFields(flags) {
+	const file = flags["expect-file"];
+	if (typeof file === "string") {
+		const label = `--expect-file ${file}`;
+		return [{
+			flag: "--expect-file",
+			property: "expect",
+			value: checkExpectations(readJsonFileFlag(file, "--expect-file"), label)
+		}];
+	}
+	const expect = {};
+	const given = [];
+	const match = flags["expect-match"];
+	if (Array.isArray(match)) {
+		expect.match = parseEmailIdList(match, "--expect-match");
+		given.push("--expect-match");
+	}
+	const noMatch = flags["expect-no-match"];
+	if (Array.isArray(noMatch)) {
+		expect.no_match = parseEmailIdList(noMatch, "--expect-no-match");
+		given.push("--expect-no-match");
+	}
+	if (given.length === 0) return [];
+	assertDisjoint(expect, given.join(" and "));
+	return [{
+		flag: given.join(", "),
+		property: "expect",
+		value: expect
+	}];
+}
+/**
+* `expectations` for create-email-rule and update-email-rule, from
+* --expectations-file. A file holding `null` removes the saved expectations,
+* which only update accepts.
+*/
+function expectationsBodyFields(allowNull) {
+	return (flags) => {
+		const file = flags["expectations-file"];
+		if (typeof file !== "string") return [];
+		const value = readJsonFileFlag(file, "--expectations-file");
+		if (value === null && !allowNull) throw usageError(`--expectations-file ${file} holds null, which only update-email-rule takes (to remove a rule's saved expectations). A new rule takes an object such as {"match": ["<email-id>"], "no_match": ["<email-id>"]}, or no --expectations-file.`);
+		return [{
+			flag: "--expectations-file",
+			property: "expectations",
+			value: value === null ? null : checkExpectations(value, `--expectations-file ${file}`)
+		}];
+	};
+}
+function confidence(value) {
+	return value.toFixed(2);
+}
+/**
+* A fact or column value as rule conditions read it, with its confidence:
+* `true at 0.69`, or for a multi fact with per-value confidences
+* `[billing 0.91, invoice 0.62] at 0.80`.
+*/
+function formatFactValue(fact) {
+	const value = fact?.value;
+	let text;
+	if (Array.isArray(value)) {
+		const per = isRecord(fact?.value_confidences) ? fact.value_confidences : void 0;
+		text = `[${value.map((item) => {
+			const name = String(item);
+			const score = per?.[name];
+			return typeof score === "number" ? `${name} ${confidence(score)}` : name;
+		}).join(", ")}]`;
+	} else if (value === null || value === void 0) text = "null";
+	else if (typeof value === "object") text = JSON.stringify(value);
+	else text = String(value);
+	return typeof fact?.confidence === "number" ? `${text} at ${confidence(fact.confidence)}` : text;
+}
+/** One line for a fact: `is_cold_outreach: true at 0.69`. */
+function formatFact(name, fact) {
+	return `${name}: ${formatFactValue(fact)}`;
+}
+function scopeWarningLine(warning) {
+	const message = warning.message?.trim();
+	if (!message) return `Scope warning: ${warning.name} (${warning.reason})`;
+	return message.includes(warning.name) ? `Scope warning: ${message}` : `Scope warning: ${warning.name}: ${message}`;
+}
+function scopeWarningLines(warnings) {
+	return Array.isArray(warnings) ? warnings.filter(isRecord).map(scopeWarningLine) : [];
+}
+const UNCLASSIFIED_REASONS = {
+	pending: {
+		why: "not classified yet",
+		resolvable: true
+	},
+	classifier_unavailable: {
+		why: "the classifier was unavailable",
+		resolvable: true
+	},
+	classification_failed: {
+		why: "its classification failed",
+		resolvable: false,
+		may: true
+	},
+	not_classifiable: {
+		why: "it cannot be classified",
+		resolvable: false
+	}
+};
+function sameId(a, b) {
+	return a.toLowerCase() === b.toLowerCase();
+}
+/**
+* Why an expectation is undecided, from its email's result, and whether a
+* later test can decide it: not for an email the rule cannot find or read, or
+* one that cannot be classified; yes for one not classified yet, or whose
+* question went unanswered.
+*/
+function undecidedReason(expectation, results) {
+	const result = results.find((entry) => sameId(entry.email_id, expectation.email_id));
+	const outcome = result?.outcome ?? expectation.outcome;
+	if (outcome === "not_found") return {
+		why: "no such email the rule can read",
+		resolvable: false
+	};
+	if (outcome === "unclassified") {
+		const reason = result?.unclassified_reason;
+		return (reason ? UNCLASSIFIED_REASONS[reason] : void 0) ?? {
+			why: reason ? `unclassified (${reason})` : "unclassified",
+			resolvable: false
+		};
+	}
+	return {
+		why: "a question went unanswered",
+		resolvable: true
+	};
+}
+function undecidedNote(reason) {
+	return `${reason.why}; ${reason.resolvable ? "test again later" : reason.may ? "a later test may not decide it" : "testing again will not decide it"}`;
+}
+function answerText(answer) {
+	const verdict = answer.answer === true ? "yes" : answer.answer === false ? "no" : "unanswered";
+	const probability = typeof answer.probability === "number" ? ` at ${confidence(answer.probability)}` : "";
+	const error = answer.error_class ? ` (${answer.error_class})` : "";
+	return `"${answer.question}" ${verdict}${probability}${error}`;
+}
+function conditionLines(summary) {
+	const conditions = Array.isArray(summary?.conditions) ? summary.conditions : [];
+	if (conditions.length === 0) return [];
+	return [`Conditions (${summary?.decided ?? 0} decided):`, ...conditions.map((condition) => `  ${condition.index}. ${condition.text}: held on ${condition.held}, failed on ${condition.failed} (the only failure on ${condition.only_failure})`)];
+}
+function questionLines(summary, results) {
+	const questions = Array.isArray(summary?.questions) ? summary.questions : [];
+	if (questions.length === 0) return [];
+	return ["Questions (on emails whose conditions held):", ...questions.map((question) => {
+		const text = results.find((result) => result.question_answers?.[question.index])?.question_answers?.[question.index]?.question;
+		return `  ${question.index}. ${text ? `"${text}": ` : ""}yes ${question.yes}, no ${question.no}, unanswered ${question.unanswered}`;
+	})];
+}
+function expectationLine(result, results) {
+	const note = result.status === "undecided" ? undecidedNote(undecidedReason(result, results)) : void 0;
+	return `  ${result.status}: ${result.email_id} expected ${result.expected}, got ${result.outcome}${note ? ` (${note})` : ""}`;
+}
+function expectationsLines(expectations, testResults) {
+	if (!expectations) return [];
+	const results = Array.isArray(expectations.results) ? expectations.results : [];
+	const passed = expectations.counts?.passed ?? 0;
+	const failed = expectations.counts?.failed ?? 0;
+	const undecided = expectations.counts?.undecided ?? 0;
+	if (expectations.passed && failed === 0 && undecided === 0) return [`Expectations: all ${passed} passed.`];
+	return [`Expectations: ${[
+		failed > 0 ? `${failed} failed` : "",
+		undecided > 0 ? `${undecided} undecided` : "",
+		`${passed} passed`
+	].filter((part) => part !== "").join(", ")}.`, ...results.filter((result) => result.status !== "passed").map((result) => expectationLine(result, testResults))];
+}
+const NOT_MATCHED_ORDER = {
+	near_miss: 1,
+	no_match: 2,
+	unclassified: 3,
+	not_found: 4
+};
+function notMatchedLine(result) {
+	if (result.outcome === "unclassified") {
+		const reason = result.unclassified_reason;
+		const note = !reason ? "" : UNCLASSIFIED_REASONS[reason]?.resolvable ? `${reason}: test again later` : reason;
+		return [`  ${result.email_id} unclassified${note ? ` (${note})` : ""}`];
+	}
+	if (result.outcome === "not_found") return [`  ${result.email_id} not_found`];
+	const failedParts = (result.parts ?? []).filter((part) => !part.matched).map((part) => part.index);
+	const values = Object.entries(result.values ?? {}).map(([column, value]) => formatFact(column, value));
+	const missing = result.missing_facts ?? [];
+	if (missing.length > 0) values.push(`missing: ${missing.join(", ")}`);
+	const head = `  ${result.email_id} ${result.outcome}${failedParts.length > 0 ? ` (failed part ${failedParts.join(", ")})` : ""}`;
+	const lines = [values.length > 0 ? `${head}: ${values.join("; ")}` : head];
+	const answers = result.question_answers ?? [];
+	if (answers.length > 0) {
+		const source = result.question_answers_source ? ` (${result.question_answers_source})` : "";
+		lines.push(`    questions${source}: ${answers.map(answerText).join("; ")}`);
+	}
+	return lines;
+}
+function notMatchedLines(results, expectations) {
+	const flagged = new Set((expectations?.results ?? []).filter((result) => result.status !== "passed").map((result) => result.email_id));
+	const rank = (result) => flagged.has(result.email_id) ? 0 : NOT_MATCHED_ORDER[result.outcome] ?? 5;
+	const notMatched = results.filter((result) => result.outcome !== "matched").map((result, position) => ({
+		result,
+		position
+	})).sort((a, b) => rank(a.result) - rank(b.result) || a.position - b.position).map(({ result }) => result);
+	if (notMatched.length === 0) return [];
+	const shown = notMatched.slice(0, 25);
+	return [shown.length < notMatched.length ? `Not matched (${shown.length} of ${notMatched.length} shown; the JSON has every result):` : `Not matched (${notMatched.length}):`, ...shown.flatMap(notMatchedLine)];
+}
+/**
+* The exit code a test's expectations call for, and the error a --json
+* document carries with it:
+* - 1 and `expectations_failed` when one failed;
+* - else 1 and `expectations_unresolvable` when one is undecided and a later
+*   test cannot decide it (its email cannot be found or read, or cannot be
+*   classified);
+* - else 3 and `expectations_undecided` when one is undecided and a later
+*   test can decide it;
+* - else nothing: the exit code stays 0.
+*/
+function expectationsOutcome(expectations, testResults = []) {
+	if (!expectations) return {};
+	const results = Array.isArray(expectations.results) ? expectations.results : [];
+	const failed = results.filter((result) => result.status === "failed").map((result) => result.email_id);
+	const undecided = results.filter((result) => result.status === "undecided").map((result) => ({
+		id: result.email_id,
+		reason: undecidedReason(result, testResults)
+	}));
+	const unresolvable = undecided.filter(({ reason }) => !reason.resolvable);
+	const failedCount = Math.max(expectations.counts?.failed ?? 0, failed.length);
+	const undecidedCount = Math.max(expectations.counts?.undecided ?? 0, undecided.length);
+	const plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+	const why = (list) => list.map(({ id, reason }) => `${id} (${reason.why})`).join(", ");
+	if (failedCount > 0) return {
+		exitCode: 1,
+		error: {
+			code: "expectations_failed",
+			message: `${plural(failedCount, "expectation", "expectations")} failed${failed.length > 0 ? `: ${failed.join(", ")}` : ""}.`
+		}
+	};
+	if (unresolvable.length > 0) return {
+		exitCode: 1,
+		error: {
+			code: "expectations_unresolvable",
+			message: `${plural(unresolvable.length, "expectation is", "expectations are")} undecided, and testing again will not decide ${unresolvable.length === 1 ? "it" : "them"}: ${why(unresolvable)}.`
+		}
+	};
+	if (undecidedCount > 0) return {
+		exitCode: 3,
+		error: {
+			code: "expectations_undecided",
+			message: `${plural(undecidedCount, "expectation is", "expectations are")} undecided${undecided.length > 0 ? `: ${why(undecided)}` : ""}. Test again later.`
+		}
+	};
+	return {};
+}
+/** The stderr report and exit code of a test-email-rule answer. */
+function testEmailRuleReport(data) {
+	if (!isRecord(data)) return { lines: [] };
+	const result = data;
+	const results = Array.isArray(result.results) ? result.results : [];
+	const summary = isRecord(result.summary) ? result.summary : void 0;
+	return {
+		lines: [
+			...(Array.isArray(summary?.warnings) ? summary.warnings : []).map((warning) => `Warning: ${warning}`),
+			...scopeWarningLines(result.scope_warnings),
+			...conditionLines(summary),
+			...questionLines(summary, results),
+			...expectationsLines(result.expectations, results),
+			...notMatchedLines(results, result.expectations)
+		],
+		...expectationsOutcome(result.expectations, results)
+	};
+}
+function expectationsCheckLine(check, ruleId) {
+	if (!isRecord(check)) return void 0;
+	const on = typeof check.version === "number" ? `version ${check.version}` : "the current version";
+	const failed = Array.isArray(check.failed) ? check.failed : [];
+	const undecided = Array.isArray(check.undecided) ? check.undecided : [];
+	if (check.passed && failed.length === 0 && undecided.length === 0) return `Expectations on ${on}: all passed.`;
+	const parts = [];
+	if (failed.length > 0) parts.push(`${failed.length} failed (${failed.join(", ")})`);
+	if (undecided.length > 0) parts.push(`${undecided.length} undecided (${undecided.join(", ")})`);
+	const rest = undecided.length > 0 ? ` To decide the rest, run \`primitive email-rules test-email-rule --rule-id ${ruleId}\`.` : "";
+	return `Expectations on ${on}: ${parts.length > 0 ? parts.join(", ") : "not passed"}.${rest}`;
+}
+/** The stderr report of a rule written by create-email-rule or update-email-rule. */
+function writtenEmailRuleReport(data, request) {
+	if (!isRecord(data)) return { lines: [] };
+	const rule = data;
+	const ruleId = typeof rule.id === "string" ? rule.id : "<rule-id>";
+	const lines = scopeWarningLines(rule.scope_warnings);
+	const checked = expectationsCheckLine(rule.expectations_check, ruleId);
+	if (checked) lines.push(checked);
+	else if (isRecord(request.body) && isRecord(request.body.expectations)) lines.push(`Expectations were not checked on this write. Test them with \`primitive email-rules test-email-rule --rule-id ${ruleId}\`.`);
+	return { lines };
+}
+/** The stderr report of get-email-rule-scope. */
+function emailRuleScopeReport(data) {
+	if (!isRecord(data)) return { lines: [] };
+	const scope = data;
+	const lines = scopeWarningLines(scope.scope_warnings);
+	if (scope.reads_nothing === true) {
+		const stopped = typeof scope.stopped_reason === "string" && scope.stopped_reason ? ` Stopped: ${scope.stopped_reason}.` : "";
+		lines.push(`This rule reads no mail now: it cannot run as its author, or everything its scope names is at none of the organization's domains or no longer read.${stopped}`);
+	}
+	return { lines };
+}
+function errorDetails(payload) {
+	if (!isRecord(payload)) return {};
+	if (isRecord(payload.details)) return payload.details;
+	if (isRecord(payload.error) && isRecord(payload.error.details)) return payload.error.details;
+	return {};
+}
+/**
+* The hint for update-email-rule's 409 `email_rule_conflict` with
+* `details.reason` `version_moved`: the rule's version is no longer the
+* if_version that was sent, so nothing was saved.
+*/
+function versionMovedHint(payload, ruleId) {
+	const details = errorDetails(payload);
+	if (details.reason !== "version_moved") return void 0;
+	const id = typeof ruleId === "string" && ruleId ? ruleId : "<rule-id>";
+	const current = typeof details.current_version === "number" ? details.current_version : void 0;
+	const read = `Read it again with \`primitive email-rules get-email-rule ${id}\` and reapply your change to what it shows`;
+	return current === void 0 ? `Hint: the rule's version is not the if_version you sent, so nothing was saved, and the answer did not give its current version. ${read}.` : `Hint: the rule's current version is ${current}, not the if_version you sent, so nothing was saved. ${read}, then retry with --if-version ${current}.`;
+}
+const EXPECTATION_FLAG_NOTE = "Replaces any expect in --body-file or --raw-body. The exit code follows the answer's expectations; see --help-full.";
+const EMAIL_RULE_OPERATION_EXTENSIONS = {
+	testEmailRule: {
+		flags: {
+			"expect-match": Flags.string({
+				description: `An email the rule must match, by id: repeat the flag or give a comma list. Sets expect.match. ${EXPECTATION_FLAG_NOTE}`,
+				multiple: true,
+				exclusive: ["expect-file"]
+			}),
+			"expect-no-match": Flags.string({
+				description: `An email the rule must not match, by id: repeat the flag or give a comma list. Sets expect.no_match. ${EXPECTATION_FLAG_NOTE}`,
+				multiple: true,
+				exclusive: ["expect-file"]
+			}),
+			"expect-file": Flags.string({
+				description: "A JSON file holding the request's expect, such as {\"match\": [\"<email-id>\"], \"no_match\": [\"<email-id>\"]}. Not with --expect-match or --expect-no-match.",
+				exclusive: ["expect-match", "expect-no-match"]
+			})
+		},
+		bodyFields: expectBodyFields,
+		bodyProperties: ["expect"],
+		fallbackExitCode: (data) => {
+			const expectations = data?.expectations;
+			return expectations && expectations.passed !== true ? 1 : void 0;
+		},
+		report: testEmailRuleReport
+	},
+	createEmailRule: {
+		flags: { "expectations-file": Flags.string({ description: "A JSON file holding the emails the rule must match and must not, such as {\"match\": [\"<email-id>\"], \"no_match\": [\"<email-id>\"]}. Sets expectations, over any in --body-file or --raw-body; the answer judges them in expectations_check." }) },
+		bodyFields: expectationsBodyFields(false),
+		bodyProperties: ["expectations"],
+		report: writtenEmailRuleReport
+	},
+	updateEmailRule: {
+		flags: { "expectations-file": Flags.string({ description: "A JSON file holding the emails the rule must match and must not, such as {\"match\": [\"<email-id>\"], \"no_match\": [\"<email-id>\"]}, replacing its saved expectations; a file holding null removes them. Sets expectations, over any in --body-file or --raw-body; the answer judges them in expectations_check." }) },
+		bodyFields: expectationsBodyFields(true),
+		bodyProperties: ["expectations"],
+		report: writtenEmailRuleReport
+	},
+	getEmailRuleScope: {
+		flags: {},
+		report: emailRuleScopeReport
+	}
+};
+/** The classification in a listEmailRuleResults answer, or null. */
+function classificationOf(data) {
+	if (!isRecord(data) || !isRecord(data.classification)) return null;
+	return data.classification;
+}
+/** One line per fact: name, value(s) and confidence. */
+function classificationFactLines(classification) {
+	return Object.entries(isRecord(classification.facts) ? classification.facts : {}).map(([name, fact]) => formatFact(name, isRecord(fact) ? fact : {}));
+}
+/** Why there are no facts to print for an email. */
+function noFactsMessage(data) {
+	if (classificationOf(data)) return "This email's classification has no facts.";
+	return (isRecord(data) && Array.isArray(data.rules) ? data.rules : []).some((rule) => isRecord(rule) && isRecord(rule.decision) && rule.decision.detail_withheld === true) ? "No classification to show: this email's content cannot be read (withheld, failed to parse or discarded)." : "No classification for this email yet. It has not been classified (recent mail can take a while, so try again later), it will not be, or its content cannot be read.";
+}
 // src/oclif/endpoint-event-types.ts
 const EVENT_TYPES_FLAG_OPERATIONS = /* @__PURE__ */ new Set(["createEndpoint", "updateEndpoint"]);
 const EVENT_TYPES_FLAG_DESCRIPTION = "Event types this endpoint subscribes to, comma separated or repeated (sets rules.event_types). Omitting the subscription means every event type except the opt-in sent_email.* events, which an endpoint receives only when it lists them; sent_email.* expands to all four. Keep email.received in the list if the endpoint also handles inbound mail. On update, the endpoint's other rules are kept.";
@@ -2735,7 +3201,7 @@ function savedConnectedProfiles(configDir, exclude) {
 */
 async function otherProfiles(configDir, session, current) {
 	if (session) try {
-		const { connectedProfilesForSession } = await import("./machine-session-BG4getHB.js").then((n) => n.s);
+		const { connectedProfilesForSession } = await import("./machine-session-DD35Pfgd.js").then((n) => n.s);
 		return {
 			inSession: true,
 			profiles: connectedProfilesForSession(configDir, session, current)
@@ -2842,6 +3308,256 @@ function sentListOtherSendersNote(rows, self) {
 	const named = senders.length > 3 ? `${senders.slice(0, 3).join(", ")} and ${senders.length - 3} more` : senders.join(", ");
 	return `${count} of ${rows.length} rows were sent by another address in this organization (${named}) to ${own}; they are mail ${own} received, not its own sends. Rows with from_address ${own} are this address's sends; pass --from ${own} to list only those.`;
 }
+// src/oclif/browser-login-prompt.ts
+const { join: join$1 } = win32;
+/**
+* The program and arguments that open `url` in the default browser. On
+* Windows the link goes to the URL protocol handler directly: through `cmd
+* /c start` an unquoted `&` would end the command, cutting a link such as an
+* approval page's `?purpose=...&client=...` short.
+*/
+function browserCommand(url, platform = process.platform) {
+	if (platform === "darwin") return {
+		command: "open",
+		args: [url]
+	};
+	if (platform === "win32") return {
+		command: join$1(process.env.SystemRoot ?? "C:\\Windows", "System32", "rundll32.exe"),
+		args: ["url.dll,FileProtocolHandler", url]
+	};
+	return {
+		command: "xdg-open",
+		args: [url]
+	};
+}
+/** The link as an http or https URL, or null for anything else (a path, file:, a share). */
+function browsableUrl(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.href : null;
+	} catch {
+		return null;
+	}
+}
+/** Open an http or https link in the default browser; anything else is left to the printed link. */
+function openBrowser(url) {
+	const link = browsableUrl(url);
+	if (!link) return;
+	const { command, args } = browserCommand(link);
+	const child = spawn(command, args, {
+		detached: true,
+		stdio: "ignore"
+	});
+	child.on("error", () => void 0);
+	child.unref();
+}
+/**
+* The copy-URL hotkey needs raw keypresses from a terminal and a terminal
+* to show the hint on. Anything else (CI, agents, piped output) gets the
+* plain URL and never blocks on input.
+*/
+function canOfferCopyHotkey(input, output) {
+	return Boolean(input.isTTY && output.isTTY && typeof input.setRawMode === "function");
+}
+function formatBrowserLoginInstructions(params) {
+	const { copyHotkey, openedBrowser, start } = params;
+	const copyHint = copyHotkey ? " (c to copy)" : "";
+	const lines = [`Your sign-in code is: ${start.user_code}`];
+	if (openedBrowser) lines.push("Opening Primitive in your browser...", "", `Browser didn't open, or want a different one? Use this URL${copyHint}:`);
+	else lines.push("", `Open this URL in any browser to sign in${copyHint}:`);
+	lines.push(`  ${start.verification_uri_complete}`);
+	if (start.verification_uri !== start.verification_uri_complete) lines.push(`On another device, go to ${start.verification_uri} and enter ${start.user_code}.`);
+	lines.push("");
+	return `${lines.join("\n")}\n`;
+}
+/**
+* OSC 52 asks the terminal emulator itself to set the clipboard, so it
+* works over SSH, where a local clipboard command would copy on the
+* remote host instead of the machine the user is sitting at.
+*/
+function osc52Sequence(text) {
+	return `\u001b]52;c;${Buffer.from(text, "utf8").toString("base64")}\u0007`;
+}
+function nativeClipboardCommand() {
+	if (process.env.SSH_CONNECTION || process.env.SSH_TTY) return null;
+	if (process.platform === "darwin") return ["pbcopy", []];
+	if (process.platform === "win32") return ["clip", []];
+	if (process.env.WAYLAND_DISPLAY) return ["wl-copy", []];
+	if (process.env.DISPLAY) return ["xclip", ["-selection", "clipboard"]];
+	return null;
+}
+/**
+* Resolves false on any failure, including a tool that exits before
+* reading its input (EPIPE on stdin), so the caller falls back to OSC 52
+* instead of the error taking down login.
+*/
+function runClipboardCommand(command, args, text) {
+	return new Promise((resolve) => {
+		let inputFailed = false;
+		const child = spawn(command, args, { stdio: [
+			"pipe",
+			"ignore",
+			"ignore"
+		] });
+		child.on("error", () => resolve(false));
+		child.stdin.on("error", () => {
+			inputFailed = true;
+		});
+		child.on("close", (code) => resolve(code === 0 && !inputFailed));
+		child.stdin.end(text);
+	});
+}
+function copyWithNativeClipboard(text) {
+	const command = nativeClipboardCommand();
+	if (!command) return Promise.resolve(false);
+	return runClipboardCommand(command[0], command[1], text);
+}
+/**
+* Copies via the native clipboard when running locally and always emits
+* OSC 52 as well. Terminals without OSC 52 support (macOS Terminal.app)
+* are covered by the native path; SSH sessions are covered by OSC 52.
+*/
+async function copyToClipboard(text, output, native = copyWithNativeClipboard) {
+	output.write(osc52Sequence(text));
+	return await native(text) ? "native" : "terminal";
+}
+const CTRL_C = "";
+const CTRL_Z = "";
+/**
+* Listens for `c` while the CLI polls for browser approval. Raw mode turns
+* Ctrl+C and Ctrl+Z into plain input, so they are handled here: Ctrl+C is
+* re-raised as SIGINT, and Ctrl+Z restores the terminal, suspends with
+* SIGTSTP, and re-enters raw mode on SIGCONT. Several keys can arrive in
+* one chunk (pastes, SSH), so every character is checked. Returns a
+* disposer that restores the terminal.
+*/
+function listenForCopyHotkey(params) {
+	const { input, output, url } = params;
+	const copy = params.copy ?? copyToClipboard;
+	let disposed = false;
+	const copyUrl = () => {
+		copy(url, output).then((how) => {
+			if (disposed) return;
+			output.write(how === "native" ? "Copied the sign-in URL to your clipboard.\n" : "Sent the sign-in URL to your terminal's clipboard. If nothing was copied, select the URL above instead.\n");
+		});
+	};
+	const onContinue = () => {
+		if (!disposed) input.setRawMode?.(true);
+	};
+	const suspend = () => {
+		input.setRawMode?.(false);
+		process.once("SIGCONT", onContinue);
+		process.kill(process.pid, "SIGTSTP");
+	};
+	const onData = (chunk) => {
+		let wantsCopy = false;
+		for (const key of chunk.toString()) {
+			if (key === CTRL_C) {
+				dispose();
+				process.kill(process.pid, "SIGINT");
+				return;
+			}
+			if (key === CTRL_Z && process.platform !== "win32") {
+				if (wantsCopy) copyUrl();
+				suspend();
+				return;
+			}
+			if (key === "c" || key === "C") wantsCopy = true;
+		}
+		if (wantsCopy) copyUrl();
+	};
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		input.off("data", onData);
+		process.off("SIGCONT", onContinue);
+		input.setRawMode?.(false);
+		input.pause();
+	};
+	input.setRawMode?.(true);
+	input.on("data", onData);
+	input.resume();
+	return dispose;
+}
+// src/oclif/step-up-approval.ts
+const STEP_UP_HEADER = "Primitive-Step-Up";
+const CONTROL_CHARACTERS = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(31)}${String.fromCharCode(127)}]`);
+const STEP_UP_TOKEN_FLAG_DESCRIPTION = "One-time token from the approval page, for a request you already approved in the browser. Sent in the Primitive-Step-Up header.";
+const BROWSER_FLAG_DESCRIPTION = "Open the approval page in your browser. Use --no-browser to only print its link.";
+/** The error code of a refusal, whether or not it is still in its envelope. */
+function errorCode(payload) {
+	if (!payload || typeof payload !== "object") return void 0;
+	const inner = payload.error;
+	if (inner && typeof inner === "object" && typeof inner.code === "string") return inner.code;
+	const code = payload.code;
+	return typeof code === "string" ? code : void 0;
+}
+/** The approval link of a `step_up_required` refusal, if that is what it is. */
+function stepUpUrlOf(payload) {
+	if (errorCode(payload) !== "step_up_required") return void 0;
+	if (!payload || typeof payload !== "object") return void 0;
+	const details = payload.details;
+	if (!details || typeof details !== "object") return void 0;
+	const url = details.step_up_url;
+	return typeof url === "string" && url.length > 0 ? url : void 0;
+}
+/**
+* Send a request, and when the server asks the person to approve it, show
+* the approval link, open it where possible, wait for the token the page
+* shows, and send the request once more with it. Without a terminal to wait
+* in, the refusal is returned with its link, to rerun with --step-up-token.
+*/
+async function withApproval(attempt, io) {
+	const first = await attempt(io.stepUpToken);
+	if (first.ok) return first;
+	const stepUpUrl = stepUpUrlOf(first.payload);
+	if (!stepUpUrl || io.stepUpToken || !io.interactive) return {
+		...first,
+		...stepUpUrl ? { stepUpUrl } : {}
+	};
+	io.write(`Approve this request in your browser: ${stepUpUrl}\n`);
+	if (io.openBrowser) io.open(stepUpUrl);
+	io.write("After you confirm, the page shows a one-time token. Paste it here to finish.\n");
+	const token = (await io.prompt("Token: ")).trim();
+	if (!token) return {
+		...first,
+		stepUpUrl
+	};
+	if (CONTROL_CHARACTERS.test(token)) {
+		io.write("That token holds a line break or another control character, so it cannot be sent. Copy it again from the page.\n");
+		return {
+			...first,
+			stepUpUrl
+		};
+	}
+	return attempt(token);
+}
+/** The line to print when a refusal asks for an approval the command could not wait for. */
+function approveThenRerunHint(stepUpUrl) {
+	return `Approve this request in your browser: ${stepUpUrl}\nThen run the same command again with --step-up-token <token from the page>.\n`;
+}
+async function promptLine(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		return await rl.question(question);
+	} finally {
+		rl.close();
+	}
+}
+/** Approval in the terminal the command runs in: never under --json, and only with a terminal on both ends. */
+function terminalApprovalIo(options) {
+	return {
+		...options.stepUpToken ? { stepUpToken: options.stepUpToken } : {},
+		interactive: !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY),
+		openBrowser: options.openBrowser,
+		open: openBrowser,
+		prompt: promptLine,
+		write: (text) => process.stderr.write(text)
+	};
+}
 // src/oclif/api-command.ts
 const API_ERROR_CODES = {
 	accessDenied: "access_denied",
@@ -2896,6 +3612,11 @@ function collectHeaderFlags(parsedFlags, headerFlagToName) {
 function flagDescription(parameter) {
 	return parameter.description ?? parameter.name;
 }
+const STEP_UP_OPERATIONS = /* @__PURE__ */ new Set([]);
+/** Whether an operation takes the browser approval token. */
+function takesStepUp(operation) {
+	return STEP_UP_OPERATIONS.has(operation.sdkName) || operation.headerParams.some((p) => p.name === "Primitive-Step-Up");
+}
 const EMAIL_ID_NOT_SENT = "The id of the received email (from `primitive emails list`), not a sent email id. --id is accepted too.";
 const OPERATION_PATH_FLAGS = {
 	listEmailRuleResults: { id: {
@@ -2915,6 +3636,34 @@ const OPERATION_PATH_FLAGS = {
 		description: EMAIL_ID_NOT_SENT
 	} }
 };
+/** End a description with a full stop when it has no closing punctuation. */
+function sentence(text) {
+	const trimmed = text.trim();
+	return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+/**
+* The path parameter a command also takes as its first argument: the only
+* one, when the operation has exactly one (`emails get <id>`). Its flag stays
+* and is no longer required on its own.
+*/
+function positionalPathParameter(operation) {
+	return operation.pathParams.length === 1 ? operation.pathParams[0] : void 0;
+}
+/** The most rows a paged --limit fetches, in pages of the server's own cap. */
+const PAGED_LIMIT_MAX = 1e3;
+/**
+* The server's per-request cap on --limit for a list the CLI can page itself
+* (array data, a cursor in meta.cursor, a limit with a maximum), else
+* undefined. A larger --limit, up to PAGED_LIMIT_MAX, is then fetched in
+* pages of that size.
+*/
+function pagedLimitMaximum(operation) {
+	if (takesStepUp(operation)) return void 0;
+	const limit = operation.queryParams.find((p) => p.name === "limit");
+	if (!limit || typeof limit.maximum !== "number") return void 0;
+	if (!pagingFlagOverride(operation, limit)) return void 0;
+	return limit.maximum < 1e3 ? limit.maximum : void 0;
+}
 /** The flag a path or query parameter is read from. */
 function parameterFlagName(sdkName, parameterName) {
 	return (sdkName ? OPERATION_PATH_FLAGS[sdkName]?.[parameterName]?.flag : void 0) ?? flagName(parameterName);
@@ -2931,7 +3680,13 @@ function pagingFlagOverride(operation, parameter) {
 	if (operation.responseSchema?.type !== "array") return void 0;
 	const described = flagDescription(parameter).trim().replace(/\.$/, "");
 	if (parameter.name === "cursor") return { description: `${described}. The next page's cursor is meta.cursor, null on the last page: without --json it is printed on stderr as \`next cursor: <value>\`; with --json, add --envelope to get it, since the bare --json output is the data array alone.` };
-	if (parameter.name === "limit" && typeof parameter.maximum === "number") return { description: `${described}.${described.includes(String(parameter.maximum)) ? "" : ` At most ${parameter.maximum} per page;`} for more, page with --cursor.`.replace(". for more", ". For more") };
+	if (parameter.name === "limit" && typeof parameter.maximum === "number") {
+		if (parameter.maximum < 1e3) {
+			const single = operation.queryParams.some((p) => p.name === "wait") ? " (not with --wait or --since)" : "";
+			return { description: `${described}. The API returns at most ${parameter.maximum} per request; a larger --limit, up to ${PAGED_LIMIT_MAX}, is fetched in pages of ${parameter.maximum}${single}. For more, page with --cursor.` };
+		}
+		return { description: `${described}.${described.includes(String(parameter.maximum)) ? "" : ` At most ${parameter.maximum} per page;`} for more, page with --cursor.`.replace(". for more", ". For more") };
+	}
 }
 const numberFlag = Flags.custom({ async parse(input, _context, options) {
 	const trimmed = input.trim();
@@ -3025,10 +3780,10 @@ function extractBodyFields(schema) {
 * the natural reading is "use the flags above; --raw-body for
 * the leftovers below."
 */
-function renderRequestSchemaSummary(schema) {
+function renderRequestSchemaSummary(schema, setByFlags = []) {
 	const fields = extractBodyFields(schema);
 	if (fields.length === 0) return null;
-	const complex = fields.filter((f) => f.kind === "complex");
+	const complex = fields.filter((f) => f.kind === "complex" && !setByFlags.includes(f.name));
 	if (complex.length === 0) return null;
 	const nameWidth = Math.min(24, Math.max(...complex.map((f) => f.name.length)));
 	const descMax = 78;
@@ -3316,9 +4071,17 @@ function buildFlags(operation) {
 		flags.json = Flags.boolean({ description: "Print exactly one JSON document on stdout, on success and on failure, and nothing on stderr. Stdout keeps its usual shape: the data payload, or with --envelope the full response envelope (data plus meta, including meta.cursor, and empty-result hints in summary). The next-cursor line is not printed; use --envelope to page. A failure prints the error with exit_code. Without --json, the cursor and notices go to stderr." });
 		flags.envelope = Flags.boolean({ description: "Print the full response envelope, including pagination metadata such as meta.cursor. Defaults to printing only the data payload for backward compatibility." });
 	}
+	const positional = positionalPathParameter(operation);
+	const pageMaximum = pagedLimitMaximum(operation);
 	for (const parameter of [...operation.pathParams, ...operation.queryParams]) {
 		const override = OPERATION_PATH_FLAGS[operation.sdkName]?.[parameter.name];
-		flags[parameterFlagName(operation.sdkName, parameter.name)] = flagForParameter(parameter, override ?? pagingFlagOverride(operation, parameter));
+		flags[parameterFlagName(operation.sdkName, parameter.name)] = flagForParameter(parameter === positional ? {
+			...parameter,
+			required: false
+		} : pageMaximum !== void 0 && parameter.name === "limit" ? {
+			...parameter,
+			maximum: PAGED_LIMIT_MAX
+		} : parameter, override ?? pagingFlagOverride(operation, parameter));
 	}
 	const bodyFieldFlagToProperty = /* @__PURE__ */ new Map();
 	if (operation.hasJsonBody) {
@@ -3343,7 +4106,21 @@ function buildFlags(operation) {
 		}
 	}
 	const headerFlagToName = /* @__PURE__ */ new Map();
+	if (takesStepUp(operation)) {
+		for (const name of ["step-up-token", "browser"]) if (flags[name] !== void 0) throw new Error(`${operation.sdkName}: --${name} is both a parameter and the approval flag`);
+		flags["step-up-token"] = Flags.string({
+			description: STEP_UP_TOKEN_FLAG_DESCRIPTION,
+			aliases: [headerFlagName(STEP_UP_HEADER)]
+		});
+		flags.browser = Flags.boolean({
+			allowNo: true,
+			default: true,
+			description: BROWSER_FLAG_DESCRIPTION
+		});
+		headerFlagToName.set("step-up-token", STEP_UP_HEADER);
+	}
 	for (const parameter of operation.headerParams) {
+		if (parameter.name === "Primitive-Step-Up") continue;
 		const name = headerFlagName(parameter.name);
 		if (RESERVED_FLAG_NAMES.has(name)) continue;
 		if (flags[name] !== void 0) continue;
@@ -3360,6 +4137,11 @@ function buildFlags(operation) {
 		default: true,
 		description: ATTACHMENT_WAIT_FLAG_DESCRIPTION
 	});
+	const extension = OPERATION_EXTENSIONS[operation.sdkName];
+	for (const [name, flag] of Object.entries(extension?.flags ?? {})) {
+		if (flags[name] !== void 0) throw new Error(`${operation.sdkName}: --${name} is both a generated flag and a CLI extension flag`);
+		flags[name] = flag;
+	}
 	return {
 		flags,
 		bodyFieldFlagToProperty,
@@ -3444,6 +4226,7 @@ const OPERATION_HINTS = {
 	deleteMemory: "Tip: prefer `primitive memories delete <key> [--function <function-id>]` for the common delete path.",
 	searchMemories: "Tip: prefer `primitive memories search [prefix] [--metadata-only] [--function <function-id>]` for the common search path.",
 	startAgentSignup: "Tip: pass --terms-accepted. Capture the signup_token from the response and feed it to `primitive agent verify-agent-signup --signup-token <token> --verification-code <6-digit-code>` (the verify flag accepts --code as an alias). The high-level `primitive signup <email>` command walks an interactive user through both steps with friendlier prompts.",
+	testEmailRule: "Tip: --expect-match and --expect-no-match (or --expect-file) set expect, the emails the rule must match and must not. When no expect is sent, by these flags or in the body, a saved rule's saved expectations are judged instead. The exit code follows whichever expectations the answer judged: 1 when one failed; 1 when one is undecided and testing again will not decide it (its email cannot be found or read, or cannot be classified); 3 when the only undecided ones can be decided later (not classified yet, or a question unanswered), so test again later. Exit 1 also means the request failed. With --json, error.code tells these apart: expectations_failed, expectations_unresolvable, expectations_undecided (exit 3), or the API's own code. Without --json a readable report follows the JSON on stderr: warnings, how each condition held, the expectations, and the values each email that did not match was compared on.",
 	verifyAgentSignup: "Tip: pass --verification-code <code> (or --code; both work). The response carries OAuth tokens but not your assigned inbox domain; run `primitive domains list` (or `primitive whoami`) after success to see the managed *.primitive.email address that routes to this account."
 };
 const OPERATION_FLAG_ALIASES = { verifyAgentSignup: { verification_code: ["code"] } };
@@ -3451,9 +4234,11 @@ const OPERATION_EXTRA_BODY_FLAGS = { addDomain: { "mail-relay": {
 	property: "mail_relay",
 	description: "Keep your existing mailbox provider: the domain's MX points at a Primitive mail relay, which forwards mail to your mailboxes and stores a copy in Primitive. Requires mail relay to be enabled for your account. Google Workspace only for now."
 } } };
+const OPERATION_EXTENSIONS = { ...EMAIL_RULE_OPERATION_EXTENSIONS };
 const MAIL_RELAY_NOT_ENABLED_MESSAGE = "Mail relay is not enabled for this account, so the domain was not added. Retry without --mail-relay to point the domain's MX at Primitive directly, or ask Primitive to enable mail relay for your account.";
 const MAIL_RELAY_UNAVAILABLE_MESSAGE = "No mail relay is available on this API server right now, so the domain was not added. Retry later, or retry without --mail-relay to point the domain's MX at Primitive directly.";
 const OPERATION_ERROR_HINTS = {
+	updateEmailRule: (code, _body, payload, path) => code === "email_rule_conflict" ? versionMovedHint(payload, path?.id) : void 0,
 	verifyDomain: (code, _body, payload) => code === "dns_verification_failed" ? domainVerificationFailedHint(payload) : void 0,
 	addDomain: (code, body) => {
 		if (code === "mail_relay_unavailable") return MAIL_RELAY_UNAVAILABLE_MESSAGE;
@@ -3474,20 +4259,35 @@ const OPERATION_SUCCESS_HOOKS = { verifyAgentSignup: ({ envelope, configDir, api
 function createOperationCommand(operation) {
 	const { flags, bodyFieldFlagToProperty, headerFlagToName } = buildFlags(operation);
 	const baseDescription = operation.description !== null && operation.description !== void 0 ? canonicalizeCliReferences(operation.description) : `${operation.method} ${operation.path}`;
-	const schemaSummary = operation.hasJsonBody ? renderRequestSchemaSummary(operation.requestSchema) : null;
+	const schemaSummary = operation.hasJsonBody ? renderRequestSchemaSummary(operation.requestSchema, OPERATION_EXTENSIONS[operation.sdkName]?.bodyProperties) : null;
 	const hint = OPERATION_HINTS[operation.sdkName];
 	const descriptionWithSchema = schemaSummary ? `${baseDescription}\n\n${schemaSummary}` : baseDescription;
 	const fullDescription = hint ? `${descriptionWithSchema}\n\n${hint}` : descriptionWithSchema;
 	const flagNames = Object.keys(flags);
+	const extension = OPERATION_EXTENSIONS[operation.sdkName];
+	const positional = positionalPathParameter(operation);
+	const positionalFlag = positional ? parameterFlagName(operation.sdkName, positional.name) : void 0;
 	class OperationCommand extends Command {
 		static description = fullDescription;
 		static flags = flags;
+		static args = positional && positionalFlag ? { [positionalFlag]: Args.string({
+			description: `${sentence(OPERATION_PATH_FLAGS[operation.sdkName]?.[positional.name]?.description ?? positional.description ?? positional.name)} The same as --${positionalFlag}; give one of the two.`,
+			required: false
+		}) } : {};
 		static summary = operation.summary ?? `${operation.method} ${operation.path}`;
 		async run() {
-			const { flags } = await this.parse(OperationCommand).catch((error) => {
+			const { args, flags } = await this.parse(OperationCommand).catch((error) => {
 				throw withFlagSuggestion(error, flagNames);
 			});
 			const parsedFlags = flags;
+			if (positionalFlag) {
+				const fromArgument = args[positionalFlag];
+				const fromFlag = parsedFlags[positionalFlag];
+				if (fromArgument !== void 0 && fromFlag !== void 0 && String(fromArgument) !== String(fromFlag)) throw new Errors.CLIError(`Give the ${positionalFlag} once: as the first argument or with --${positionalFlag}, not both with different values.`, { exit: 2 });
+				const value = fromFlag ?? fromArgument;
+				if (value === void 0 || value === "") throw new Errors.CLIError(`Missing the ${positionalFlag}: pass it as the first argument or with --${positionalFlag}.`, { exit: 2 });
+				parsedFlags[positionalFlag] = value;
+			}
 			const headers = collectHeaderFlags(parsedFlags, headerFlagToName);
 			if ([
 				"startAgentSignup",
@@ -3504,6 +4304,11 @@ function createOperationCommand(operation) {
 				if (operation.hasJsonBody) {
 					const explicit = readJsonBody(parsedFlags);
 					const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
+					const extensionFlagFor = /* @__PURE__ */ new Map();
+					for (const field of extension?.bodyFields?.(parsedFlags) ?? []) {
+						overrides[field.property] = field.value;
+						extensionFlagFor.set(field.property, field.flag);
+					}
 					if (Object.keys(overrides).length > 0) {
 						if (explicit === void 0) body = overrides;
 						else if (explicit !== null && typeof explicit === "object" && !Array.isArray(explicit)) body = {
@@ -3512,7 +4317,7 @@ function createOperationCommand(operation) {
 						};
 						else {
 							const explicitKind = explicit === null ? "null" : Array.isArray(explicit) ? "array" : typeof explicit;
-							const overrideFlags = Object.keys(overrides).map((p) => `--${flagName(p)}`).join(", ");
+							const overrideFlags = Object.keys(overrides).map((p) => extensionFlagFor.get(p) ?? `--${flagName(p)}`).join(", ");
 							throw new Errors.CLIError(`--raw-body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --raw-body and rely on the per-field flags, or move every field into the JSON --raw-body and drop the flags.`);
 						}
 					} else body = explicit;
@@ -3533,16 +4338,84 @@ function createOperationCommand(operation) {
 				const replyStateSurface = replyStateSurfaceForOperation(operation.sdkName, query);
 				const automatedSurface = automatedSurfaceForOperation(operation.sdkName, query);
 				const fromVerified = fromVerifiedExpectation(operation.sdkName, query);
-				const callOperation = () => operationFn({
-					body,
-					client: apiClient.client,
-					...Object.keys(headers).length > 0 ? { headers } : {},
-					parseAs: operation.binaryResponse ? "blob" : "auto",
-					path: collectValues(operation.pathParams, parsedFlags, operation.sdkName),
-					query,
-					responseStyle: "fields"
-				});
-				const result = ATTACHMENT_WAIT_OPERATIONS.has(operation.sdkName) ? await withAttachmentWait(callOperation, {
+				const callOperation = (stepUpToken, pageQuery = query) => {
+					const sent = stepUpToken ? {
+						...headers,
+						[STEP_UP_HEADER]: stepUpToken
+					} : headers;
+					return operationFn({
+						body,
+						client: apiClient.client,
+						...Object.keys(sent).length > 0 ? { headers: sent } : {},
+						parseAs: operation.binaryResponse ? "blob" : "auto",
+						path: collectValues(operation.pathParams, parsedFlags, operation.sdkName),
+						query: pageQuery,
+						responseStyle: "fields"
+					});
+				};
+				let stepUpUrl;
+				const callWithApproval = async () => {
+					const approved = await withApproval(async (token) => {
+						const attempt = await callOperation(token);
+						return {
+							ok: !attempt.error,
+							payload: attempt.error ? extractErrorPayload(attempt.error) : void 0,
+							attempt
+						};
+					}, terminalApprovalIo({
+						stepUpToken: typeof parsedFlags["step-up-token"] === "string" ? parsedFlags["step-up-token"] : void 0,
+						openBrowser: parsedFlags.browser !== false,
+						json: parsedFlags.json === true
+					}));
+					stepUpUrl = approved.stepUpUrl;
+					return approved.attempt;
+				};
+				const pageMaximum = pagedLimitMaximum(operation);
+				const wanted = typeof query.limit === "number" ? query.limit : 0;
+				const paged = pageMaximum !== void 0 && wanted > pageMaximum;
+				if (paged) {
+					const single = typeof query.wait === "number" && query.wait > 0 ? "--wait" : query.since !== void 0 ? "--since" : void 0;
+					if (single) throw new Errors.CLIError(`${single} takes a --limit of at most ${pageMaximum}, since it reads one page; a larger --limit is fetched in several requests.`, { exit: 2 });
+				}
+				let pagingNote;
+				const callPaged = async () => {
+					const max = pageMaximum ?? wanted;
+					const rows = [];
+					let sentCursor = query.cursor;
+					let last = await callOperation(void 0, {
+						...query,
+						limit: Math.min(max, wanted)
+					});
+					const budget = Math.ceil(wanted / max) + 20;
+					for (let requests = 1;; requests += 1) {
+						if (last.error) return last;
+						const envelope = last.data;
+						const page = Array.isArray(envelope?.data) ? envelope.data : [];
+						rows.push(...page);
+						const cursor = envelope?.meta?.cursor ?? void 0;
+						const exhausted = Boolean(cursor) && cursor !== sentCursor && rows.length < wanted && requests >= budget;
+						if (exhausted) pagingNote = `Stopped after ${requests} requests with ${rows.length} of ${wanted}; more may remain. Continue with --cursor ${cursor}.`;
+						if (!cursor || cursor === sentCursor || rows.length >= wanted || exhausted) return {
+							...last,
+							data: {
+								...envelope ?? {},
+								data: rows,
+								meta: {
+									...envelope?.meta ?? {},
+									limit: wanted,
+									cursor: cursor ?? null
+								}
+							}
+						};
+						sentCursor = cursor;
+						last = await callOperation(void 0, {
+							...query,
+							cursor,
+							limit: Math.min(max, wanted - rows.length)
+						});
+					}
+				};
+				const result = paged ? await callPaged() : takesStepUp(operation) ? await callWithApproval() : ATTACHMENT_WAIT_OPERATIONS.has(operation.sdkName) ? await withAttachmentWait(callOperation, {
 					wait: parsedFlags.wait !== false,
 					errorCode: (error) => extractErrorCode(extractErrorPayload(error)),
 					onFirstWait: () => {
@@ -3552,8 +4425,9 @@ function createOperationCommand(operation) {
 				if (result.error) {
 					const errorPayload = extractErrorPayload(result.error);
 					writeErrorWithHints(errorPayload, result.response);
-					const operationErrorHint = OPERATION_ERROR_HINTS[operation.sdkName]?.(extractErrorCode(errorPayload), body, errorPayload);
+					const operationErrorHint = OPERATION_ERROR_HINTS[operation.sdkName]?.(extractErrorCode(errorPayload), body, errorPayload, collectValues(operation.pathParams, parsedFlags, operation.sdkName));
 					if (operationErrorHint) process.stderr.write(`${operationErrorHint}\n`);
+					if (stepUpUrl) process.stderr.write(approveThenRerunHint(stepUpUrl));
 					if (replyStateSurface && isAwaitingRejectedError(errorPayload)) process.stderr.write(`${awaitingRejectedError(replyStateSurface).message}\n`);
 					if (automatedSurface && isAutomatedRejectedError(errorPayload)) process.stderr.write(`${automatedRejectedError(automatedSurface).message}\n`);
 					surfaceUnauthorizedHint({
@@ -3625,6 +4499,7 @@ function createOperationCommand(operation) {
 				const withEnvelope = parsedFlags.envelope === true;
 				const cursor = envelope?.meta?.cursor;
 				if (cursor && !jsonOutput) process.stderr.write(`next cursor: ${cursor}\n`);
+				if (pagingNote && !jsonOutput) process.stderr.write(`${pagingNote}\n`);
 				const summary = [];
 				if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
 					const hint = EMPTY_RESULT_HINTS[operation.sdkName];
@@ -3655,7 +4530,40 @@ function createOperationCommand(operation) {
 					const detail = hookError instanceof Error ? hookError.message : String(hookError);
 					process.stderr.write(`Warning: ${operation.sdkName} succeeded but its post-success hook threw (${detail}). The response below is still valid; act on it manually.\n`);
 				}
-				this.log(JSON.stringify(jsonOutput && withEnvelope ? operationJsonDocument(envelope, summary) : operationOutputPayload(envelope, withEnvelope), null, 2));
+				let report;
+				let reportError;
+				try {
+					report = extension?.report?.(envelope?.data, {
+						body,
+						path: collectValues(operation.pathParams, parsedFlags, operation.sdkName)
+					});
+				} catch (error) {
+					reportError = error instanceof Error ? error.message : String(error);
+					let fallback;
+					try {
+						fallback = extension?.fallbackExitCode?.(envelope?.data);
+					} catch {
+						fallback = 1;
+					}
+					if (fallback) report = {
+						lines: [],
+						exitCode: fallback,
+						error: {
+							code: "expectations_not_passed",
+							message: "The answer's expectations did not all pass; read expectations in the answer."
+						}
+					};
+				}
+				let printed = jsonOutput && withEnvelope ? operationJsonDocument(envelope, summary) : operationOutputPayload(envelope, withEnvelope);
+				if (jsonOutput && report?.exitCode && report.error && printed !== null && typeof printed === "object" && !Array.isArray(printed)) printed = {
+					...printed,
+					error: report.error
+				};
+				this.log(JSON.stringify(printed, null, 2));
+				if (reportError !== void 0) process.stderr.write(`Warning: ${operation.sdkName} succeeded but its report could not be built (${reportError}). The JSON above is the full answer; read it rather than the exit code.\n`);
+				if (report && !jsonOutput) for (const line of report.lines) process.stderr.write(`${line}\n`);
+				if (reportError !== void 0 && report?.exitCode && !jsonOutput) process.stderr.write(`The answer's expectations did not all pass, so the command exits ${report.exitCode}.\n`);
+				if (report?.exitCode) process.exitCode = report.exitCode;
 			});
 		}
 	}
@@ -3672,4 +4580,4 @@ const EMPTY_RESULT_HINTS = {
 function canonicalizeCliReferences(description) {
 	return description.replaceAll("`primitive emails:latest`", "`primitive emails latest`").replaceAll("`primitive describe emails:get-email | jq '.responseSchema.properties'`", "`primitive describe emails:get | jq '.responseSchema.properties'`");
 }
-export { deriveSendIdempotencyKey as $, wakeRelationship as A, ATTACHMENT_WAIT_MAX_MS as At, readEmailInteraction as B, CliOrgRefusedError as Bt, readThreadContext as C, currentMailSessionKey as Ct, skillFirstLine as D, formatAlreadySentNotice as Dt, serverRelationship as E, runtimeSessionVariableList as Et, readPendingMail as F, createCliApiClient as Ft, MAX_SEND_WAIT_TIMEOUT_MS as G, replyInteractionWarning as H, fetchCliOrgs as Ht, recordPendingMail as I, refreshStoredCliCredentials as It, assertValidIdempotencyKey as J, SEND_OUTCOME_HELP as K, removePendingMail as L, refuseOrgSelectionForProfile as Lt, clearConsumedPendingMail as M, ConnectedAgentKeyRequiredError as Mt, clearReadPendingMail as N, SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE as Nt, wakeReadCommand as O, withFlagSuggestion as Ot, pendingMailPath as P, createAuthenticatedCliApiClient as Pt, classifySendError as Q, interactionHumanLine as R, resolveCliApiRequestConfig as Rt, latestOwnOutbound as S, loadSkillLine as St, serverMuted as T, detectRuntimeSession as Tt, wakeInteractionSentence as U, revokeUserLogin as Ut, replyExpectation as V, credentialsFromUserLogin as Vt, IDEMPOTENCY_KEY_FLAG_DESCRIPTION as W, switchCurrentOrg as Wt, buildThrownSendFailureEnvelope as X, buildFollowUpCommand as Y, checkPriorReplies as Z, explainPendingMailNotFound as _, cliInvocation as _t, createOperationCommand as a, formatSendFailureSummary as at, displayAddress as b, generatedAgentName as bt, formatErrorPayload as c, reportSendCommandResult as ct, isGrantRefusal as d, sendWaitClampNotice as dt, excludeSignalReplies as et, parameterFlagName as f, sentHistoryWindowStart as ft, writeErrorWithHints as g, DEFAULT_ENROLL_NAME as gt, surfaceUnauthorizedHint as h, thrownErrorExitCode as ht, TIME_FLAG_DESCRIPTION as i, formatPriorRepliesWarning as it, claimPendingMail as j, withAttachmentWait as jt, wakeRecipientField as k, ATTACHMENT_WAIT_FLAG_DESCRIPTION as kt, hasControlCharacter as l, sendIdentityFields as lt, runWithTiming as m, successfulSendOutcome as mt, API_ERROR_CODES as n, formatDeletedEarlierSendNotice as nt, extractErrorCode as o, formatSendRecordFailureSummary as ot, readTextFileFlag as p, serializeErrorPayload as pt, apiResultHttpStatus as q, OPERATION_PATH_FLAGS as r, formatPriorRepliesCheckSkipped as rt, extractErrorPayload as s, priorRepliesThatWentOut as st, API_BASE_URL_FLAG_DESCRIPTION as t, followUpCommandPrefix as tt, headerFlagName as u, sendOutcomeExitCode as ut, bareAddress$1 as v, connectNextSteps as vt, sentInThread as w, detectAgentRuntime as wt, formatMailWakeLine as x, identitySuggestions as xt, describeWake as y, defaultConnectionName as yt, interactionNextActions as z, selectedOrgFromEnv as zt };
+export { replyExpectation as $, refuseOrgSelectionForProfile as $t, bareAddress$1 as A, connectNextSteps as At, wakeReadCommand as B, withFlagSuggestion as Bt, terminalApprovalIo as C, sendWaitClampNotice as Ct, listenForCopyHotkey as D, thrownErrorExitCode as Dt, formatBrowserLoginInstructions as E, successfulSendOutcome as Et, readThreadContext as F, currentMailSessionKey as Ft, clearReadPendingMail as G, ATTACHMENT_WAIT_FLAG_DESCRIPTION as Gt, wakeRelationship as H, classificationOf as Ht, sentInThread as I, detectAgentRuntime as It, recordPendingMail as J, ConnectedAgentKeyRequiredError as Jt, pendingMailPath as K, ATTACHMENT_WAIT_MAX_MS as Kt, serverMuted as L, detectRuntimeSession as Lt, displayAddress as M, generatedAgentName as Mt, formatMailWakeLine as N, identitySuggestions as Nt, openBrowser as O, DEFAULT_ENROLL_NAME as Ot, latestOwnOutbound as P, loadSkillLine as Pt, readEmailInteraction as Q, refreshStoredCliCredentials as Qt, serverRelationship as R, runtimeSessionVariableList as Rt, promptLine as S, sendOutcomeExitCode as St, canOfferCopyHotkey as T, serializeErrorPayload as Tt, claimPendingMail as U, isEmailId as Ut, wakeRecipientField as V, classificationFactLines as Vt, clearConsumedPendingMail as W, noFactsMessage as Wt, interactionHumanLine as X, createAuthenticatedCliApiClient as Xt, removePendingMail as Y, SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE as Yt, interactionNextActions as Z, createCliApiClient as Zt, writeErrorWithHints as _, formatSendFailureSummary as _t, createOperationCommand as a, revokeUserLogin as an, apiResultHttpStatus as at, STEP_UP_TOKEN_FLAG_DESCRIPTION as b, reportSendCommandResult as bt, formatErrorPayload as c, buildThrownSendFailureEnvelope as ct, isGrantRefusal as d, deriveSendIdempotencyKey as dt, resolveCliApiRequestConfig as en, replyInteractionWarning as et, parameterFlagName as f, excludeSignalReplies as ft, takesStepUp as g, formatPriorRepliesWarning as gt, surfaceUnauthorizedHint as h, formatPriorRepliesCheckSkipped as ht, TIME_FLAG_DESCRIPTION as i, fetchCliOrgs as in, SEND_OUTCOME_HELP as it, describeWake as j, defaultConnectionName as jt, explainPendingMailNotFound as k, cliInvocation as kt, hasControlCharacter as l, checkPriorReplies as lt, runWithTiming as m, formatDeletedEarlierSendNotice as mt, API_ERROR_CODES as n, CliOrgRefusedError as nn, IDEMPOTENCY_KEY_FLAG_DESCRIPTION as nt, extractErrorCode as o, switchCurrentOrg as on, assertValidIdempotencyKey as ot, readTextFileFlag as p, followUpCommandPrefix as pt, readPendingMail as q, withAttachmentWait as qt, OPERATION_PATH_FLAGS as r, credentialsFromUserLogin as rn, MAX_SEND_WAIT_TIMEOUT_MS as rt, extractErrorPayload as s, buildFollowUpCommand as st, API_BASE_URL_FLAG_DESCRIPTION as t, selectedOrgFromEnv as tn, wakeInteractionSentence as tt, headerFlagName as u, classifySendError as ut, BROWSER_FLAG_DESCRIPTION as v, formatSendRecordFailureSummary as vt, withApproval as w, sentHistoryWindowStart as wt, approveThenRerunHint as x, sendIdentityFields as xt, STEP_UP_HEADER as y, priorRepliesThatWentOut as yt, skillFirstLine as z, formatAlreadySentNotice as zt };