primcli 1.40.0 → 1.42.0

package/dist/{sdk.gen-CgKZwHs3.js → interaction-actions-D5o_frTT.js}

@@ -1,5 +1,8 @@
 import { b as __exportAll } from "./repeats-CoK0tpCK-Bx7nmyRi.js";
-import { m as createConfig, p as createClient } from "./connected-agent-profile-8tpOMdq3.js";
+import { C as resolveCliAuth, G as createConfig, S as normalizeApiBaseUrl, T as saveSignupCredentials, U as PrimitiveApiClient, V as requireDefaultLoginProfile, W as createClient, _ as deleteCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, i as loadCliConfig, m as cliAccessTokenExpiresAt, p as acquireCliCredentialsLock, w as saveCliCredentials, x as loadCliCredentials, y as detectPrimitiveKeyEnvMisname } from "./cli-config-BoZ1lMUQ.js";
+import { Command, Errors, Flags } from "@oclif/core";
+import { readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 //#region ../packages/api-core/src/api/client.gen.ts
 const client = createClient(createConfig({ baseUrl: "https://api.primitive.dev/v1" }));
 //#endregion
@@ -1018,6 +1021,13 @@ const discardEmailContent = (options) => (options.client ?? client).post({
 * merged here; that normalization is model-specific and left to the
 * caller.
 *
+* Pass `since` for an incremental read. `since=start` returns the
+* full conversation plus a `cursor`. Sending that `cursor` back as
+* `since` returns only the messages created or changed after it,
+* oldest first, with the same per-message shape, and a new
+* `cursor`. Without `since` the response carries no `cursor` and
+* no per-message `status`.
+*
 */
 const getConversation = (options) => (options.client ?? client).get({
 	security: [{
@@ -3278,4 +3288,1820 @@ const provisionMemberAddress = (options) => (options.client ?? client).put({
 	}
 });
 //#endregion
-export { putAgentContactPolicy as $, getRepeatingSend as A, listEmails as B, getEmail as C, updateFunction as Ct, getInboxStatus as D, updateWakeSchedule as Dt, getFunctionTestRunTrace as E, updateWakeAuthorization as Et, listAgentNetworks as F, listRoutes as G, listFunctionLogs as H, listContacts as I, listWakeDispatches as J, listSentEmails as K, listDefaultNetworkAgents as L, getThread as M, getWakeSchedule as N, getMemory as O, verifyAgentClaim as Ot, listAgentContacts as P, putAgentContact as Q, listDefaultNetworkMembers as R, getDefaultNetworkAgent as S, updateDefaultNetworkMember as St, getFunctionRouting as T, updateRoute as Tt, listFunctions as U, listEndpoints as V, listRepeatingSends as W, pollCliLogin as X, listWakeSchedules as Y, pullWebhookEvent as Z, getAccount as _, startAgentSignup as _t, createEndpoint as a, resendAgentSignupVerification as at, getConversation as b, testFunction as bt, createWakeAuthorization as c, searchEmails as ct, deleteContact as d, sendEmail as dt, putContact as et, deleteMemory as f, setFunctionRoute as ft, downloadEmailAttachmentPart as g, startAgentClaim as gt, deleteWakeSchedule as h, simulateRoute as ht, completeWebhookEvent as i, replyToEmail as it, getSentEmail as j, getOrgRoutingTopology as k, verifyAgentSignup as kt, createWakeSchedule as l, searchMemories as lt, deleteWakeAuthorization as m, setMemory as mt, checkDefaultNetworkContactAdmission as n, removeDefaultNetworkMember as nt, createFunction as o, runWakeSchedule as ot, deleteRoute as p, setFunctionSecret as pt, listWakeAuthorizations as q, cliLogout as r, reorderRoutes as rt, createRoute as s, sdk_gen_exports as st, addDefaultNetworkMember as t, redeemCreditCode as tt, deleteAgentContact as u, semanticSearch as ut, getAgentContactPolicy as v, startCliLogin as vt, getFunction as w, updateRepeatingSend as wt, getCreditBalance as x, unsetFunctionRoute as xt, getContact as y, stopRepeatFromEmail as yt, listDomains as z };
+//#region src/oclif/api-client.ts
+const API_HEADERS_ENV = "PRIMITIVE_API_HEADERS";
+const OAUTH_REFRESH_SKEW_MS = 60 * 1e3;
+const SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE = "Saved Primitive CLI OAuth session expired or was revoked. Run `primitive signin` to authenticate again.";
+function mergeHeaders(...headers) {
+	const merged = {};
+	for (const headerSet of headers) {
+		if (!headerSet) continue;
+		for (const [name, value] of Object.entries(headerSet)) merged[name] = value;
+	}
+	return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function parseHeadersJson(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Errors.CLIError(`${API_HEADERS_ENV} must be valid JSON object syntax: ${detail}`, { exit: 1 });
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Errors.CLIError(`${API_HEADERS_ENV} must be a JSON object.`, { exit: 1 });
+	const headers = {};
+	for (const [rawName, rawValue] of Object.entries(parsed)) {
+		const name = validateCliHeaderName(rawName);
+		if (typeof rawValue !== "string") throw new Errors.CLIError(`${API_HEADERS_ENV}.${name} must be a string.`, { exit: 1 });
+		headers[name] = validateCliHeaderValue(rawValue, name);
+	}
+	return headers;
+}
+function cliApiHeadersFromEnv(env = process.env) {
+	const rawGenericHeaders = env[API_HEADERS_ENV]?.trim();
+	return rawGenericHeaders ? parseHeadersJson(rawGenericHeaders) : void 0;
+}
+function resolveCliApiRequestConfig(params) {
+	if ((params.env ?? process.env)["PRIMITIVE_AGENT_PROFILE"]?.trim()) {
+		const auth = resolveCliAuth(params);
+		return {
+			apiBaseUrl: auth.apiBaseUrl,
+			resolvedApiBaseUrl: auth.apiBaseUrl,
+			baseUrlOverridden: params.apiBaseUrl !== void 0,
+			environmentName: null
+		};
+	}
+	const currentEnvironment = resolveConfigEnvironment(loadCliConfig(params.configDir));
+	const configuredApiBaseUrl = currentEnvironment?.config.api_base_url;
+	if (currentEnvironment !== null && currentEnvironment.name !== "default" && params.apiBaseUrl === void 0 && configuredApiBaseUrl === void 0) throw new Errors.CLIError(`The active Primitive CLI environment \`${currentEnvironment.name}\` does not specify an api_base_url. Set one with \`primitive config set --environment ${currentEnvironment.name} --api-base-url https://...\`, or switch to a different environment with \`primitive config use <name>\`. Refusing to fall back to the production default for a non-default environment.`, { exit: 1 });
+	const apiBaseUrl = params.apiBaseUrl !== void 0 ? normalizeApiBaseUrl(params.apiBaseUrl) : configuredApiBaseUrl;
+	return {
+		apiBaseUrl,
+		baseUrlOverridden: apiBaseUrl !== void 0,
+		environmentName: currentEnvironment?.name ?? null,
+		headers: mergeHeaders(currentEnvironment?.config.headers, cliApiHeadersFromEnv(params.env)),
+		resolvedApiBaseUrl: normalizeApiBaseUrl(apiBaseUrl)
+	};
+}
+function createCliApiClient(params) {
+	const requestConfig = resolveCliApiRequestConfig(params);
+	return {
+		apiClient: new PrimitiveApiClient({
+			apiKey: params.apiKey,
+			apiBaseUrl: requestConfig.resolvedApiBaseUrl,
+			headers: requestConfig.headers
+		}),
+		requestConfig
+	};
+}
+function oauthTokenEndpoint(apiBaseUrl) {
+	const url = new URL(apiBaseUrl);
+	url.pathname = "/oauth/token";
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
+function shouldRefresh(credentials, now) {
+	const expiresAt = Date.parse(credentials.expires_at);
+	if (!Number.isFinite(expiresAt)) return true;
+	return expiresAt <= now() + OAUTH_REFRESH_SKEW_MS;
+}
+function isOAuthRefreshSuccess(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const row = value;
+	return typeof row.access_token === "string" && typeof row.refresh_token === "string" && row.token_type === "Bearer" && typeof row.expires_in === "number" && Number.isFinite(row.expires_in) && row.expires_in > 0;
+}
+function oauthErrorCode(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const raw = value.error;
+	return typeof raw === "string" ? raw : null;
+}
+function oauthErrorDescription(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const raw = value.error_description;
+	return typeof raw === "string" && raw.trim() ? raw : null;
+}
+async function refreshStoredCliCredentials(params) {
+	const now = params.now ?? Date.now;
+	if (!shouldRefresh(params.credentials, now)) return params.credentials;
+	let releaseLock;
+	try {
+		if (!params.credentialsLockHeld) try {
+			releaseLock = acquireCliCredentialsLock(params.configDir);
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			throw new Errors.CLIError(detail, { exit: 1 });
+		}
+		const current = loadCliCredentials(params.configDir);
+		if (!current) throw new Errors.CLIError("Saved Primitive CLI OAuth session is no longer available. Run `primitive signin` to authenticate again.", { exit: 1 });
+		if (!shouldRefresh(current, now)) return current;
+		const fetchImpl = params.fetch ?? fetch;
+		const body = new URLSearchParams({
+			client_id: current.oauth_client_id,
+			grant_type: "refresh_token",
+			refresh_token: current.refresh_token
+		});
+		let response;
+		try {
+			response = await fetchImpl(oauthTokenEndpoint(params.apiBaseUrl), {
+				body,
+				headers: {
+					...params.headers ?? {},
+					"content-type": "application/x-www-form-urlencoded"
+				},
+				method: "POST"
+			});
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			throw new Errors.CLIError(`Could not refresh saved Primitive CLI OAuth credentials: ${detail}`, { exit: 1 });
+		}
+		const payload = await response.json().catch(() => null);
+		if (!response.ok) {
+			const code = oauthErrorCode(payload);
+			const description = oauthErrorDescription(payload);
+			if (code === "invalid_grant") {
+				deleteCliCredentials(params.configDir);
+				throw new Errors.CLIError(SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE, { exit: 1 });
+			}
+			throw new Errors.CLIError(`Could not refresh saved Primitive CLI OAuth credentials${description ? `: ${description}` : "."}`, { exit: 1 });
+		}
+		if (!isOAuthRefreshSuccess(payload)) throw new Errors.CLIError("Primitive OAuth token endpoint returned an unexpected refresh response.", { exit: 1 });
+		const next = {
+			...current,
+			access_token: payload.access_token,
+			expires_at: cliAccessTokenExpiresAt(payload.expires_in, now),
+			refresh_token: payload.refresh_token,
+			token_type: payload.token_type
+		};
+		saveCliCredentials(params.configDir, next);
+		return next;
+	} finally {
+		releaseLock?.();
+	}
+}
+async function createAuthenticatedCliApiClient(params) {
+	const requestConfig = resolveCliApiRequestConfig(params);
+	let auth = resolveCliAuth({
+		apiKey: params.apiKey,
+		apiBaseUrl: requestConfig.apiBaseUrl,
+		configDir: params.configDir,
+		env: params.env
+	});
+	if (auth.apiKey === void 0) {
+		const hint = detectPrimitiveKeyEnvMisname(params.env ?? process.env);
+		if (hint) process.stderr.write(`${hint}\n`);
+	}
+	if (auth.source === "stored" && auth.credentials) {
+		const refreshed = await refreshStoredCliCredentials({
+			apiBaseUrl: auth.apiBaseUrl,
+			configDir: params.configDir,
+			credentials: auth.credentials,
+			credentialsLockHeld: params.credentialsLockHeld,
+			fetch: params.fetch,
+			headers: requestConfig.headers,
+			now: params.now
+		});
+		auth = {
+			...auth,
+			apiKey: refreshed.access_token,
+			credentials: refreshed
+		};
+	}
+	return {
+		apiClient: new PrimitiveApiClient({
+			apiKey: auth.apiKey,
+			apiBaseUrl: auth.apiBaseUrl,
+			headers: auth.connectedAgent ? void 0 : requestConfig.headers
+		}),
+		auth,
+		baseUrlOverridden: requestConfig.baseUrlOverridden,
+		requestConfig
+	};
+}
+//#endregion
+//#region src/oclif/attachment-wait.ts
+/** Generated download commands that wait for attachment content by default. */
+const ATTACHMENT_WAIT_OPERATIONS = new Set([
+	"downloadAttachments",
+	"downloadEmailAttachmentPart",
+	"downloadSentAttachmentPart"
+]);
+/** Longest a download command waits for attachment content, in total. */
+const ATTACHMENT_WAIT_MAX_MS = 6e4;
+const INITIAL_DELAY_MS = 1e3;
+const MAX_DELAY_MS = 8e3;
+const ATTACHMENT_WAIT_FLAG_DESCRIPTION = `Wait and retry while the attachment content is not ready yet (attachment_not_ready), for up to ${ATTACHMENT_WAIT_MAX_MS / 1e3}s. Pass --no-wait to return the error immediately.`;
+/** Seconds from a Retry-After header, or undefined when absent or not a number of seconds. */
+function retryAfterMs(response) {
+	const header = response?.headers?.get("retry-after");
+	if (!header || !/^\d+$/.test(header.trim())) return void 0;
+	return Number(header.trim()) * 1e3;
+}
+/**
+* Delay before the next attempt: the server's Retry-After when it gives one,
+* otherwise exponential backoff from 1s, capped at 8s either way, and never
+* past the remaining budget.
+*/
+function nextAttachmentWaitDelay(attempt, remainingMs, serverHintMs) {
+	const backoff = INITIAL_DELAY_MS * 2 ** Math.min(attempt, 10);
+	return Math.max(0, Math.min(Math.min(serverHintMs ?? backoff, MAX_DELAY_MS), remainingMs));
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Run `call` and, while it fails with attachment_not_ready, wait and run it
+* again until it succeeds, fails differently, or the budget is spent. The last
+* result is returned either way, so the caller reports it exactly as before.
+*/
+async function withAttachmentWait(call, options) {
+	const now = options.now ?? Date.now;
+	const sleep = options.sleep ?? defaultSleep;
+	const maxWaitMs = options.maxWaitMs ?? 6e4;
+	const started = now();
+	let result = await call();
+	for (let attempt = 0; options.wait; attempt++) {
+		if (!result.error || options.errorCode(result.error) !== "attachment_not_ready") break;
+		const remaining = maxWaitMs - (now() - started);
+		if (remaining <= 0) break;
+		if (attempt === 0) options.onFirstWait?.();
+		await sleep(nextAttachmentWaitDelay(attempt, remaining, retryAfterMs(result.response)));
+		result = await call();
+	}
+	return result;
+}
+//#endregion
+//#region src/oclif/automated-filter.ts
+/**
+* The server-side `automated` verdict on inbound email: `automated`
+* (boolean) and `automated_reasons` (why, in rule order), decided by
+* the API when the email arrives, and the `automated=true|false` filter
+* on GET /emails and GET /emails/search.
+*
+* A server that predates it either rejects the `automated` filter (GET
+* /emails validates its query strictly) or ignores it and returns rows
+* without the fields (GET /emails/search). Both must fail loudly: a CLI
+* that read a missing verdict as "not automated" would hand an agent
+* every bounce and newsletter as mail from a person, and one that fell
+* back to deciding it locally would re-read all unanswered automated
+* mail on every call.
+*/
+const AUTOMATED_FILTER_UNSUPPORTED_CODE = "automated_filter_unsupported";
+const AUTOMATED_VALUES = ["true", "false"];
+const AUTOMATED_FLAG_DESCRIPTION = "Only emails whose server-decided `automated` verdict is this value: `false` = sent by a person, `true` = bounces and delivery reports, auto-replies, list and newsletter mail, and mail from the address it was sent to. Fails if the server does not support the automated filter yet.";
+var AutomatedFilterUnsupportedError = class extends Error {
+	code = AUTOMATED_FILTER_UNSUPPORTED_CODE;
+	constructor(detail) {
+		super(`The server does not support the \`automated\` filter yet: ${detail} Nothing was treated as sent by a person. Upgrade to a server that returns \`automated\` and \`automated_reasons\`, or pass --include-automated.`);
+		this.name = "AutomatedFilterUnsupportedError";
+	}
+};
+/** Like AutomatedFilterUnsupportedError, for a probe that failed. */
+var AutomatedFilterUnverifiedError = class extends AutomatedFilterUnsupportedError {
+	constructor(detail) {
+		super(detail);
+		this.message = `Could not verify that the server supports the \`automated\` filter: ${detail} Nothing was treated as matching. Retry the command.`;
+		this.name = "AutomatedFilterUnverifiedError";
+		this.code = "automated_filter_unverified";
+	}
+};
+function hasAutomatedVerdict(row) {
+	if (row === null || typeof row !== "object") return false;
+	const candidate = row;
+	return typeof candidate.automated === "boolean" && Array.isArray(candidate.automated_reasons) && candidate.automated_reasons.every((reason) => typeof reason === "string");
+}
+/**
+* Throw unless every row carries the verdict, and, for each `expected`
+* value given, unless every row has that value: a server that accepted
+* the filter but did not apply it must not pass for one that did.
+*/
+function assertAutomatedVerdict(rows, surface, expected) {
+	const missing = rows.filter((row) => !hasAutomatedVerdict(row)).length;
+	if (missing > 0) throw new AutomatedFilterUnsupportedError(`${surface} returned ${missing} of ${rows.length} email${rows.length === 1 ? "" : "s"} without the \`automated\` and \`automated_reasons\` fields.`);
+	const verdicts = expected === void 0 ? [] : typeof expected === "boolean" ? [expected] : expected;
+	for (const verdict of verdicts) {
+		const wrong = rows.filter((row) => row.automated !== verdict).length;
+		if (wrong > 0) throw new AutomatedFilterUnsupportedError(`${surface} ignored \`automated=${verdict}\` and returned ${wrong} email${wrong === 1 ? "" : "s"} with \`automated=${!verdict}\`.`);
+	}
+}
+/**
+* The verdicts the `automated:` terms in a search DSL query require.
+* The DSL joins its terms with AND, so every `automated:true|false`
+* term must hold for every returned row. Quoted text is skipped, so a
+* phrase that merely contains "automated:false" does not count.
+*/
+function automatedVerdictsFromQuery(q) {
+	if (typeof q !== "string") return [];
+	const verdicts = [];
+	const tokens = q.match(/(?:[^\s"]|"(?:[^"\\]|\\.)*"?)+/g) ?? [];
+	for (const token of tokens) {
+		const match = /^automated:"?(true|false)"?$/i.exec(token);
+		if (match) verdicts.push(match[1].toLowerCase() === "true");
+	}
+	return verdicts;
+}
+/**
+* Every verdict a list or search call asked for: the `automated`
+* parameter plus any `automated:` terms in the search query.
+*/
+function expectedAutomatedVerdicts(automated, q) {
+	return [...automated === void 0 ? [] : [automated], ...automatedVerdictsFromQuery(q)];
+}
+/** True when a search DSL query uses the `automated:` term. */
+function queryUsesAutomated(q) {
+	return typeof q === "string" && /(^|[\s(])-?automated:/i.test(q);
+}
+function errorBody$1(payload) {
+	if (payload === null || typeof payload !== "object") return {};
+	const inner = payload.error;
+	return inner !== null && typeof inner === "object" ? inner : payload;
+}
+/**
+* True when an API error is an older server rejecting the `automated`
+* query parameter or the `automated:` search term as unknown.
+*/
+function isAutomatedRejectedError(payload) {
+	const body = errorBody$1(payload);
+	if (body.code !== "validation_error") return false;
+	const message = typeof body.message === "string" ? body.message : JSON.stringify(payload);
+	return /automated/i.test(message) && /unrecogni[sz]ed|unknown/i.test(message);
+}
+function automatedRejectedError(surface) {
+	return new AutomatedFilterUnsupportedError(`${surface} rejected the \`automated\` filter as unknown.`);
+}
+const AUTOMATED_SURFACES = {
+	listEmails: "GET /emails",
+	searchEmails: "GET /emails/search"
+};
+/**
+* For the generated `emails list` / `emails search` commands: the
+* surface name when this call filtered on `automated` (the parameter or
+* an `automated:` search term), else null.
+*/
+function automatedSurfaceForOperation(sdkName, query) {
+	const surface = AUTOMATED_SURFACES[sdkName];
+	if (!surface || !query) return null;
+	const q = typeof query.q === "string" ? query.q : void 0;
+	return query.automated !== void 0 || queryUsesAutomated(q) ? surface : null;
+}
+const searchSupportProbes$1 = /* @__PURE__ */ new WeakMap();
+/**
+* GET /emails/search ignores unknown parameters, so an empty page for
+* `automated=...` does not show that the server applied the filter.
+* Read one unfiltered row: if it lacks the verdict the server does not
+* support it. No rows at all means the mailbox is empty, so the empty
+* answer stands. One probe per API client per process.
+*/
+function ensureSearchReportsAutomated(apiClient) {
+	const key = apiClient;
+	let probe = searchSupportProbes$1.get(key);
+	if (!probe) {
+		probe = (async () => {
+			const result = await searchEmails({
+				client: apiClient.client,
+				query: {
+					limit: 1,
+					include_facets: "false",
+					snippet: "false"
+				},
+				responseStyle: "fields"
+			});
+			if (result.error) throw new AutomatedFilterUnverifiedError("the empty result could not be checked: reading one unfiltered row from GET /emails/search failed.");
+			const rows = result.data?.data;
+			assertAutomatedVerdict(rows ?? [], "GET /emails/search");
+		})();
+		searchSupportProbes$1.set(key, probe);
+		probe.catch(() => {
+			if (searchSupportProbes$1.get(key) === probe) searchSupportProbes$1.delete(key);
+		});
+	}
+	return probe;
+}
+//#endregion
+//#region src/oclif/endpoints-test-redirect.ts
+async function detectFunctionEndpoint(endpointId, listEndpoints) {
+	let response;
+	try {
+		response = await listEndpoints();
+	} catch {
+		return null;
+	}
+	if (response.error) return null;
+	const rows = response.data?.data;
+	if (!Array.isArray(rows)) return null;
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		if (row.id !== endpointId) continue;
+		if (row.kind !== "function") return null;
+		const functionId = row.function_id;
+		if (typeof functionId !== "string" || functionId.length === 0) return null;
+		return {
+			endpointId,
+			functionId
+		};
+	}
+	return null;
+}
+function formatFunctionEndpointRedirect(match) {
+	return [
+		"This is a function endpoint. Function endpoints are tested differently. Run:",
+		"",
+		`    primitive functions test --id ${match.functionId}`,
+		"",
+		`(pass the function id, not the endpoint id. endpoint_id=${match.endpointId} function_id=${match.functionId})`
+	].join("\n");
+}
+async function maybeWriteFunctionEndpointRedirect(inputs) {
+	if (inputs.sdkName !== "testEndpoint") return null;
+	if (inputs.errorCode !== "not_found") return null;
+	if (!inputs.endpointId) return null;
+	const match = await detectFunctionEndpoint(inputs.endpointId, inputs.listEndpoints);
+	if (!match) return null;
+	inputs.writeStderr(`${formatFunctionEndpointRedirect(match)}\n`);
+	return match;
+}
+//#endregion
+//#region src/oclif/idempotent-replay-banner.ts
+/**
+* If `data` carries `idempotent_replay: true`, write a stderr notice
+* that the message already went out and nothing new was sent.
+* Otherwise no-op.
+*
+* The notice deliberately gives no advice on how to force a fresh
+* copy. Whoever sees a replay has already sent this message; telling
+* them to vary the content is an instruction to double-send.
+*/
+function writeIdempotentReplayBannerIfReplay(data, options) {
+	if (!isReplay(data)) return;
+	options.write(`${formatAlreadySentNotice(data)}\n`);
+}
+function isReplay(data) {
+	if (data === null || typeof data !== "object") return false;
+	return data.idempotent_replay === true;
+}
+function formatAlreadySentNotice(sent) {
+	const details = [];
+	if (typeof sent.id === "string" && sent.id) details.push(`sent id ${sent.id}`);
+	const status = typeof sent.status === "string" && sent.status ? sent.status : null;
+	const deliveryStatus = typeof sent.delivery_status === "string" && sent.delivery_status ? sent.delivery_status : null;
+	if (status) details.push(`status ${status}`);
+	if (deliveryStatus && deliveryStatus !== status) details.push(`delivery status ${deliveryStatus}`);
+	return `Already sent: this exact message went out earlier${details.length > 0 ? ` (${details.join(", ")})` : ""}. Nothing new was sent.`;
+}
+//#endregion
+//#region src/oclif/reply-state.ts
+const AWAITING_VALUES = ["you", "them"];
+const AWAITING_FLAG_DESCRIPTION = "Only emails whose reply state is this value: `you` = waiting on your reply (the thread's latest message is inbound), `them` = you replied last. Queued and scheduled replies count as replied. Delivered mail only: rejected mail is never returned. Fails if the server does not report reply state yet.";
+const REPLY_STATE_UNSUPPORTED_CODE = "reply_state_unsupported";
+/** True when a search DSL query uses the `awaiting:` term. */
+function queryUsesAwaiting(q) {
+	return typeof q === "string" && /(^|[\s(])-?awaiting:/i.test(q);
+}
+var ReplyStateUnsupportedError = class extends Error {
+	code = REPLY_STATE_UNSUPPORTED_CODE;
+	constructor(detail) {
+		super(`The server does not support reply state yet: ${detail} Nothing was treated as awaiting your reply. Upgrade to a server that returns \`awaiting\` and \`reply_count\`, or run without reply-state options.`);
+		this.name = "ReplyStateUnsupportedError";
+	}
+};
+/**
+* The server's reply-state support could not be established (a probe
+* failed). Reported like ReplyStateUnsupportedError so callers never
+* read an unverified empty answer as "nothing matched".
+*/
+var ReplyStateUnverifiedError = class extends ReplyStateUnsupportedError {
+	constructor(detail) {
+		super(detail);
+		this.message = `Could not verify that the server supports reply state: ${detail} Nothing was treated as matching. Retry the command.`;
+		this.name = "ReplyStateUnverifiedError";
+		this.code = "reply_state_unverified";
+	}
+};
+function hasReplyState(row) {
+	if (row === null || typeof row !== "object") return false;
+	const candidate = row;
+	return (candidate.awaiting === "you" || candidate.awaiting === "them") && typeof candidate.reply_count === "number" && (candidate.last_replied_at === null || typeof candidate.last_replied_at === "string");
+}
+/**
+* Throw unless every row carries reply state. An empty page proves
+* nothing either way; callers that asked for reply state follow an
+* empty search page with ensureSearchReportsReplyState(). `surface` names the
+* response for the error, e.g. "GET /emails".
+*/
+function assertReplyState(rows, surface) {
+	const missing = rows.filter((row) => !hasReplyState(row)).length;
+	if (missing > 0) throw new ReplyStateUnsupportedError(`${surface} returned ${missing} of ${rows.length} email${rows.length === 1 ? "" : "s"} without the \`awaiting\` and \`reply_count\` fields.`);
+}
+const AWAITING_REJECTED_UNSUPPORTED_CODE = "awaiting_rejected_unsupported";
+/**
+* The `awaiting` filter matches delivered mail only: a rejected email
+* (for example refused over the storage limit) was never delivered, so it
+* awaits no one. A server that returns one through the filter predates
+* that, and an agent would be handed mail nobody can answer.
+*/
+var AwaitingIncludesRejectedError = class extends ReplyStateUnsupportedError {
+	constructor(detail) {
+		super(detail);
+		this.message = `The server's \`awaiting\` filter does not exclude undelivered mail yet: ${detail} Upgrade to a server whose \`awaiting\` filter matches delivered mail only.`;
+		this.name = "AwaitingIncludesRejectedError";
+		this.code = AWAITING_REJECTED_UNSUPPORTED_CODE;
+	}
+};
+/**
+* For rows returned BY an `awaiting` filter (not the unfiltered probe):
+* every row carries reply state, and none has status `rejected`.
+*/
+function assertAwaitingFilterRows(rows, surface) {
+	assertReplyState(rows, surface);
+	const rejected = rows.filter((row) => row !== null && typeof row === "object" && row.status === "rejected").length;
+	if (rejected > 0) throw new AwaitingIncludesRejectedError(`${surface} returned ${rejected} email${rejected === 1 ? "" : "s"} with status \`rejected\`.`);
+}
+function errorBody(payload) {
+	if (payload === null || typeof payload !== "object") return {};
+	const inner = payload.error;
+	return inner !== null && typeof inner === "object" ? inner : payload;
+}
+/**
+* True when an API error is an older server rejecting the `awaiting`
+* query parameter or the `awaiting:` search term as unknown. A current
+* server accepts both, and the CLI only ever sends valid values.
+*/
+function isAwaitingRejectedError(payload) {
+	const body = errorBody(payload);
+	if (body.code !== "validation_error") return false;
+	const message = typeof body.message === "string" ? body.message : JSON.stringify(payload);
+	return /awaiting/i.test(message) && /unrecogni[sz]ed|unknown/i.test(message);
+}
+function awaitingRejectedError(surface) {
+	return new ReplyStateUnsupportedError(`${surface} rejected the \`awaiting\` filter as unknown.`);
+}
+/** Short column value for tables: "you", "them", or "-" when absent. */
+function formatAwaitingCell(row) {
+	if (!hasReplyState(row)) return "-";
+	return row.awaiting;
+}
+/** Reply count for tables, or "-" when the server did not report it. */
+function formatRepliesCell(row) {
+	if (!hasReplyState(row)) return "-";
+	return String(row.reply_count);
+}
+const REPLY_STATE_SURFACES = {
+	listEmails: "GET /emails",
+	searchEmails: "GET /emails/search"
+};
+/**
+* For the generated `emails list` / `emails search` commands: the
+* surface name when this call asked for reply state (an `awaiting`
+* parameter or an `awaiting:` search term), else null.
+*/
+function replyStateSurfaceForOperation(sdkName, query) {
+	const surface = REPLY_STATE_SURFACES[sdkName];
+	if (!surface || !query) return null;
+	const q = typeof query.q === "string" ? query.q : void 0;
+	return query.awaiting !== void 0 || queryUsesAwaiting(q) ? surface : null;
+}
+const searchSupportProbes = /* @__PURE__ */ new WeakMap();
+/**
+* GET /emails/search ignores unknown parameters, so an empty page for
+* `awaiting=...` does not show that the server applied the filter.
+* Read one unfiltered row: if it lacks reply state the server does not
+* support it and this throws ReplyStateUnsupportedError. No rows at all
+* means the mailbox is empty, so the empty answer stands.
+*/
+function ensureSearchReportsReplyState(apiClient) {
+	const key = apiClient;
+	let probe = searchSupportProbes.get(key);
+	if (!probe) {
+		probe = (async () => {
+			const result = await searchEmails({
+				client: apiClient.client,
+				query: {
+					limit: 1,
+					include_facets: "false",
+					snippet: "false"
+				},
+				responseStyle: "fields"
+			});
+			if (result.error) throw new ReplyStateUnverifiedError("the empty result could not be checked: reading one unfiltered row from GET /emails/search failed.");
+			const rows = result.data?.data;
+			assertReplyState(rows ?? [], "GET /emails/search");
+		})();
+		searchSupportProbes.set(key, probe);
+		probe.catch(() => {
+			if (searchSupportProbes.get(key) === probe) searchSupportProbes.delete(key);
+		});
+	}
+	return probe;
+}
+//#endregion
+//#region src/oclif/api-command.ts
+const API_ERROR_CODES = {
+	accessDenied: "access_denied",
+	authorizationPending: "authorization_pending",
+	expiredToken: "expired_token",
+	invalidDeviceCode: "invalid_device_code",
+	notFound: "not_found",
+	slowDown: "slow_down",
+	unauthorized: "unauthorized"
+};
+function flagName(parameterName) {
+	return parameterName.replace(/_/g, "-");
+}
+function flagDescription(parameter) {
+	return parameter.description ?? parameter.name;
+}
+const numberFlag = Flags.custom({ async parse(input, _context, options) {
+	const trimmed = input.trim();
+	if (trimmed === "") throw new Errors.CLIError(`Expected a number but received: ${input}`);
+	const value = Number(trimmed);
+	if (!Number.isFinite(value)) throw new Errors.CLIError(`Expected a number but received: ${input}`);
+	if (options.min !== void 0 && value < options.min) throw new Errors.CLIError(`Expected a number greater than or equal to ${options.min} but received: ${input}`);
+	if (options.max !== void 0 && value > options.max) throw new Errors.CLIError(`Expected a number less than or equal to ${options.max} but received: ${input}`);
+	return value;
+} });
+function numericFlagOptions(parameter) {
+	return {
+		...typeof parameter.default === "number" ? { default: parameter.default } : {},
+		...typeof parameter.maximum === "number" ? { max: parameter.maximum } : {},
+		...typeof parameter.minimum === "number" ? { min: parameter.minimum } : {}
+	};
+}
+function extractBodyFields(schema) {
+	if (!schema || typeof schema !== "object") return [];
+	const properties = schema.properties;
+	if (!properties || typeof properties !== "object") return [];
+	const requiredArr = Array.isArray(schema.required) ? schema.required.filter((k) => typeof k === "string") : [];
+	const required = new Set(requiredArr);
+	const fields = [];
+	for (const [name, raw] of Object.entries(properties)) {
+		const propSchema = raw && typeof raw === "object" ? raw : {};
+		const t = propSchema.type;
+		let displayType = "any";
+		let kind = "complex";
+		if (typeof t === "string") {
+			displayType = t;
+			if (t === "string") kind = "string";
+			else if (t === "integer") kind = "integer";
+			else if (t === "number") kind = "number";
+			else if (t === "boolean") kind = "boolean";
+			else if (t === "array") {
+				const items = propSchema.items;
+				if (items && typeof items === "object") {
+					const itemType = items.type;
+					if (typeof itemType === "string") displayType = `array<${itemType}>`;
+				}
+				kind = "complex";
+			} else kind = "complex";
+		} else if (Array.isArray(t)) {
+			const nonNull = t.filter((s) => s !== "null");
+			if (nonNull.length === 1) {
+				const single = nonNull[0];
+				displayType = `${single}?`;
+				if (single === "string") kind = "string";
+				else if (single === "integer") kind = "integer";
+				else if (single === "number") kind = "number";
+				else if (single === "boolean") kind = "boolean";
+				else kind = "complex";
+			} else {
+				displayType = nonNull.join("|");
+				kind = "complex";
+			}
+		}
+		const description = typeof propSchema.description === "string" ? propSchema.description.split(/\n\s*\n/)[0].replace(/\s*\n\s*/g, " ").trim() : "";
+		const enumRaw = propSchema.enum;
+		const enumValues = kind === "string" && Array.isArray(enumRaw) ? enumRaw.filter((e) => typeof e === "string") : void 0;
+		fields.push({
+			name,
+			description,
+			required: required.has(name),
+			displayType,
+			kind,
+			...enumValues && enumValues.length > 0 ? { enumValues } : {},
+			...typeof propSchema.maximum === "number" ? { maximum: propSchema.maximum } : {},
+			...typeof propSchema.minimum === "number" ? { minimum: propSchema.minimum } : {}
+		});
+	}
+	return fields.sort((a, b) => {
+		if (a.required !== b.required) return a.required ? -1 : 1;
+		return a.name.localeCompare(b.name);
+	});
+}
+/**
+* Render a "Body fields" summary for the per-command help.
+*
+* Most scalar fields are exposed as individual `--flag` flags,
+* which oclif auto-renders in the FLAGS section above. To avoid
+* duplicating that, the summary here only documents fields that
+* MUST go through `--raw-body` (complex types: arrays, objects,
+* mixed-non-nullable). When an operation has only scalars, the
+* summary is omitted entirely and oclif's FLAGS section is the
+* full story.
+*
+* For operations with mixed scalar and complex fields, we also
+* include a short header pointing the agent at the flag form so
+* the natural reading is "use the flags above; --raw-body for
+* the leftovers below."
+*/
+function renderRequestSchemaSummary(schema) {
+	const fields = extractBodyFields(schema);
+	if (fields.length === 0) return null;
+	const complex = fields.filter((f) => f.kind === "complex");
+	if (complex.length === 0) return null;
+	const nameWidth = Math.min(24, Math.max(...complex.map((f) => f.name.length)));
+	const descMax = 78;
+	const lines = ["Body fields requiring --raw-body JSON (these are not exposed as flags):"];
+	for (const f of complex) {
+		const marker = f.required ? " *" : "  ";
+		const padName = f.name.padEnd(nameWidth);
+		const trimmedDesc = f.description.length > descMax ? `${f.description.slice(0, descMax - 3)}...` : f.description;
+		const desc = trimmedDesc ? `  ${trimmedDesc}` : "";
+		lines.push(`${marker} ${padName}  ${f.displayType}${desc}`);
+	}
+	lines.push("(* = required. Scalar body fields are exposed as individual --flag-name flags; see FLAGS above.)");
+	return lines.join("\n");
+}
+function flagForParameter(parameter) {
+	const common = {
+		description: flagDescription(parameter),
+		required: parameter.required
+	};
+	if (parameter.type === "boolean") return Flags.boolean(common);
+	if (parameter.type === "integer") return Flags.integer({
+		...common,
+		...numericFlagOptions(parameter)
+	});
+	if (parameter.type === "number") return numberFlag({
+		...common,
+		...numericFlagOptions(parameter)
+	});
+	if (parameter.enum && parameter.enum.length > 0) return Flags.string({
+		...common,
+		options: parameter.enum
+	});
+	return Flags.string(common);
+}
+function coerceParameterValue(parameter, value) {
+	if (value === void 0) return;
+	if (parameter.type === "number") {
+		if (typeof value === "number") return value;
+		const parsed = Number(value);
+		if (Number.isNaN(parsed)) throw new Errors.CLIError(`Invalid number for --${parameter.name}: ${value}`);
+		return parsed;
+	}
+	if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") return value;
+	throw new Errors.CLIError(`Unsupported flag value for --${parameter.name}`);
+}
+function cliError(message) {
+	return new Errors.CLIError(message, { exit: 1 });
+}
+function parseJson(source, flagLabel) {
+	try {
+		return JSON.parse(source);
+	} catch (error) {
+		throw cliError(`${flagLabel} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function readJsonBody(flags) {
+	const bodyFile = flags["body-file"];
+	const rawBody = flags["raw-body"];
+	if (bodyFile && rawBody) throw cliError("Use either --raw-body or --body-file, not both");
+	if (typeof bodyFile === "string") {
+		let contents;
+		try {
+			contents = readFileSync(bodyFile, "utf8");
+		} catch (error) {
+			throw cliError(`Could not read --body-file ${bodyFile}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return parseJson(contents, `--body-file ${bodyFile}`);
+	}
+	if (typeof rawBody === "string") return parseJson(rawBody, "--raw-body");
+}
+function readTextFileFlag(path, flagLabel) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		throw cliError(`Could not read ${flagLabel} ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function extractErrorPayload(raw) {
+	if (raw && typeof raw === "object" && !(raw instanceof Error) && "error" in raw) {
+		const inner = raw.error;
+		if (inner !== null && inner !== void 0) return inner;
+	}
+	return raw;
+}
+function extractCauseDetails(cause) {
+	const details = {};
+	let code;
+	if (!cause || typeof cause !== "object") return { details };
+	for (const [key, value] of Object.entries(cause)) if (typeof value === "string" || typeof value === "number") {
+		details[key] = value;
+		if (key === "code" && typeof value === "string") code = value;
+	}
+	return {
+		code,
+		details
+	};
+}
+function formatErrorPayload(payload) {
+	if (payload instanceof Error) {
+		const { code, details } = extractCauseDetails(payload.cause);
+		const body = {
+			code: code ?? "client_error",
+			message: payload.message || payload.name || String(payload)
+		};
+		if (Object.keys(details).length > 0) body.cause = details;
+		return JSON.stringify(body, null, 2);
+	}
+	return JSON.stringify(payload, null, 2);
+}
+function extractErrorCode(payload) {
+	if (payload instanceof Error) {
+		const { code } = extractCauseDetails(payload.cause);
+		return code;
+	}
+	if (payload && typeof payload === "object") {
+		const inner = payload.error;
+		if (inner && typeof inner === "object" && typeof inner.code === "string") return inner.code;
+		const direct = payload.code;
+		if (typeof direct === "string") return direct;
+	}
+}
+const ERROR_CODE_HINTS = { [API_ERROR_CODES.unauthorized]: "Hint: run `primitive signin`, pass --api-key explicitly, or set PRIMITIVE_API_KEY in your environment. `primitive whoami` is the fastest way to verify auth is live." };
+const NETWORK_ERROR_HINTS = {
+	ENETUNREACH: "Hint: the network is unreachable. If you're behind a proxy and set HTTP(S)_PROXY, re-run with NODE_USE_ENV_PROXY=1 (Node 22+ ignores those env vars by default). `primitive doctor` reports the local environment in one shot.",
+	ECONNREFUSED: "Hint: the server refused the connection. Check that your firewall allows egress to *.primitive.dev, that your PRIMITIVE_API_BASE_URL_* overrides (if any) point at a reachable host, and re-run with NODE_USE_ENV_PROXY=1 if you're behind a proxy. `primitive doctor` reports the local environment in one shot.",
+	ETIMEDOUT: "Hint: the connection timed out. Check egress rules and proxy configuration; if you're behind a proxy, re-run with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY set. `primitive doctor` reports the local environment in one shot.",
+	EAI_AGAIN: "Hint: DNS lookup failed. Check /etc/resolv.conf inside containers, and try `curl -v https://api.primitive.dev/v1/account` to confirm the host resolves. `primitive doctor` reports the local environment in one shot."
+};
+function writeErrorWithHints(payload) {
+	process.stderr.write(`${formatErrorPayload(payload)}\n`);
+	const code = extractErrorCode(payload);
+	if (!code) return;
+	if (code in ERROR_CODE_HINTS) {
+		const hint = ERROR_CODE_HINTS[code];
+		process.stderr.write(`${hint}\n`);
+		return;
+	}
+	if (code in NETWORK_ERROR_HINTS) process.stderr.write(`${NETWORK_ERROR_HINTS[code]}\n`);
+}
+/**
+* Surface a user-facing hint when a request comes back unauthorized.
+*
+* Deliberately does NOT mutate the saved credentials.json. Auto-
+* deleting on any 401 made transient rejections look like permanent
+* credential failures and forced unnecessary re-login cycles; we
+* surface a hint and let the user decide whether to re-authenticate.
+*
+* The one legitimate auto-delete case lives in `primitive login`'s
+* `checkExistingLogin`: the user has explicitly asked to log in,
+* existing credentials are probed, and if they fail we clean up
+* before minting a new key. That path calls `deleteCliCredentials`
+* directly rather than going through this function.
+*/
+function surfaceUnauthorizedHint(params) {
+	if (extractErrorCode(params.payload) !== API_ERROR_CODES.unauthorized || params.auth.source !== "stored") return;
+	if (params.baseUrlOverridden && params.auth.credentials !== null && params.auth.apiBaseUrl !== params.auth.credentials.api_base_url) {
+		process.stderr.write("Saved Primitive CLI credentials were rejected by the overridden API base URL. The saved credential is preserved; unset PRIMITIVE_API_BASE_URL, run `primitive config reset` to clear configured URL overrides, or run `primitive logout` to remove the stored credential.\n");
+		return;
+	}
+	process.stderr.write("Your saved Primitive CLI OAuth session was rejected. If the command was working a moment ago, please retry; brief retries often clear transient rejections. If it keeps failing, run `primitive logout && primitive signin` to mint a fresh session.\n");
+}
+function formatElapsed(ms) {
+	const seconds = ms / 1e3;
+	if (seconds < 60) return `${seconds.toFixed(2)}s`;
+	const minutes = Math.floor(seconds / 60);
+	return `${minutes}m ${(seconds - minutes * 60).toFixed(2)}s`;
+}
+async function runWithTiming(enabled, fn) {
+	if (!enabled) return fn();
+	const start = Date.now();
+	try {
+		return await fn();
+	} finally {
+		process.stderr.write(`[time: ${formatElapsed(Date.now() - start)}]\n`);
+	}
+}
+const TIME_FLAG_DESCRIPTION = "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.";
+const API_BASE_URL_FLAG_DESCRIPTION = "Override the API base URL. Internal testing only; not documented to customers.";
+const RESERVED_FLAG_NAMES = new Set([
+	"api-key",
+	"api-base-url",
+	"raw-body",
+	"body-file",
+	"envelope",
+	"output"
+]);
+function bodyFieldFlag(field, aliases) {
+	const common = {
+		description: field.description || field.name,
+		...aliases && aliases.length > 0 ? { aliases } : {}
+	};
+	if (field.kind === "boolean") return Flags.boolean({
+		...common,
+		allowNo: true
+	});
+	if (field.kind === "integer") return Flags.integer({
+		...common,
+		...numericFlagOptions(field)
+	});
+	if (field.kind === "number") return numberFlag({
+		...common,
+		...numericFlagOptions(field)
+	});
+	if (field.enumValues) return Flags.string({
+		...common,
+		options: field.enumValues
+	});
+	return Flags.string(common);
+}
+function buildFlags(operation) {
+	const flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: "Override the API base URL. Internal testing only; not documented to customers.",
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	if (!operation.binaryResponse) {
+		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." });
+	}
+	for (const parameter of [...operation.pathParams, ...operation.queryParams]) flags[flagName(parameter.name)] = flagForParameter(parameter);
+	const bodyFieldFlagToProperty = /* @__PURE__ */ new Map();
+	if (operation.hasJsonBody) {
+		flags["raw-body"] = Flags.string({ description: "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available." });
+		flags["body-file"] = Flags.string({ description: "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload." });
+		const bodyFields = extractBodyFields(operation.requestSchema);
+		const aliasesForOperation = OPERATION_FLAG_ALIASES[operation.sdkName];
+		for (const field of bodyFields) {
+			if (field.kind === "complex") continue;
+			const name = flagName(field.name);
+			if (RESERVED_FLAG_NAMES.has(name)) continue;
+			if (flags[name] !== void 0) continue;
+			flags[name] = bodyFieldFlag(field, aliasesForOperation?.[field.name]);
+			bodyFieldFlagToProperty.set(name, field.name);
+		}
+	}
+	if (operation.binaryResponse) flags.output = Flags.string({ description: "Write binary response bytes to a file" });
+	if (ATTACHMENT_WAIT_OPERATIONS.has(operation.sdkName)) flags.wait = Flags.boolean({
+		allowNo: true,
+		default: true,
+		description: ATTACHMENT_WAIT_FLAG_DESCRIPTION
+	});
+	return {
+		flags,
+		bodyFieldFlagToProperty
+	};
+}
+function collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty) {
+	const result = {};
+	for (const [flag, property] of bodyFieldFlagToProperty) {
+		const value = parsedFlags[flag];
+		if (value === void 0) continue;
+		result[property] = value;
+	}
+	return result;
+}
+function collectValues(parameters, flags) {
+	const values = {};
+	for (const parameter of parameters) {
+		const value = coerceParameterValue(parameter, flags[flagName(parameter.name)]);
+		if (value !== void 0) values[parameter.name] = value;
+	}
+	return values;
+}
+function operationOutputPayload(envelope, includeEnvelope) {
+	return includeEnvelope ? envelope ?? null : envelope?.data ?? null;
+}
+/**
+* The `--json` document for a generated command: the full response
+* envelope, so pagination metadata travels with the data, plus any
+* notes the command would otherwise print on stderr.
+*/
+function operationJsonDocument(envelope, summary = []) {
+	const document = envelope !== null && typeof envelope === "object" ? { ...envelope } : { data: null };
+	if (summary.length > 0) document.summary = summary.join("\n");
+	return document;
+}
+function isIncompleteDomainVerification(operation, envelope) {
+	if (operation.sdkName !== "verifyDomain") return false;
+	const data = envelope?.data;
+	if (!data || typeof data !== "object") return false;
+	return data.verified === false;
+}
+function writeIncompleteDomainVerificationHint() {
+	process.stderr.write("Domain verification is incomplete. Add or fix the DNS records shown above, or run `primitive domains zone-file --id <domain-id>` to download the complete zone file, then retry `primitive domains verify --id <domain-id>`.\n");
+}
+const OPERATION_HINTS = {
+	addDomain: "Tip: after this returns a domain id, run `primitive domains zone-file --id <domain-id> --output <domain>.zone` when the user wants an importable DNS zone file.",
+	verifyDomain: "Tip: if DNS is still missing, run `primitive domains zone-file --id <domain-id> --output <domain>.zone` to give the user an importable DNS zone file.",
+	downloadDomainZoneFile: "Tip: prefer `primitive domains zone-file --id <domain-id> --output <domain>.zone` for CLI-friendly file output.",
+	getInboxStatus: "Tip: prefer `primitive inbox status` for a compact readiness summary and next-step commands.",
+	getSendPermissions: "Tip: this command answers where you may send mail to. To find usable sender domains for --from, run `primitive domains list` or `primitive inbox status` and use an address at an active verified domain.",
+	sendEmail: "Tip: prefer `primitive send --to <address> --body <text> --attachment <file>` for file attachments. This raw command exists for callers passing JSON.",
+	createFunction: "Tip: prefer `primitive functions deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
+	updateFunction: "Tip: prefer `primitive functions redeploy --id <id> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
+	createFunctionSecret: "Tip: prefer `primitive functions set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
+	setFunctionSecret: "Tip: prefer `primitive functions set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
+	setMemory: "Tip: prefer `primitive memories set <key> <json-value> [--function <function-id>]` for JSON value parsing and scope flags. This raw command exists for callers passing full request JSON.",
+	getMemory: "Tip: prefer `primitive memories get <key> [--function <function-id>]` for the common read path.",
+	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, and optionally --signup-code <code> if you have one. 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.",
+	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"] } };
+const OPERATION_SUCCESS_HOOKS = { verifyAgentSignup: ({ envelope, configDir, apiBaseUrl, writeStderr }) => {
+	const data = envelope?.data;
+	if (!data?.access_token || !data?.refresh_token) return;
+	saveSignupCredentials({
+		apiBaseUrl,
+		configDir,
+		signup: data
+	});
+	writeStderr("Credentials saved to the CLI config; `primitive whoami` will work on the next call.\n");
+} };
+function createOperationCommand(operation) {
+	const { flags, bodyFieldFlagToProperty } = 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 hint = OPERATION_HINTS[operation.sdkName];
+	const descriptionWithSchema = schemaSummary ? `${baseDescription}\n\n${schemaSummary}` : baseDescription;
+	const fullDescription = hint ? `${descriptionWithSchema}\n\n${hint}` : descriptionWithSchema;
+	class OperationCommand extends Command {
+		static description = fullDescription;
+		static flags = flags;
+		static summary = operation.summary ?? `${operation.method} ${operation.path}`;
+		async run() {
+			const { flags } = await this.parse(OperationCommand);
+			const parsedFlags = flags;
+			if ([
+				"startAgentSignup",
+				"verifyAgentSignup",
+				"resendAgentSignupVerification"
+			].includes(operation.operationId)) requireDefaultLoginProfile();
+			await runWithTiming(parsedFlags.time === true, async () => {
+				const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+					apiKey: typeof parsedFlags["api-key"] === "string" ? parsedFlags["api-key"] : void 0,
+					apiBaseUrl: typeof parsedFlags["api-base-url"] === "string" ? parsedFlags["api-base-url"] : void 0,
+					configDir: this.config.configDir
+				});
+				let body;
+				if (operation.hasJsonBody) {
+					const explicit = readJsonBody(parsedFlags);
+					const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
+					if (Object.keys(overrides).length > 0) if (explicit === void 0) body = overrides;
+					else if (explicit !== null && typeof explicit === "object" && !Array.isArray(explicit)) body = {
+						...explicit,
+						...overrides
+					};
+					else {
+						const explicitKind = explicit === null ? "null" : Array.isArray(explicit) ? "array" : typeof explicit;
+						const overrideFlags = Object.keys(overrides).map((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;
+				}
+				if (operation.bodyRequired && body === void 0) throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
+				const operationFn = sdk_gen_exports[operation.sdkName];
+				const query = collectValues(operation.queryParams, parsedFlags);
+				const replyStateSurface = replyStateSurfaceForOperation(operation.sdkName, query);
+				const automatedSurface = automatedSurfaceForOperation(operation.sdkName, query);
+				const callOperation = () => operationFn({
+					body,
+					client: apiClient.client,
+					parseAs: operation.binaryResponse ? "blob" : "auto",
+					path: collectValues(operation.pathParams, parsedFlags),
+					query,
+					responseStyle: "fields"
+				});
+				const result = ATTACHMENT_WAIT_OPERATIONS.has(operation.sdkName) ? await withAttachmentWait(callOperation, {
+					wait: parsedFlags.wait !== false,
+					errorCode: (error) => extractErrorCode(extractErrorPayload(error)),
+					onFirstWait: () => {
+						process.stderr.write(`Attachment content is not ready yet; waiting up to ${ATTACHMENT_WAIT_MAX_MS / 1e3}s. Pass --no-wait to return immediately.\n`);
+					}
+				}) : await callOperation();
+				if (result.error) {
+					const errorPayload = extractErrorPayload(result.error);
+					writeErrorWithHints(errorPayload);
+					if (replyStateSurface && isAwaitingRejectedError(errorPayload)) process.stderr.write(`${awaitingRejectedError(replyStateSurface).message}\n`);
+					if (automatedSurface && isAutomatedRejectedError(errorPayload)) process.stderr.write(`${automatedRejectedError(automatedSurface).message}\n`);
+					surfaceUnauthorizedHint({
+						auth,
+						baseUrlOverridden,
+						configDir: this.config.configDir,
+						payload: errorPayload
+					});
+					const listClient = apiClient.client;
+					const listEndpointsFn = () => listEndpoints({
+						client: listClient,
+						responseStyle: "fields"
+					});
+					await maybeWriteFunctionEndpointRedirect({
+						sdkName: operation.sdkName,
+						errorCode: extractErrorCode(errorPayload),
+						endpointId: typeof parsedFlags.id === "string" ? parsedFlags.id : void 0,
+						listEndpoints: listEndpointsFn,
+						writeStderr: (chunk) => {
+							process.stderr.write(chunk);
+						}
+					});
+					process.exitCode = 1;
+					return;
+				}
+				if (operation.binaryResponse) {
+					const blob = result.data;
+					const bytes = Buffer.from(await blob.arrayBuffer());
+					const output = parsedFlags.output;
+					if (typeof output === "string") {
+						writeFileSync(output, bytes);
+						return;
+					}
+					process.stdout.write(bytes);
+					return;
+				}
+				const envelope = result.data;
+				if (replyStateSurface) try {
+					const rows = Array.isArray(envelope?.data) ? envelope.data : [];
+					assertAwaitingFilterRows(rows, replyStateSurface);
+					if (rows.length === 0 && operation.sdkName === "searchEmails") await ensureSearchReportsReplyState(apiClient);
+				} catch (error) {
+					if (!(error instanceof ReplyStateUnsupportedError)) throw error;
+					process.stderr.write(`${error.message}\n`);
+					process.exitCode = 1;
+					return;
+				}
+				if (automatedSurface) try {
+					const rows = Array.isArray(envelope?.data) ? envelope.data : [];
+					assertAutomatedVerdict(rows, automatedSurface, expectedAutomatedVerdicts(query?.automated === "true" ? true : query?.automated === "false" ? false : void 0, typeof query?.q === "string" ? query.q : void 0));
+					if (rows.length === 0 && operation.sdkName === "searchEmails") await ensureSearchReportsAutomated(apiClient);
+				} catch (error) {
+					if (!(error instanceof AutomatedFilterUnsupportedError)) throw error;
+					process.stderr.write(`${error.message}\n`);
+					process.exitCode = 1;
+					return;
+				}
+				const jsonOutput = parsedFlags.json === true;
+				const withEnvelope = parsedFlags.envelope === true;
+				const cursor = envelope?.meta?.cursor;
+				if (cursor && !jsonOutput) process.stderr.write(`next cursor: ${cursor}\n`);
+				const summary = [];
+				if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
+					const hint = EMPTY_RESULT_HINTS[operation.sdkName];
+					if (hint && jsonOutput) {
+						if (withEnvelope) summary.push(hint);
+					} else if (hint) process.stderr.write(`${hint}\n`);
+				}
+				writeIdempotentReplayBannerIfReplay(envelope?.data, { write: (chunk) => {
+					process.stderr.write(chunk);
+				} });
+				const successHook = OPERATION_SUCCESS_HOOKS[operation.sdkName];
+				if (successHook) try {
+					successHook({
+						envelope,
+						configDir: this.config.configDir,
+						apiBaseUrl: auth.apiBaseUrl,
+						writeStderr: (chunk) => {
+							process.stderr.write(chunk);
+						}
+					});
+				} catch (hookError) {
+					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));
+				if (isIncompleteDomainVerification(operation, envelope)) {
+					writeIncompleteDomainVerificationHint();
+					process.exitCode = 1;
+				}
+			});
+		}
+	}
+	return OperationCommand;
+}
+const EMPTY_RESULT_HINTS = {
+	listDeliveries: "(no results) No webhook deliveries logged yet. If you have an endpoint configured but expected to see test fires here: test deliveries from `primitive endpoints test` are NOT logged in this list, they're synchronous and visible only in the test-endpoint command's response. Real deliveries are logged when an inbound `email.received` event fans out to your endpoints. If you have no endpoints, run `primitive endpoints list` to check.",
+	listEndpoints: "(no results) No webhook endpoints configured. Add one with `primitive endpoints create --url <your-url>`.",
+	listEmails: "(no results) No inbound emails received yet on this account. Send one to a verified domain to populate this list. For a compact view, prefer `primitive emails latest`.",
+	listDomains: "(no results) No domains on this account. Add one with `primitive domains add --domain <yourdomain.example>`.",
+	listFilters: "(no results) No filter rules configured.",
+	listFunctions: "(no results) No Functions configured yet. Start with `primitive functions templates`, then `primitive functions init --template <template>` and `primitive functions deploy --name <name> --file <bundle>`."
+};
+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'`");
+}
+//#endregion
+//#region src/oclif/send-outcome.ts
+const SEND_OUTCOME_EXIT_CODES = {
+	replied: 0,
+	sent: 0,
+	already_sent: 0,
+	not_sent: 1,
+	sent_awaiting_reply: 3,
+	uncertain: 4
+};
+const DEFINITIVE_SEND_REJECTION_STATUSES = [
+	400,
+	401,
+	402,
+	403,
+	404,
+	413,
+	422,
+	429
+];
+const SEND_OUTCOME_HELP = `Outcomes and exit codes, shared by chat, chat reply, send and reply (JSON output carries the name as "outcome"):
+  - exit 0 replied: chat only. The message was sent and a reply arrived.
+  - exit 0 sent: accepted for delivery. A queued status counts as sent.
+  - exit 0 already_sent: an identical earlier send exists (or was deleted: HTTP 410 sent_email_deleted). Nothing new went out. Do not resend.
+  - exit 1 not_sent: the API rejected the request (HTTP 400, 401, 402, 403, 404, 413, 422 or 429), the command failed before sending, or the send record has status agent_failed, gate_denied or canceled. Nothing went out.
+  - exit 2: invalid flags or arguments. Nothing went out.
+  - exit 3 sent_awaiting_reply: chat only. Sent, but no reply before the timeout. Wait; do not resend.
+  - exit 4 uncertain: transport error, conflict, server error, or a send record with status unknown. It may or may not have gone out. Reconcile with primitive sent get --idempotency-key <key> (the key is in the --json envelope) before retrying.`;
+function sendOutcomeExitCode(outcome) {
+	return SEND_OUTCOME_EXIT_CODES[outcome];
+}
+function sendFailureOutcome(httpStatus) {
+	return httpStatus !== void 0 && DEFINITIVE_SEND_REJECTION_STATUSES.includes(httpStatus) ? "not_sent" : "uncertain";
+}
+const SENT_EMAIL_DELETED_CODE = "sent_email_deleted";
+function errorPayloadCode(payload) {
+	if (payload === null || typeof payload !== "object") return void 0;
+	const code = payload.code;
+	return typeof code === "string" ? code : void 0;
+}
+function isDeletedEarlierSend(httpStatus, errorPayload) {
+	return httpStatus === 410 && errorPayloadCode(errorPayload) === SENT_EMAIL_DELETED_CODE;
+}
+/** Classify an API error from a send request. */
+function classifySendError(httpStatus, errorPayload) {
+	return isDeletedEarlierSend(httpStatus, errorPayload) ? "already_sent" : sendFailureOutcome(httpStatus);
+}
+function formatDeletedEarlierSendNotice() {
+	return "Already sent: an earlier send matching this request went out and its record was later deleted, so the API refused this one (HTTP 410 sent_email_deleted). Nothing new was sent. Do not resend or change the idempotency key to get around this.";
+}
+/** Read the HTTP status from a `responseStyle: "fields"` API result. */
+function apiResultHttpStatus(result) {
+	if (result === null || typeof result !== "object") return void 0;
+	if (!("response" in result)) return void 0;
+	const response = result.response;
+	return typeof response?.status === "number" ? response.status : void 0;
+}
+const SEND_STATUSES_THAT_DID_NOT_GO_OUT = new Set([
+	"agent_failed",
+	"canceled",
+	"gate_denied"
+]);
+const SEND_STATUSES_WITH_UNKNOWN_OUTCOME = new Set(["unknown"]);
+/**
+* Classify a send record the API returned with a 2xx. A 2xx alone does
+* not mean a message went out: the record's status can show the
+* attempt was rejected or that its result is indeterminate. The same
+* holds for an idempotent replay, which returns the earlier attempt's
+* record as it stands.
+*/
+function successfulSendOutcome(sent) {
+	if (SEND_STATUSES_THAT_DID_NOT_GO_OUT.has(sent.status)) return "not_sent";
+	if (SEND_STATUSES_WITH_UNKNOWN_OUTCOME.has(sent.status)) return "uncertain";
+	return sent.idempotent_replay === true ? "already_sent" : "sent";
+}
+/**
+* Summary for a 2xx send record whose status shows it did not go out
+* (`not_sent`) or that its result is indeterminate (`uncertain`).
+*/
+function formatSendRecordFailureSummary(noun, outcome, sent) {
+	const record = sent.idempotent_replay === true ? `the earlier identical attempt (sent id ${sent.id}) has status ${sent.status}` : `the send record (id ${sent.id}) has status ${sent.status}`;
+	if (outcome === "not_sent") return `${noun} not sent: ${record}. Nothing went out; fix the problem before retrying.`;
+	return `${noun} send outcome uncertain: ${record}. It may or may not have gone out. Do not resend blindly; check sent history first.`;
+}
+function describeSentStatus(status) {
+	if (status === "queued") return "queued for delivery";
+	if (status === "delivered") return "delivered";
+	return `status ${status}`;
+}
+function formatSentSummary(noun, sent) {
+	return `${noun} sent (${describeSentStatus(sent.status)}, id ${sent.id}). Do not resend.`;
+}
+function formatSendFailureSummary(noun, outcome, httpStatus) {
+	if (outcome === "not_sent") return `${noun} not sent: ${httpStatus === void 0 ? "the request failed before sending" : `the API rejected the request (HTTP ${httpStatus})`}. Nothing went out; fix the problem before retrying.`;
+	return `${noun} send outcome uncertain (${httpStatus === void 0 ? "no response from the API" : `HTTP ${httpStatus}`}): it may or may not have gone out. Do not resend blindly; check sent history first.`;
+}
+function priorRepliesThatWentOut(replies, options = {}) {
+	return (replies ?? []).filter((reply) => !SEND_STATUSES_THAT_DID_NOT_GO_OUT.has(reply.status) && reply.id !== options.excludeSentId);
+}
+function formatPriorRepliesWarning(prior) {
+	const latest = prior.at(-1);
+	if (!latest) return null;
+	return `This email already has ${prior.length === 1 ? "1 outgoing email" : `${prior.length} outgoing emails`}, most recently at ${latest.created_at} (sent id ${latest.id}). These may include activity updates and do not prove a completed answer. Sending this reply.`;
+}
+function formatPriorRepliesCheckSkipped(emailId, reason) {
+	return `Could not check whether you already replied to email ${emailId} (${reason}). Prior-reply check skipped; sending the reply anyway.`;
+}
+/**
+* Look up the inbound email and report replies to it that already
+* went out. Never throws: the check is advisory and must not block a
+* send, so every failure comes back as `skipped` with a reason the
+* caller surfaces.
+*/
+async function checkPriorReplies(params) {
+	try {
+		const result = await getEmail({
+			client: params.client,
+			path: { id: params.emailId },
+			responseStyle: "fields"
+		});
+		if (result.error) {
+			const status = apiResultHttpStatus(result);
+			return {
+				status: "skipped",
+				reason: status === void 0 ? "the email lookup failed" : `the email lookup returned HTTP ${status}`
+			};
+		}
+		const envelope = result.data;
+		const detail = envelope?.data ?? envelope;
+		if (!detail || !Array.isArray(detail.replies)) return {
+			status: "skipped",
+			reason: "the email lookup returned no reply history"
+		};
+		return {
+			status: "checked",
+			prior: priorRepliesThatWentOut(detail.replies),
+			detail
+		};
+	} catch (error) {
+		return {
+			status: "skipped",
+			reason: `the email lookup failed: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function commandFromArgv(argv) {
+	return argv.map(shellQuote).join(" ");
+}
+function buildFollowUpCommand(kind, description, argv, options = {}) {
+	const requiresMessage = options.requiresMessage ?? false;
+	return {
+		argv,
+		description,
+		command: commandFromArgv(argv),
+		kind,
+		placeholders: requiresMessage ? [{
+			description: "Replace with the message body before running.",
+			token: "<message>"
+		}] : [],
+		requires_message: requiresMessage
+	};
+}
+const SENT_HISTORY_CLOCK_SKEW_MS = 300 * 1e3;
+function sentHistoryWindowStart(attemptStartedAtIso) {
+	const started = Date.parse(attemptStartedAtIso);
+	if (!Number.isFinite(started)) return attemptStartedAtIso;
+	return new Date(started - SENT_HISTORY_CLOCK_SKEW_MS).toISOString();
+}
+/** Header rule for Idempotency-Key: 1 to 255 printable ASCII characters. */
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{1,255}$/;
+const IDEMPOTENCY_KEY_FLAG_DESCRIPTION = "Idempotency key for this send (1 to 255 printable ASCII characters). Retrying with the same key returns the original send instead of sending twice. Defaults to a key derived from the request content and the current five-minute window, so an identical retry within that window is deduplicated and a deliberate repeat later still sends. To retry an uncertain send after that, pass the key it reported. Look a send up later with `primitive sent get --idempotency-key <key>`.";
+function assertValidIdempotencyKey(key) {
+	if (!IDEMPOTENCY_KEY_PATTERN.test(key)) throw new Errors.CLIError("--idempotency-key must be 1 to 255 printable ASCII characters with no spaces.", { exit: 2 });
+	return key;
+}
+const NON_CONTENT_SEND_FIELDS = new Set(["wait", "wait_timeout_ms"]);
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item ?? null)).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+	return JSON.stringify(value ?? null);
+}
+/**
+* How long a derived key stays the same. It matches the window the API
+* uses for the key it derives itself when a request carries none, so an
+* identical send repeated inside this window is deduplicated and a
+* deliberate repeat later (a digest, a heartbeat, the same short reply
+* on another day) still goes out, exactly as without a key. An explicit
+* --idempotency-key never expires.
+*/
+const DERIVED_IDEMPOTENCY_WINDOW_MS = 300 * 1e3;
+/**
+* The idempotency key a send uses when the caller passes none. It is a
+* hash of what is sent (and, for a reply, of the email replied to) and
+* of the current five-minute window, so dedup matches what the API did
+* before the CLI sent a key, while the CLI knows the key before the
+* request starts. That lets an uncertain outcome still report the key to
+* reconcile with, and to retry under with --idempotency-key.
+*/
+function deriveSendIdempotencyKey(kind, request, now = Date.now()) {
+	const content = Object.fromEntries(Object.entries(request).filter(([key]) => !NON_CONTENT_SEND_FIELDS.has(key)));
+	return `primitive-${kind}-${createHash("sha256").update(canonicalJson(content)).update(`:t${Math.floor(now / DERIVED_IDEMPOTENCY_WINDOW_MS)}`).digest("hex")}`;
+}
+/**
+* Identity fields every send, reply and chat `--json` envelope carries,
+* whatever the outcome. `sent_email_id` is null until a send record is
+* known; `idempotency_key` is known before the request starts, so an
+* uncertain outcome can be reconciled with
+* `primitive sent get --idempotency-key <key>`.
+*/
+function sendIdentityFields(params) {
+	return {
+		sent_email_id: params.sent?.id ?? null,
+		idempotency_key: params.idempotencyKey ?? params.sent?.client_idempotency_key ?? null
+	};
+}
+/**
+* Commands that inspect an existing send. None of them send again:
+* a caller that follows them after a failure cannot double-send.
+*/
+function buildSendCommandFollowUps(params) {
+	const commands = [];
+	if (params.sentId === null && params.outcome === "uncertain" && params.idempotencyKey) commands.push(buildFollowUpCommand("find_sent_email_by_idempotency_key", "Look up this attempt by its idempotency key before retrying", [
+		"primitive",
+		"sent",
+		"get",
+		"--idempotency-key",
+		params.idempotencyKey
+	]));
+	if (params.sentId !== null) commands.push(buildFollowUpCommand("inspect_sent_email", "Inspect the send and its delivery status", [
+		"primitive",
+		"sent",
+		"get",
+		"--id",
+		params.sentId
+	]));
+	if (params.outcome === "uncertain") commands.push(buildFollowUpCommand("list_recent_sent_emails", "Check sent history for this attempt before retrying", [
+		"primitive",
+		"sent",
+		"list",
+		"--date-from",
+		sentHistoryWindowStart(params.attemptStartedAtIso)
+	]));
+	return commands;
+}
+/**
+* Classify a `send` / `reply` API result, write the stderr summary,
+* and print stdout. Without `--json` stdout stays exactly what these
+* commands always printed (the SendMailResult, or `null`), so
+* existing `| jq` pipelines keep working; the outcome is on stderr
+* and in the exit code. With `--json` stdout is always an envelope,
+* whatever the outcome, and the summary is only its outcome_message.
+*/
+function reportSendCommandResult(params) {
+	const httpStatus = apiResultHttpStatus(params.result);
+	let outcome;
+	let outcomeMessage;
+	let sent = null;
+	let errorPayload = null;
+	if (params.result.error) {
+		errorPayload = extractErrorPayload(params.result.error);
+		params.onApiError(errorPayload);
+		const failure = classifySendError(httpStatus, errorPayload);
+		outcome = failure;
+		outcomeMessage = failure === "already_sent" ? formatDeletedEarlierSendNotice() : formatSendFailureSummary(params.noun, failure, httpStatus);
+		if (!params.json) params.writeStderr(`${outcomeMessage}\n`);
+	} else {
+		sent = params.result.data?.data ?? null;
+		if (sent === null) {
+			outcome = "uncertain";
+			outcomeMessage = `${params.noun} send outcome uncertain: the API accepted the request but returned no send record. Do not resend blindly; check sent history first.`;
+			errorPayload = { message: "The API returned no send record." };
+		} else {
+			outcome = successfulSendOutcome(sent);
+			outcomeMessage = outcome === "not_sent" || outcome === "uncertain" ? formatSendRecordFailureSummary(params.noun, outcome, sent) : outcome === "already_sent" ? formatAlreadySentNotice(sent) : formatSentSummary(params.noun, sent);
+		}
+		if (!params.json) params.writeStderr(`${outcomeMessage}\n`);
+	}
+	if (params.json) {
+		const envelope = {
+			outcome,
+			exit_code: sendOutcomeExitCode(outcome),
+			outcome_message: outcomeMessage,
+			...sendIdentityFields({
+				idempotencyKey: params.idempotencyKey,
+				sent
+			}),
+			sent,
+			http_status: httpStatus ?? null,
+			error: serializeErrorPayload(errorPayload),
+			follow_up_commands: buildSendCommandFollowUps({
+				attemptStartedAtIso: params.attemptStartedAtIso,
+				idempotencyKey: params.idempotencyKey,
+				outcome,
+				sentId: sent?.id ?? null
+			}),
+			...params.extraEnvelopeFields
+		};
+		params.log(JSON.stringify(envelope, null, 2));
+	} else if (!params.result.error) params.log(JSON.stringify(sent, null, 2));
+	return outcome;
+}
+/** JSON-safe form of an API error payload; `Error` objects stringify to `{}`. */
+function serializeErrorPayload(payload) {
+	if (!(payload instanceof Error)) return payload ?? null;
+	const serialized = {
+		name: payload.name,
+		message: payload.message
+	};
+	const cause = payload.cause;
+	if (cause && typeof cause.code === "string") serialized.code = cause.code;
+	return serialized;
+}
+/**
+* Envelope for a `send` / `reply` that threw instead of returning an
+* API result. Printed in --json mode so stdout carries an envelope for
+* every outcome. Before the request starts (bad input, missing auth,
+* unreadable attachment) nothing went out; after it starts the
+* outcome is unknown.
+*/
+function buildThrownSendFailureEnvelope(params) {
+	const message = params.error instanceof Error ? params.error.message : String(params.error);
+	const outcome = params.requestStarted ? "uncertain" : "not_sent";
+	return {
+		outcome,
+		exit_code: params.requestStarted ? sendOutcomeExitCode("uncertain") : thrownErrorExitCode(params.error),
+		outcome_message: formatSendFailureSummary(params.noun, outcome, void 0),
+		...sendIdentityFields({
+			idempotencyKey: params.idempotencyKey,
+			sent: null
+		}),
+		sent: null,
+		http_status: null,
+		error: { message },
+		follow_up_commands: params.requestStarted && params.attemptStartedAtIso ? buildSendCommandFollowUps({
+			attemptStartedAtIso: params.attemptStartedAtIso,
+			idempotencyKey: params.idempotencyKey,
+			outcome,
+			sentId: null
+		}) : [],
+		...params.extraEnvelopeFields
+	};
+}
+/** Exit code oclif will use for a thrown error (2 for usage errors). */
+function thrownErrorExitCode(error) {
+	const exit = error?.oclif?.exit;
+	return typeof exit === "number" ? exit : 1;
+}
+//#endregion
+//#region src/oclif/interaction-actions.ts
+const HINTS = new Set([
+	"status",
+	"card",
+	"none",
+	"pending"
+]);
+/** A printable `<protocol>/<version>`; anything else is treated as unknown. */
+const KIND = /^[a-z][a-z0-9._-]{0,63}\/[1-9][0-9]{0,3}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function categoryOf(hint, kind, fyi, candidate) {
+	if (hint === "pending") return candidate ? "pending" : "ordinary";
+	if (hint === "card") switch (kind) {
+		case "x402.payment/1": return "payment";
+		case "primitive.contact/1": return "contact";
+		case "repeat.tick/1": return "repeat";
+		case "repeat.stop/1": return "repeat_stopped";
+		default: return "unsupported";
+	}
+	if (fyi) return "fyi";
+	if (hint === "status") return "signal";
+	return "ordinary";
+}
+function replyExpectation(category) {
+	switch (category) {
+		case "fyi":
+		case "signal":
+		case "repeat_stopped": return "no_reply";
+		case "payment":
+		case "contact": return "answer_with_command";
+		case "repeat": return "repeat";
+		case "unsupported": return "unsupported";
+		case "pending": return "read_again";
+		default: return "reply";
+	}
+}
+/**
+* The server's interaction facts for an email read, or null when the server
+* did not report `interaction_hint` (an older server). An unfamiliar hint is
+* treated as `none`, as the API documents.
+*/
+function readEmailInteraction(detail) {
+	const row = record(detail);
+	if (!row || typeof row.interaction_hint !== "string") return null;
+	const hint = HINTS.has(row.interaction_hint) ? row.interaction_hint : "none";
+	const rawKind = row.interaction_kind;
+	const kind = (hint === "card" || hint === "status") && typeof rawKind === "string" && KIND.test(rawKind) ? rawKind : null;
+	const fyi = row.fyi === true || record(row.collaboration)?.fyi === true;
+	const category = categoryOf(hint, kind, fyi, row.interaction_candidate === true);
+	const expectation = replyExpectation(category);
+	return {
+		hint,
+		kind,
+		fyi,
+		category,
+		plain_reply_completes: expectation === "reply" || expectation === "repeat",
+		no_reply_needed: expectation === "no_reply"
+	};
+}
+function replyAction(bin, id) {
+	return buildFollowUpCommand("reply", "Reply to the sender", [
+		bin,
+		"reply",
+		"--id",
+		id,
+		"--body",
+		"<message>"
+	], { requiresMessage: true });
+}
+/**
+* The commands that answer an email, best first. Empty when the email needs
+* no reply or this CLI cannot answer it. `repeatStoppable: false` (the
+* repeat's own part says only the sender can stop it) leaves out the stop.
+*/
+function interactionNextActions(interaction, emailId, options = {}) {
+	const bin = options.bin ?? "primitive";
+	if (!UUID.test(emailId)) return [];
+	const id = emailId.toLowerCase();
+	switch (interaction?.category ?? "ordinary") {
+		case "ordinary": return [replyAction(bin, id)];
+		case "payment": return [buildFollowUpCommand("inspect_payment", "Show the payment request's terms before paying", [
+			bin,
+			"payments",
+			"challenge-from-email",
+			"--id",
+			id
+		]), buildFollowUpCommand("pay", "Pay the payment request (signs with your wallet key and sends the payment)", [
+			bin,
+			"payments",
+			"pay-email",
+			"--in-reply-to",
+			id
+		])];
+		case "contact": return [buildFollowUpCommand("accept_contact", "Accept the contact request, if the owner's policy allows it", [
+			bin,
+			"contacts",
+			"accept",
+			"--id",
+			id
+		])];
+		case "repeat": {
+			const actions = [replyAction(bin, id)];
+			if (options.repeatStoppable !== false) actions.push(buildFollowUpCommand("stop_repeat", "Stop the repeating message once its goal is met", [
+				bin,
+				"repeat",
+				"stop",
+				"--id",
+				id
+			]));
+			return actions;
+		}
+		case "pending": return [buildFollowUpCommand("read_again", "Read the email again once the server has finished checking it", [
+			bin,
+			"emails",
+			"get",
+			"--id",
+			id,
+			"--brief"
+		])];
+		default: return [];
+	}
+}
+/**
+* One human line naming how to answer the email, or null for ordinary mail
+* (and older servers), where `primitive reply` is the answer. Contains only
+* server-decided values and fixed text, never anything the sender wrote.
+*/
+function interactionHumanLine(interaction, actions) {
+	if (!interaction) return null;
+	const command = (kind) => actions.find((action) => action.kind === kind)?.command;
+	const kind = interaction.kind ?? "unknown kind";
+	switch (interaction.category) {
+		case "fyi": return "Informational (fyi): no reply needed, not even another fyi.";
+		case "signal": return `Status signal (${kind}): no reply needed.`;
+		case "repeat_stopped": return `Notice that a repeating message stopped (${kind}): no reply needed.`;
+		case "payment": {
+			const inspect = command("inspect_payment");
+			const pay = command("pay");
+			return inspect && pay ? `Payment interaction (${kind}). If it requests payment, review it with ${inspect} and pay with ${pay}. A plain reply does not pay or decline it.` : null;
+		}
+		case "contact": {
+			const accept = command("accept_contact");
+			return accept ? `Contact interaction (${kind}). If it is a contact request, accept it under the owner's policy with ${accept}. A plain reply does not accept it.` : null;
+		}
+		case "repeat": {
+			const stop = command("stop_repeat");
+			return stop ? `Repeating message (${kind}). Reply if it asks for an answer; stop it once its goal is met with ${stop}.` : `Repeating message (${kind}). Reply if it asks for an answer; only the sender can stop it.`;
+		}
+		case "unsupported": return `Interaction (${kind}) that this CLI cannot answer. A plain reply does not complete it.`;
+		case "pending": {
+			const again = command("read_again");
+			return again ? `Primitive has not finished checking this email for an interaction. Read it again before answering: ${again}` : null;
+		}
+		default: return null;
+	}
+}
+/** The label a wake notice carries: the interaction kind, `fyi`, or null. */
+function wakeInteractionLabel(detail) {
+	const interaction = readEmailInteraction(detail);
+	if (!interaction) return null;
+	if (interaction.hint === "card") return interaction.kind ?? "unknown";
+	if (interaction.fyi) return "fyi";
+	return null;
+}
+/** The category a wake label stands for, or null for an invalid label. */
+function wakeLabelCategory(label) {
+	if (!isWakeInteractionLabel(label)) return null;
+	if (label === "fyi") return "fyi";
+	return categoryOf("card", label === "unknown" ? null : label, false, false);
+}
+/**
+* The fixed wake sentences, keyed by reply expectation. The Claude hook
+* scripts in bin/ carry copies (they run standalone); a test keeps them equal.
+*/
+const WAKE_SENTENCES = {
+	reply: "",
+	read_again: "",
+	no_reply: " It needs no reply.",
+	answer_with_command: " It is an interaction a plain reply does not complete; the brief names the command that answers it.",
+	repeat: " It is a repeating message; the brief says how to answer it and whether you can stop it.",
+	unsupported: " It is an interaction this CLI cannot answer; a plain reply does not complete it."
+};
+/**
+* The sentence a wake line adds after its read command for an interaction
+* label: empty for ordinary mail and for anything that is not a valid label.
+*/
+function wakeInteractionSentence(label) {
+	const category = wakeLabelCategory(label);
+	return category ? WAKE_SENTENCES[replyExpectation(category)] : "";
+}
+/** Accepts only labels `wakeInteractionLabel` can produce. */
+function isWakeInteractionLabel(value) {
+	return typeof value === "string" && (value === "fyi" || value === "unknown" || KIND.test(value));
+}
+/**
+* Warning for a plain (prose) reply to `detail`, or null when a plain reply
+* is a fine answer. Never refuses: the caller still sends.
+*/
+function replyInteractionWarning(detail, emailId) {
+	const interaction = readEmailInteraction(detail);
+	if (!interaction || !UUID.test(emailId)) return null;
+	const id = emailId.toLowerCase();
+	const kind = interaction.kind;
+	const label = kind ?? "unknown kind";
+	const base = {
+		email_id: id,
+		kind,
+		category: interaction.category
+	};
+	const expected = interactionNextActions(interaction, id);
+	const commandFor = (actionKind) => expected.find((action) => action.kind === actionKind)?.command;
+	const expectation = replyExpectation(interaction.category);
+	if (expectation === "reply" || expectation === "repeat") return null;
+	switch (interaction.category) {
+		case "payment": return {
+			...base,
+			code: "interaction_not_answered",
+			message: `Warning: email ${id} is a payment interaction (${label}). A plain reply does not pay or decline it; sending anyway. To pay: ${commandFor("pay")}`,
+			expected
+		};
+		case "contact": return {
+			...base,
+			code: "interaction_not_answered",
+			message: `Warning: email ${id} is a contact interaction (${label}). A plain reply does not accept it; sending anyway. To accept: ${commandFor("accept_contact")}`,
+			expected
+		};
+		case "unsupported": return {
+			...base,
+			code: "interaction_not_answered",
+			message: `Warning: email ${id} is an interaction (${label}) that this CLI cannot answer. A plain reply does not complete it; sending anyway.`,
+			expected
+		};
+		case "fyi": return {
+			...base,
+			code: "reply_not_needed",
+			message: `Warning: email ${id} is informational (fyi) and needs no reply; sending anyway.`,
+			expected
+		};
+		case "signal": return {
+			...base,
+			code: "reply_not_needed",
+			message: `Warning: email ${id} is a status signal (${label}) and needs no reply; sending anyway.`,
+			expected
+		};
+		case "repeat_stopped": return {
+			...base,
+			code: "reply_not_needed",
+			message: `Warning: email ${id} is a notice that a repeating message stopped (${label}) and needs no reply; sending anyway.`,
+			expected
+		};
+		default: return null;
+	}
+}
+//#endregion
+export { queryUsesAwaiting as $, listContacts as $t, thrownErrorExitCode as A, setMemory as An, deleteRoute as At, surfaceUnauthorizedHint as B, updateRepeatingSend as Bn, getEmail as Bt, priorRepliesThatWentOut as C, runWakeSchedule as Cn, createFunction as Ct, sentHistoryWindowStart as D, sendEmail as Dn, deleteAgentContact as Dt, sendOutcomeExitCode as E, semanticSearch as En, createWakeSchedule as Et, extractErrorCode as F, stopRepeatFromEmail as Fn, getAgentContactPolicy as Ft, ReplyStateUnsupportedError as G, verifyAgentSignup as Gn, getMemory as Gt, AWAITING_FLAG_DESCRIPTION as H, updateWakeAuthorization as Hn, getFunctionRouting as Ht, extractErrorPayload as I, testFunction as In, getContact as It, ensureSearchReportsReplyState as J, getSentEmail as Jt, assertAwaitingFilterRows as K, getOrgRoutingTopology as Kt, formatErrorPayload as L, unsetFunctionRoute as Ln, getConversation as Lt, API_ERROR_CODES as M, startAgentClaim as Mn, deleteWakeSchedule as Mt, TIME_FLAG_DESCRIPTION as N, startAgentSignup as Nn, downloadEmailAttachmentPart as Nt, serializeErrorPayload as O, setFunctionRoute as On, deleteContact as Ot, createOperationCommand as P, startCliLogin as Pn, getAccount as Pt, isAwaitingRejectedError as Q, listAgentNetworks as Qt, readTextFileFlag as R, updateDefaultNetworkMember as Rn, getCreditBalance as Rt, formatSendRecordFailureSummary as S, resendAgentSignupVerification as Sn, createEndpoint as St, sendIdentityFields as T, searchMemories as Tn, createWakeAuthorization as Tt, AWAITING_VALUES as U, updateWakeSchedule as Un, getFunctionTestRunTrace as Ut, writeErrorWithHints as V, updateRoute as Vn, getFunction as Vt, REPLY_STATE_UNSUPPORTED_CODE as W, verifyAgentClaim as Wn, getInboxStatus as Wt, formatRepliesCell as X, getWakeSchedule as Xt, formatAwaitingCell as Y, getThread as Yt, hasReplyState as Z, listAgentContacts as Zt, deriveSendIdempotencyKey as _, putContact as _n, resolveCliApiRequestConfig as _t, replyExpectation as a, listFunctionLogs as an, AutomatedFilterUnsupportedError as at, formatPriorRepliesWarning as b, reorderRoutes as bn, cliLogout as bt, wakeInteractionSentence as c, listRoutes as cn, ensureSearchReportsAutomated as ct, apiResultHttpStatus as d, listWakeDispatches as dn, isAutomatedRejectedError as dt, listDefaultNetworkAgents as en, formatAlreadySentNotice as et, assertValidIdempotencyKey as f, listWakeSchedules as fn, queryUsesAutomated as ft, classifySendError as g, putAgentContactPolicy as gn, refreshStoredCliCredentials as gt, checkPriorReplies as h, putAgentContact as hn, createCliApiClient as ht, readEmailInteraction as i, listEndpoints as in, AUTOMATED_VALUES as it, API_BASE_URL_FLAG_DESCRIPTION as j, simulateRoute as jn, deleteWakeAuthorization as jt, successfulSendOutcome as k, setFunctionSecret as kn, deleteMemory as kt, IDEMPOTENCY_KEY_FLAG_DESCRIPTION as l, listSentEmails as ln, expectedAutomatedVerdicts as lt, buildThrownSendFailureEnvelope as m, pullWebhookEvent as mn, createAuthenticatedCliApiClient as mt, interactionNextActions as n, listDomains as nn, AUTOMATED_FILTER_UNSUPPORTED_CODE as nt, replyInteractionWarning as o, listFunctions as on, assertAutomatedVerdict as ot, buildFollowUpCommand as p, pollCliLogin as pn, SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE as pt, awaitingRejectedError as q, getRepeatingSend as qt, isWakeInteractionLabel as r, listEmails as rn, AUTOMATED_FLAG_DESCRIPTION as rt, wakeInteractionLabel as s, listRepeatingSends as sn, automatedRejectedError as st, interactionHumanLine as t, listDefaultNetworkMembers as tn, writeIdempotentReplayBannerIfReplay as tt, SEND_OUTCOME_HELP as u, listWakeAuthorizations as un, hasAutomatedVerdict as ut, formatDeletedEarlierSendNotice as v, redeemCreditCode as vn, addDefaultNetworkMember as vt, reportSendCommandResult as w, searchEmails as wn, createRoute as wt, formatSendFailureSummary as x, replyToEmail as xn, completeWebhookEvent as xt, formatPriorRepliesCheckSkipped as y, removeDefaultNetworkMember as yn, checkDefaultNetworkContactAdmission as yt, runWithTiming as z, updateFunction as zn, getDefaultNetworkAgent as zt };