@primitivedotdev/cli 0.30.2 → 0.31.0

package/dist/oclif/index.js

@@ -2413,6 +2413,15 @@ const openapiDocument = {
 					},
 					"description": "Filter by domain ID."
 				},
+				{
+					"name": "reply_to_sent_email_id",
+					"in": "query",
+					"schema": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"description": "Filter to inbound emails that are replies to a specific\noutbound send. The value is a `sent_emails.id` (UUID). At\ninbound ingest, Primitive matches the parsed In-Reply-To\nheader (or References as a fallback) against\n`sent_emails.message_id` in the same org and records the\nresolved id on `emails.reply_to_sent_email_id`. This filter\nis the strict-threading lookup behind `primitive chat` and\nany UI that wants to show the inbound reply to a given\nsend. NULL on inbound that isn't a threaded reply to one\nof your sends, so existing emails received before this\ningestion landed will not match.\n"
+				},
 				{
 					"name": "status",
 					"in": "query",
@@ -4666,6 +4675,11 @@ const openapiDocument = {
 						"type": "array",
 						"description": "Sent emails recorded as replies to this inbound, in send\norder (ascending). Populated when a customer's send-mail\nrequest carries an `in_reply_to` Message-ID that matches\nthis inbound's `message_id` in the same org. Includes\nattempts that were gate-denied, so the array reflects every\nrecorded reply attempt regardless of outcome.\n",
 						"items": { "$ref": "#/components/schemas/EmailDetailReply" }
+					},
+					"reply_to_sent_email_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "The `sent_emails.id` of the outbound this inbound was a\nreply to, when resolvable. Set at inbound ingest by\nmatching the parsed In-Reply-To (or References, as a\nfallback) against `sent_emails.message_id` in the same\norg. The mirror of `sent_emails.in_reply_to_email_id` for\nthe inbound side of a thread. NULL when the inbound is\nnot a threaded reply to one of your sends, when neither\nheader survived the path through intermediate MTAs, or on\ninbound received before this auto-link landed.\n"
 					}
 				},
 				"required": [
@@ -7336,6 +7350,11 @@ const operationManifest = [
 							"created_at"
 						]
 					}
+				},
+				"reply_to_sent_email_id": {
+					"type": ["string", "null"],
+					"format": "uuid",
+					"description": "The `sent_emails.id` of the outbound this inbound was a\nreply to, when resolvable. Set at inbound ingest by\nmatching the parsed In-Reply-To (or References, as a\nfallback) against `sent_emails.message_id` in the same\norg. The mirror of `sent_emails.in_reply_to_email_id` for\nthe inbound side of a thread. NULL when the inbound is\nnot a threaded reply to one of your sends, when neither\nheader survived the path through intermediate MTAs, or on\ninbound received before this auto-link landed.\n"
 				}
 			},
 			"required": [
@@ -7588,6 +7607,13 @@ const operationManifest = [
 				"required": false,
 				"type": "string"
 			},
+			{
+				"description": "Filter to inbound emails that are replies to a specific\noutbound send. The value is a `sent_emails.id` (UUID). At\ninbound ingest, Primitive matches the parsed In-Reply-To\nheader (or References as a fallback) against\n`sent_emails.message_id` in the same org and records the\nresolved id on `emails.reply_to_sent_email_id`. This filter\nis the strict-threading lookup behind `primitive chat` and\nany UI that wants to show the inbound reply to a given\nsend. NULL on inbound that isn't a threaded reply to one\nof your sends, so existing emails received before this\ningestion landed will not match.\n",
+				"enum": null,
+				"name": "reply_to_sent_email_id",
+				"required": false,
+				"type": "string"
+			},
 			{
 				"description": "Filter by inbound email lifecycle status.",
 				"enum": null,
@@ -11062,7 +11088,7 @@ function resolveConfigEnvironment(config) {
 	} : null;
 }
 function upsertCliEnvironment(params) {
-	const name = normalizeCliEnvironmentName(params.environmentName ?? DEFAULT_ENVIRONMENT);
+	const name = normalizeCliEnvironmentName(params.environmentName ?? "default");
 	const existing = params.config.environments[name] ?? {};
 	const nextHeaders = { ...existing.headers ?? {} };
 	for (const assignment of params.headers ?? []) {
@@ -11139,6 +11165,7 @@ function resolveCliApiRequestConfig(params) {
 	const currentEnvironment = resolveConfigEnvironment(loadCliConfig(params.configDir));
 	const configuredApiBaseUrl1 = currentEnvironment?.config.api_base_url_1;
 	const configuredApiBaseUrl2 = currentEnvironment?.config.api_base_url_2;
+	if (currentEnvironment !== null && currentEnvironment.name !== "default" && params.apiBaseUrl1 === void 0 && configuredApiBaseUrl1 === void 0) throw new Errors.CLIError(`The active Primitive CLI environment \`${currentEnvironment.name}\` does not specify an api_base_url_1. Set one with \`primitive config set --environment ${currentEnvironment.name} --api-base-url-1 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 apiBaseUrl1 = params.apiBaseUrl1 !== void 0 ? normalizeApiBaseUrl1(params.apiBaseUrl1) : configuredApiBaseUrl1;
 	const apiBaseUrl2 = params.apiBaseUrl2 !== void 0 ? normalizeApiBaseUrl2(params.apiBaseUrl2) : configuredApiBaseUrl2;
 	return {
@@ -11410,26 +11437,26 @@ function coerceParameterValue(parameter, value) {
 	if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") return value;
 	throw new Errors.CLIError(`Unsupported flag value for --${parameter.name}`);
 }
-function cliError$5(message) {
+function cliError$6(message) {
 	return new Errors.CLIError(message, { exit: 1 });
 }
 function parseJson(source, flagLabel) {
 	try {
 		return JSON.parse(source);
 	} catch (error) {
-		throw cliError$5(`${flagLabel} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+		throw cliError$6(`${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$5("Use either --raw-body or --body-file, not both");
+	if (bodyFile && rawBody) throw cliError$6("Use either --raw-body or --body-file, not both");
 	if (typeof bodyFile === "string") {
 		let contents;
 		try {
 			contents = readFileSync(bodyFile, "utf8");
 		} catch (error) {
-			throw cliError$5(`Could not read --body-file ${bodyFile}: ${error instanceof Error ? error.message : String(error)}`);
+			throw cliError$6(`Could not read --body-file ${bodyFile}: ${error instanceof Error ? error.message : String(error)}`);
 		}
 		return parseJson(contents, `--body-file ${bodyFile}`);
 	}
@@ -11439,7 +11466,7 @@ function readTextFileFlag(path, flagLabel) {
 	try {
 		return readFileSync(path, "utf8");
 	} catch (error) {
-		throw cliError$5(`Could not read ${flagLabel} ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		throw cliError$6(`Could not read ${flagLabel} ${path}: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
 function extractErrorPayload(raw) {
@@ -11504,15 +11531,27 @@ function writeErrorWithHints(payload) {
 	}
 	if (code in NETWORK_ERROR_HINTS) process.stderr.write(`${NETWORK_ERROR_HINTS[code]}\n`);
 }
-function removeStaleSavedCredentialOnUnauthorized(params) {
-	if (extractErrorCode(params.payload) !== API_ERROR_CODES.unauthorized || params.auth.source !== "stored") return false;
+/**
+* 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.apiBaseUrl1 !== params.auth.credentials.api_base_url_1) {
-		process.stderr.write("Saved Primitive CLI credentials were rejected by the overridden API base URL. The local credential was not removed; unset PRIMITIVE_API_BASE_URL_1, run `primitive config reset` to clear configured URL overrides, or run `primitive logout` to remove the stored credential.\n");
-		return false;
+		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_1, run `primitive config reset` to clear configured URL overrides, or run `primitive logout` to remove the stored credential.\n");
+		return;
 	}
-	deleteCliCredentials(params.configDir);
-	process.stderr.write("Removed saved Primitive CLI credentials because the backing API key is no longer valid. Run `primitive login` to create a new one.\n");
-	return true;
+	process.stderr.write("Your saved Primitive CLI credential 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 login` to mint a fresh credential.\n");
 }
 function formatElapsed(ms) {
 	const seconds = ms / 1e3;
@@ -11676,7 +11715,7 @@ function createOperationCommand(operation) {
 				if (result.error) {
 					const errorPayload = extractErrorPayload(result.error);
 					writeErrorWithHints(errorPayload);
-					removeStaleSavedCredentialOnUnauthorized({
+					surfaceUnauthorizedHint({
 						auth,
 						baseUrlOverridden,
 						configDir: this.config.configDir,
@@ -11737,6 +11776,384 @@ 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/outbound-defaults.ts
+const SUBJECT_MAX_LENGTH = 200;
+function deriveSubject(body) {
+	for (const line of body.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		return trimmed.length > SUBJECT_MAX_LENGTH ? `${trimmed.slice(0, SUBJECT_MAX_LENGTH - 3)}...` : trimmed;
+	}
+	return "Message";
+}
+function isVerifiedDomain(domain) {
+	return domain.is_active === true;
+}
+async function pickDefaultFromAddress(apiClient, authFailureContext) {
+	const result = await listDomains({
+		client: apiClient.client,
+		responseStyle: "fields"
+	});
+	if (result.error) {
+		const errorPayload = extractErrorPayload(result.error);
+		if (extractErrorCode(errorPayload) === API_ERROR_CODES.unauthorized) {
+			writeErrorWithHints(errorPayload);
+			surfaceUnauthorizedHint({
+				...authFailureContext,
+				payload: errorPayload
+			});
+			throw new Errors.CLIError("Cannot send: API key is missing or invalid (see hint above).", { exit: 1 });
+		}
+		throw new Errors.CLIError(`Could not look up your verified domains to default --from. Pass --from explicitly. Underlying error: ${formatErrorPayload(errorPayload)}`);
+	}
+	const first = result.data?.data?.find(isVerifiedDomain);
+	if (!first) throw new Errors.CLIError("No active verified outbound domain found on this account; pass --from explicitly. To set up outbound, claim a domain via `primitive domains add` and verify it.");
+	return `agent@${first.domain}`;
+}
+//#endregion
+//#region src/oclif/commands/emails-poll.ts
+function quoteDslValue(value) {
+	if (/^[^\s"]+$/.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function combineQ(q, domain) {
+	const parts = [q?.trim(), domain ? `domain:${quoteDslValue(domain.trim())}` : void 0].filter((part) => Boolean(part));
+	return parts.length > 0 ? parts.join(" ") : void 0;
+}
+function normalizeIsoDate(value, label) {
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime())) throw new Error(`${label} must be a valid date or ISO-8601 timestamp.`);
+	return parsed.toISOString();
+}
+function filtersFromFlags(flags) {
+	return {
+		body: flags.body,
+		domain: flags.domain,
+		domainId: flags["domain-id"],
+		from: flags.from,
+		hasAttachment: flags["has-attachment"],
+		q: flags.q,
+		replyToSentEmailId: flags["reply-to-sent-email-id"],
+		spamScoreGte: flags["spam-score-gte"],
+		spamScoreLt: flags["spam-score-lt"],
+		subject: flags.subject,
+		to: flags.to
+	};
+}
+function sinceFromFlags(flags) {
+	if (flags.since) return normalizeIsoDate(flags.since, "--since");
+	return flags["include-existing"] ? void 0 : (/* @__PURE__ */ new Date()).toISOString();
+}
+function buildEmailSearchQuery(params) {
+	const query = {
+		include_facets: "false",
+		limit: params.pageSize,
+		snippet: "false",
+		sort: "received_at_asc"
+	};
+	const q = combineQ(params.filters.q, params.filters.domain);
+	if (q) query.q = q;
+	if (params.filters.body) query.body = params.filters.body;
+	if (params.filters.domainId) query.domain_id = params.filters.domainId;
+	if (params.filters.from) query.from = params.filters.from;
+	if (params.filters.hasAttachment !== void 0) query.has_attachment = params.filters.hasAttachment ? "true" : "false";
+	if (params.filters.spamScoreGte !== void 0) query.spam_score_gte = params.filters.spamScoreGte;
+	if (params.filters.spamScoreLt !== void 0) query.spam_score_lt = params.filters.spamScoreLt;
+	if (params.filters.replyToSentEmailId) query.reply_to_sent_email_id = params.filters.replyToSentEmailId;
+	if (params.filters.subject) query.subject = params.filters.subject;
+	if (params.filters.to) query.to = params.filters.to;
+	if (params.since) query.date_from = params.since;
+	if (params.cursor) query.cursor = params.cursor;
+	return query;
+}
+function encodeReceivedAtSearchCursor(email) {
+	const raw = `r|${new Date(email.received_at).toISOString()}|${email.id}`;
+	return Buffer.from(raw, "utf8").toString("base64url");
+}
+function cursorFromRows(rows) {
+	const last = rows.at(-1);
+	return last ? encodeReceivedAtSearchCursor(last) : null;
+}
+function collectNewAcceptedEmails(rows, seenIds) {
+	const fresh = [];
+	for (const row of rows) {
+		if (row.status !== "accepted" && row.status !== "completed") continue;
+		if (seenIds.has(row.id)) continue;
+		seenIds.add(row.id);
+		fresh.push(row);
+	}
+	return fresh;
+}
+async function fetchEmailSearchPage(params) {
+	const result = await searchEmails({
+		client: params.apiClient.client,
+		query: buildEmailSearchQuery({
+			cursor: params.cursor,
+			filters: params.filters,
+			pageSize: params.pageSize,
+			since: params.since
+		}),
+		responseStyle: "fields"
+	});
+	if (result.error) return {
+		ok: false,
+		error: result.error
+	};
+	const envelope = result.data;
+	const rows = envelope?.data ?? [];
+	return {
+		ok: true,
+		cursor: envelope?.meta.cursor ?? cursorFromRows(rows),
+		rows
+	};
+}
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+//#region src/oclif/commands/chat.ts
+const DEFAULT_CHAT_TIMEOUT_SECONDS = 120;
+const DEFAULT_STRICT_PHASE_SECONDS = 60;
+function cliError$5(message) {
+	return new Errors.CLIError(message, { exit: 1 });
+}
+async function readStdinToString() {
+	if (process.stdin.isTTY) throw cliError$5("No message provided. Pass the message as the second positional argument or pipe it via stdin.");
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+var ChatCommand = class ChatCommand extends Command {
+	static description = `Send a message to an address and wait for the reply.
+
+  This is the first-party verb for talking to agents that live behind
+  email addresses. \`primitive send\` is transport (fire-and-forget);
+  \`primitive chat\` is semantic (send + wait for the threaded reply).
+
+  The message body can be given as the second positional argument or
+  piped via stdin. The reply body is written to stdout; --json emits a
+  structured envelope with both sides of the exchange.
+
+  Matching the reply: the wait phase polls inbound mail filtered by
+  the recipient as sender and the send time as a lower bound. The
+  first match is taken; the full inbound row is then fetched for the
+  body. Exits non-zero on timeout.`;
+	static summary = "Chat with an agent over email (send and wait for the reply)";
+	static examples = [
+		"<%= config.bin %> chat help@agent.acme.dev 'how do I rotate my API key?'",
+		"cat error.log | <%= config.bin %> chat help@agent.acme.dev --subject 'webhook 401s'",
+		"<%= config.bin %> chat help@agent.acme.dev 'follow up question' --json",
+		"<%= config.bin %> chat help@agent.acme.dev 'one more thing' --timeout 300"
+	];
+	static args = {
+		recipient: Args.string({
+			description: "Address to chat with (e.g. help@agent.acme.dev).",
+			required: true
+		}),
+		message: Args.string({ description: "Message body. If omitted, read from stdin." })
+	};
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url-1": Flags.string({
+			description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+			env: "PRIMITIVE_API_BASE_URL_1",
+			hidden: true
+		}),
+		"api-base-url-2": Flags.string({
+			description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+			env: "PRIMITIVE_API_BASE_URL_2",
+			hidden: true
+		}),
+		from: Flags.string({ description: "Sender address. Defaults to agent@<your-first-verified-outbound-domain>." }),
+		subject: Flags.string({ description: "Subject line. Defaults to the first line of the message when omitted." }),
+		"in-reply-to": Flags.string({ description: "Message-Id of the parent email to thread this against. Use when continuing a prior conversation from outside the CLI; for an inbound you received via Primitive, prefer `primitive reply --id <inbound-id>`." }),
+		json: Flags.boolean({ description: "Emit a structured JSON envelope { sent, reply } on stdout instead of just the reply body." }),
+		timeout: Flags.integer({
+			default: DEFAULT_CHAT_TIMEOUT_SECONDS,
+			description: "Seconds to wait for a reply before exiting non-zero; 0 waits forever.",
+			min: 0
+		}),
+		"strict-phase-seconds": Flags.integer({
+			default: DEFAULT_STRICT_PHASE_SECONDS,
+			description: "Seconds to wait in strict-threading mode (filter by reply_to_sent_email_id) before falling back to time-window matching. Set to the full --timeout to disable the fallback; --strict-only is the explicit way to do that.",
+			min: 1
+		}),
+		"strict-only": Flags.boolean({ description: "Disable the time-window fallback. Only accept inbounds whose threading headers (In-Reply-To / References) resolve to this send. Recommended when correctness matters more than success rate (e.g. agents talking to agents)." }),
+		interval: Flags.integer({
+			default: 2,
+			description: "Seconds between polls while waiting for the reply.",
+			min: 1
+		}),
+		"page-size": Flags.integer({
+			default: 50,
+			description: "Inbound emails to fetch per poll while waiting (1-100). Internal tuning knob.",
+			max: 100,
+			min: 1,
+			hidden: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { args, flags } = await this.parse(ChatCommand);
+		const message = args.message !== void 0 && args.message !== "" ? args.message : await readStdinToString();
+		if (!message.trim()) throw cliError$5("Message body is empty.");
+		await runWithTiming(flags.time, async () => {
+			const { apiClient, auth, baseUrlOverridden } = createAuthenticatedCliApiClient({
+				apiKey: flags["api-key"],
+				apiBaseUrl1: flags["api-base-url-1"],
+				apiBaseUrl2: flags["api-base-url-2"],
+				configDir: this.config.configDir
+			});
+			const authFailureContext = {
+				auth,
+				baseUrlOverridden,
+				configDir: this.config.configDir
+			};
+			const from = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
+			const subject = flags.subject ?? deriveSubject(message);
+			const sentAtIso = (/* @__PURE__ */ new Date()).toISOString();
+			const sendResult = await sendEmail({
+				body: {
+					from,
+					to: args.recipient,
+					subject,
+					body_text: message,
+					...flags["in-reply-to"] !== void 0 ? { in_reply_to: flags["in-reply-to"] } : {}
+				},
+				client: apiClient._sendClient,
+				responseStyle: "fields"
+			});
+			if (sendResult.error) {
+				const errorPayload = extractErrorPayload(sendResult.error);
+				writeErrorWithHints(errorPayload);
+				surfaceUnauthorizedHint({
+					...authFailureContext,
+					payload: errorPayload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			const sent = sendResult.data?.data;
+			if (!sent) throw cliError$5("Send succeeded but the API returned no data.");
+			const reply = await waitForReply({
+				apiClient,
+				authFailureContext,
+				from,
+				interval: flags.interval,
+				pageSize: flags["page-size"],
+				recipient: args.recipient,
+				sentAtIso,
+				sentId: sent.id,
+				strictOnly: flags["strict-only"],
+				strictPhaseSeconds: flags["strict-phase-seconds"],
+				timeoutSeconds: flags.timeout
+			});
+			if (reply === null) {
+				process.stderr.write(`Timed out after ${flags.timeout}s waiting for a reply from ${args.recipient}.\n`);
+				process.exitCode = 1;
+				return;
+			}
+			if (flags.json) {
+				const envelope = {
+					sent,
+					reply
+				};
+				this.log(JSON.stringify(envelope, null, 2));
+			} else {
+				const body = reply.body_text ?? reply.body_html ?? "";
+				this.log(body);
+			}
+		});
+	}
+};
+async function waitForReply(params) {
+	const totalDeadline = params.timeoutSeconds === 0 ? null : Date.now() + params.timeoutSeconds * 1e3;
+	const strictDeadlineFromBudget = Date.now() + params.strictPhaseSeconds * 1e3;
+	const strictDeadline = params.strictOnly ? totalDeadline : totalDeadline === null ? strictDeadlineFromBudget : Math.min(strictDeadlineFromBudget, totalDeadline);
+	const phases = [{
+		label: "strict",
+		filters: { replyToSentEmailId: params.sentId },
+		deadline: strictDeadline
+	}];
+	if (!params.strictOnly) phases.push({
+		label: "fallback",
+		filters: {
+			from: params.recipient,
+			to: params.from
+		},
+		deadline: totalDeadline
+	});
+	let strictFilterUnsupported = false;
+	for (const phase of phases) {
+		if (phase.label === "strict" && strictFilterUnsupported) continue;
+		const seenIds = /* @__PURE__ */ new Set();
+		let cursor = null;
+		while (true) {
+			if (phase.deadline !== null && Date.now() >= phase.deadline) break;
+			const page = await fetchEmailSearchPage({
+				apiClient: params.apiClient,
+				cursor,
+				filters: phase.filters,
+				pageSize: params.pageSize,
+				since: params.sentAtIso
+			});
+			if (!page.ok) {
+				const payload = extractErrorPayload(page.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					...params.authFailureContext,
+					payload
+				});
+				throw new Errors.CLIError("Failed to poll for reply.", { exit: 1 });
+			}
+			let lastAccepted;
+			for (let i = page.rows.length - 1; i >= 0; i--) {
+				const row = page.rows[i];
+				if (row.status === "accepted" || row.status === "completed") {
+					lastAccepted = row;
+					break;
+				}
+			}
+			if (lastAccepted) cursor = encodeReceivedAtSearchCursor(lastAccepted);
+			const matches = collectNewAcceptedEmails(page.rows, seenIds);
+			for (const match of matches) {
+				const full = await getEmail({
+					client: params.apiClient.client,
+					path: { id: match.id },
+					responseStyle: "fields"
+				});
+				if (full.error) {
+					const payload = extractErrorPayload(full.error);
+					writeErrorWithHints(payload);
+					surfaceUnauthorizedHint({
+						...params.authFailureContext,
+						payload
+					});
+					throw new Errors.CLIError(`Reply landed but fetching the full body failed (id=${match.id}).`, { exit: 1 });
+				}
+				const envelope = full.data;
+				const detail = envelope?.data ?? envelope ?? null;
+				if (!detail) throw new Errors.CLIError(`Reply landed but the email body could not be loaded (id=${match.id}).`, { exit: 1 });
+				if (phase.label === "strict" && detail.reply_to_sent_email_id !== params.sentId) {
+					if (!strictFilterUnsupported) process.stderr.write(params.strictOnly ? "Strict-phase reply matching is not supported by this Primitive API host; --strict-only requires server support so the command will exit without a match.\n" : "Strict-phase reply matching is not supported by this Primitive API host; falling back to time-window matching.\n");
+					strictFilterUnsupported = true;
+					continue;
+				}
+				return detail;
+			}
+			if (strictFilterUnsupported && phase.label === "strict") break;
+			if (lastAccepted !== void 0) continue;
+			if (phase.deadline !== null && Date.now() >= phase.deadline) break;
+			if (totalDeadline !== null && Date.now() >= totalDeadline) return null;
+			await sleep$1(params.interval * 1e3);
+		}
+	}
+	return null;
+}
+//#endregion
 //#region src/oclif/commands/config.ts
 function loadOrCreateConfig(configDir) {
 	return loadCliConfig(configDir) ?? emptyCliConfig();
@@ -11748,8 +12165,7 @@ function redactConfig(config) {
 	};
 }
 var ConfigSetCommand = class ConfigSetCommand extends Command {
-	static hidden = true;
-	static summary = "Set hidden Primitive CLI request config";
+	static summary = "Set a Primitive CLI request environment";
 	static flags = {
 		environment: Flags.string({
 			char: "e",
@@ -11783,8 +12199,7 @@ var ConfigSetCommand = class ConfigSetCommand extends Command {
 	}
 };
 var ConfigUseCommand = class ConfigUseCommand extends Command {
-	static hidden = true;
-	static summary = "Switch active Primitive CLI request config";
+	static summary = "Switch the active Primitive CLI request environment";
 	static args = { environment: Args.string({
 		description: "Environment name to use",
 		required: true
@@ -11802,8 +12217,7 @@ var ConfigUseCommand = class ConfigUseCommand extends Command {
 	}
 };
 var ConfigListCommand = class ConfigListCommand extends Command {
-	static hidden = true;
-	static summary = "List hidden Primitive CLI request configs";
+	static summary = "List Primitive CLI request environments";
 	static flags = {
 		json: Flags.boolean({ description: "Print JSON" }),
 		"show-secrets": Flags.boolean({ description: "Show header values instead of redacting them" })
@@ -11833,8 +12247,7 @@ var ConfigListCommand = class ConfigListCommand extends Command {
 	}
 };
 var ConfigResetCommand = class ConfigResetCommand extends Command {
-	static hidden = true;
-	static summary = "Reset hidden Primitive CLI request config";
+	static summary = "Reset Primitive CLI request environments";
 	static flags = { environment: Flags.string({
 		char: "e",
 		description: "Only remove one environment"
@@ -11858,6 +12271,11 @@ var ConfigResetCommand = class ConfigResetCommand extends Command {
 		process.stderr.write(`Primitive CLI environment ${environment} removed.\n`);
 	}
 };
+var ConfigCommand = class extends ConfigListCommand {
+	static hidden = true;
+	static summary = "Manage Primitive CLI request environments";
+	static description = "Manage local Primitive CLI request environments for API endpoint overrides and request headers.";
+};
 //#endregion
 //#region src/oclif/commands/doctor.ts
 const MIN_NODE_MAJOR = 22;
@@ -12196,7 +12614,7 @@ var EmailsLatestCommand = class EmailsLatestCommand extends Command {
 			if (result.error) {
 				const errorPayload = extractErrorPayload(result.error);
 				writeErrorWithHints(errorPayload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					auth,
 					baseUrlOverridden,
 					configDir: this.config.configDir,
@@ -12222,104 +12640,6 @@ var EmailsLatestCommand = class EmailsLatestCommand extends Command {
 	}
 };
 //#endregion
-//#region src/oclif/commands/emails-poll.ts
-function quoteDslValue(value) {
-	if (/^[^\s"]+$/.test(value)) return value;
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
-}
-function combineQ(q, domain) {
-	const parts = [q?.trim(), domain ? `domain:${quoteDslValue(domain.trim())}` : void 0].filter((part) => Boolean(part));
-	return parts.length > 0 ? parts.join(" ") : void 0;
-}
-function normalizeIsoDate(value, label) {
-	const parsed = new Date(value);
-	if (Number.isNaN(parsed.getTime())) throw new Error(`${label} must be a valid date or ISO-8601 timestamp.`);
-	return parsed.toISOString();
-}
-function filtersFromFlags(flags) {
-	return {
-		body: flags.body,
-		domain: flags.domain,
-		domainId: flags["domain-id"],
-		from: flags.from,
-		hasAttachment: flags["has-attachment"],
-		q: flags.q,
-		spamScoreGte: flags["spam-score-gte"],
-		spamScoreLt: flags["spam-score-lt"],
-		subject: flags.subject,
-		to: flags.to
-	};
-}
-function sinceFromFlags(flags) {
-	if (flags.since) return normalizeIsoDate(flags.since, "--since");
-	return flags["include-existing"] ? void 0 : (/* @__PURE__ */ new Date()).toISOString();
-}
-function buildEmailSearchQuery(params) {
-	const query = {
-		include_facets: "false",
-		limit: params.pageSize,
-		snippet: "false",
-		sort: "received_at_asc"
-	};
-	const q = combineQ(params.filters.q, params.filters.domain);
-	if (q) query.q = q;
-	if (params.filters.body) query.body = params.filters.body;
-	if (params.filters.domainId) query.domain_id = params.filters.domainId;
-	if (params.filters.from) query.from = params.filters.from;
-	if (params.filters.hasAttachment !== void 0) query.has_attachment = params.filters.hasAttachment ? "true" : "false";
-	if (params.filters.spamScoreGte !== void 0) query.spam_score_gte = params.filters.spamScoreGte;
-	if (params.filters.spamScoreLt !== void 0) query.spam_score_lt = params.filters.spamScoreLt;
-	if (params.filters.subject) query.subject = params.filters.subject;
-	if (params.filters.to) query.to = params.filters.to;
-	if (params.since) query.date_from = params.since;
-	if (params.cursor) query.cursor = params.cursor;
-	return query;
-}
-function encodeReceivedAtSearchCursor(email) {
-	const raw = `r|${new Date(email.received_at).toISOString()}|${email.id}`;
-	return Buffer.from(raw, "utf8").toString("base64url");
-}
-function cursorFromRows(rows) {
-	const last = rows.at(-1);
-	return last ? encodeReceivedAtSearchCursor(last) : null;
-}
-function collectNewAcceptedEmails(rows, seenIds) {
-	const fresh = [];
-	for (const row of rows) {
-		if (row.status !== "accepted" && row.status !== "completed") continue;
-		if (seenIds.has(row.id)) continue;
-		seenIds.add(row.id);
-		fresh.push(row);
-	}
-	return fresh;
-}
-async function fetchEmailSearchPage(params) {
-	const result = await searchEmails({
-		client: params.apiClient.client,
-		query: buildEmailSearchQuery({
-			cursor: params.cursor,
-			filters: params.filters,
-			pageSize: params.pageSize,
-			since: params.since
-		}),
-		responseStyle: "fields"
-	});
-	if (result.error) return {
-		ok: false,
-		error: result.error
-	};
-	const envelope = result.data;
-	const rows = envelope?.data ?? [];
-	return {
-		ok: true,
-		cursor: envelope?.meta.cursor ?? cursorFromRows(rows),
-		rows
-	};
-}
-function sleep$1(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-//#endregion
 //#region src/oclif/commands/emails-wait.ts
 const DEFAULT_WAIT_TIMEOUT_SECONDS$1 = 300;
 function cliError$4(message) {
@@ -12372,6 +12692,7 @@ var EmailsWaitCommand = class EmailsWaitCommand extends Command {
 			min: 1
 		}),
 		q: Flags.string({ description: "Full-text search DSL query" }),
+		"reply-to-sent-email-id": Flags.string({ description: "Filter to inbound emails that are threaded replies to a specific outbound send (UUID from a /v1/send-mail response). Combine with --to and --since for the strictest version of the wait-for-reply pattern." }),
 		since: Flags.string({ description: "Only match emails received on or after this date/time" }),
 		"spam-score-gte": Flags.integer({ description: "Only match emails with spam score greater than or equal to this value" }),
 		"spam-score-lt": Flags.integer({ description: "Only match emails with spam score below this value" }),
@@ -12416,7 +12737,7 @@ var EmailsWaitCommand = class EmailsWaitCommand extends Command {
 			if (!page.ok) {
 				const payload = extractErrorPayload(page.error);
 				writeErrorWithHints(payload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					auth,
 					baseUrlOverridden,
 					configDir: this.config.configDir,
@@ -12538,7 +12859,7 @@ var EmailsWatchCommand = class EmailsWatchCommand extends Command {
 			if (!page.ok) {
 				const payload = extractErrorPayload(page.error);
 				writeErrorWithHints(payload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					auth,
 					baseUrlOverridden,
 					configDir: this.config.configDir,
@@ -13260,7 +13581,7 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 					process.stderr.write(`Function ${outcome.created.name} (${outcome.created.id}) was created and secrets [${succeeded}] were written, but the final redeploy failed; the new bindings are NOT yet live. Re-run \`primitive functions redeploy --id ${outcome.created.id} --file <bundle>\` once the cause is fixed.\n`);
 				}
 				writeErrorWithHints(outcome.payload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					...authFailureContext,
 					payload: outcome.payload
 				});
@@ -13283,7 +13604,7 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 				});
 				if (waitResult.kind === "error") {
 					writeErrorWithHints(waitResult.payload);
-					removeStaleSavedCredentialOnUnauthorized({
+					surfaceUnauthorizedHint({
 						...authFailureContext,
 						payload: waitResult.payload
 					});
@@ -13316,8 +13637,8 @@ const PRIMITIVE_TEAM_AUTHOR = {
 	name: "Primitive Team",
 	url: "https://primitive.dev"
 };
-const SDK_VERSION_RANGE = "^0.30.2";
-const CLI_VERSION_RANGE = "^0.30.2";
+const SDK_VERSION_RANGE = "^0.31.0";
+const CLI_VERSION_RANGE = "^0.31.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY is auto-injected by the Primitive Functions runtime.
@@ -13827,7 +14148,7 @@ var FunctionsLogsCommand = class FunctionsLogsCommand extends Command {
 					if (result.error) {
 						const errorPayload = extractErrorPayload(result.error);
 						writeErrorWithHints(errorPayload);
-						removeStaleSavedCredentialOnUnauthorized({
+						surfaceUnauthorizedHint({
 							auth,
 							baseUrlOverridden,
 							configDir: this.config.configDir,
@@ -14083,7 +14404,7 @@ var FunctionsRedeployCommand = class FunctionsRedeployCommand extends Command {
 					process.stderr.write(`Secrets [${succeeded}] were written, but the redeploy step failed; the new bindings are NOT yet live. Re-run \`primitive functions redeploy --id ${flags.id} --file <bundle>\` once the cause is fixed.\n`);
 				}
 				writeErrorWithHints(outcome.payload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					...authFailureContext,
 					payload: outcome.payload
 				});
@@ -14105,7 +14426,7 @@ var FunctionsRedeployCommand = class FunctionsRedeployCommand extends Command {
 				});
 				if (waitResult.kind === "error") {
 					writeErrorWithHints(waitResult.payload);
-					removeStaleSavedCredentialOnUnauthorized({
+					surfaceUnauthorizedHint({
 						...authFailureContext,
 						payload: waitResult.payload
 					});
@@ -14306,7 +14627,7 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 				if (outcome.stage === "get-function") process.stderr.write("Secret was written, but reading current function code for redeploy failed; the secret is NOT yet live. Re-run with --redeploy, or call `primitive functions redeploy --id <id> --file <bundle>` once you have the bundle.\n");
 				else if (outcome.stage === "redeploy") process.stderr.write("Secret was written, but the redeploy step failed; the secret is NOT yet live. Inspect the function's deploy_error and re-run `primitive functions redeploy --id <id> --file <bundle>` once the cause is fixed.\n");
 				writeErrorWithHints(outcome.payload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					...authFailureContext,
 					payload: outcome.payload
 				});
@@ -14494,7 +14815,7 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 			if (triggerResult.error) {
 				const payload = extractErrorPayload(triggerResult.error);
 				writeErrorWithHints(payload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					auth,
 					baseUrlOverridden,
 					configDir: this.config.configDir,
@@ -14532,7 +14853,7 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 				if (!page.ok) {
 					const payload = extractErrorPayload(page.error);
 					writeErrorWithHints(payload);
-					removeStaleSavedCredentialOnUnauthorized({
+					surfaceUnauthorizedHint({
 						auth,
 						baseUrlOverridden,
 						configDir: this.config.configDir,
@@ -14560,7 +14881,7 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 				if (result.error) {
 					const payload = extractErrorPayload(result.error);
 					writeErrorWithHints(payload);
-					removeStaleSavedCredentialOnUnauthorized({
+					surfaceUnauthorizedHint({
 						auth,
 						baseUrlOverridden,
 						configDir: this.config.configDir,
@@ -14640,22 +14961,17 @@ async function checkExistingLogin(params) {
 	})))(apiClient);
 	if (!result.error) return { status: "valid" };
 	const payload = extractErrorPayload(result.error);
-	if (removeStaleSavedCredentialOnUnauthorized({
-		auth: {
-			apiKey: params.credentials.api_key,
-			apiBaseUrl1: probeApiBaseUrl1,
-			apiBaseUrl2: normalizeApiBaseUrl2(void 0),
-			credentials: params.credentials,
-			source: "stored"
-		},
-		baseUrlOverridden: requestConfig.baseUrlOverridden,
-		configDir: params.configDir,
-		payload
-	})) return { status: "removed_stale" };
+	const code = extractErrorCode(payload);
+	const baseUrlDiffersFromSaved = requestConfig.baseUrlOverridden && requestConfig.apiBaseUrl1 !== params.credentials.api_base_url_1;
+	if (code === API_ERROR_CODES.unauthorized && !baseUrlDiffersFromSaved) {
+		deleteCliCredentials(params.configDir);
+		process.stderr.write("Removed saved Primitive CLI credentials because the existing key was rejected during login. Continuing with a fresh login.\n");
+		return { status: "removed_stale" };
+	}
 	return {
 		status: "blocked",
 		payload,
-		message: extractErrorCode(payload) === API_ERROR_CODES.unauthorized ? "Saved Primitive CLI credentials were rejected. Run `primitive logout` to remove them before logging in again." : "A saved Primitive CLI login exists, but the CLI could not verify whether it is still valid. Run `primitive logout` before logging in again."
+		message: code === API_ERROR_CODES.unauthorized ? "Saved Primitive CLI credentials were rejected by an API URL different from the one they were saved with. Run `primitive logout` to remove them, or switch back to the original environment before logging in again." : "A saved Primitive CLI login exists, but the CLI could not verify whether it is still valid. Run `primitive logout` before logging in again."
 	};
 }
 var LoginCommand = class LoginCommand extends Command {
@@ -15040,7 +15356,7 @@ var ReplyCommand = class ReplyCommand extends Command {
 			if (result.error) {
 				const errorPayload = extractErrorPayload(result.error);
 				writeErrorWithHints(errorPayload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					auth,
 					baseUrlOverridden,
 					configDir: this.config.configDir,
@@ -15059,39 +15375,6 @@ var ReplyCommand = class ReplyCommand extends Command {
 };
 //#endregion
 //#region src/oclif/commands/send.ts
-const SUBJECT_MAX_LENGTH = 200;
-function deriveSubject(body) {
-	for (const line of body.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		return trimmed.length > SUBJECT_MAX_LENGTH ? `${trimmed.slice(0, SUBJECT_MAX_LENGTH - 3)}...` : trimmed;
-	}
-	return "Message";
-}
-function isVerifiedDomain(domain) {
-	return domain.is_active === true;
-}
-async function pickDefaultFromAddress(apiClient, authFailureContext) {
-	const result = await listDomains({
-		client: apiClient.client,
-		responseStyle: "fields"
-	});
-	if (result.error) {
-		const errorPayload = extractErrorPayload(result.error);
-		if (extractErrorCode(errorPayload) === API_ERROR_CODES.unauthorized) {
-			writeErrorWithHints(errorPayload);
-			removeStaleSavedCredentialOnUnauthorized({
-				...authFailureContext,
-				payload: errorPayload
-			});
-			throw new Errors.CLIError("Cannot send: API key is missing or invalid (see hint above).", { exit: 1 });
-		}
-		throw new Errors.CLIError(`Could not look up your verified domains to default --from. Pass --from explicitly. Underlying error: ${formatErrorPayload(errorPayload)}`);
-	}
-	const first = result.data?.data?.find(isVerifiedDomain);
-	if (!first) throw new Errors.CLIError("No active verified outbound domain found on this account; pass --from explicitly. To set up outbound, claim a domain via `primitive domains add` and verify it.");
-	return `agent@${first.domain}`;
-}
 var SendCommand = class SendCommand extends Command {
 	static description = `Send an outbound email. Agent-grade shortcut for \`sending send\` with sensible defaults.
 
@@ -15183,7 +15466,7 @@ var SendCommand = class SendCommand extends Command {
 			if (result.error) {
 				const errorPayload = extractErrorPayload(result.error);
 				writeErrorWithHints(errorPayload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					...authFailureContext,
 					payload: errorPayload
 				});
@@ -15628,7 +15911,7 @@ var WhoamiCommand = class WhoamiCommand extends Command {
 			if (result.error) {
 				const errorPayload = extractErrorPayload(result.error);
 				writeErrorWithHints(errorPayload);
-				removeStaleSavedCredentialOnUnauthorized({
+				surfaceUnauthorizedHint({
 					auth,
 					baseUrlOverridden,
 					configDir: this.config.configDir,
@@ -15851,7 +16134,7 @@ const generatedCommands = Object.fromEntries(operationManifest.filter((operation
 const COMMANDS = {
 	completion: CompletionCommand,
 	"list-operations": ListOperationsCommand,
-	config: ConfigListCommand,
+	config: ConfigCommand,
 	"config:list": ConfigListCommand,
 	"config:reset": ConfigResetCommand,
 	"config:set": ConfigSetCommand,
@@ -15859,6 +16142,7 @@ const COMMANDS = {
 	describe: DescribeCommand,
 	send: SendCommand,
 	reply: ReplyCommand,
+	chat: ChatCommand,
 	login: LoginCommand,
 	signup: SignupCommand,
 	logout: LogoutCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -27,6 +27,10 @@
       "cli": {
         "description": "CLI authentication"
       },
+      "config": {
+        "description": "Manage local Primitive CLI request environments",
+        "hidden": true
+      },
       "account": {
         "description": "Manage your account settings, storage, and webhook secret"
       },