@primitivedotdev/cli 0.31.5 → 0.31.7

package/dist/oclif/index.js

@@ -13379,7 +13379,7 @@ function surfaceUnauthorizedHint(params) {
 	}
 	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) {
+function formatElapsed$1(ms) {
 	const seconds = ms / 1e3;
 	if (seconds < 60) return `${seconds.toFixed(2)}s`;
 	const minutes = Math.floor(seconds / 60);
@@ -13391,7 +13391,7 @@ async function runWithTiming(enabled, fn) {
 	try {
 		return await fn();
 	} finally {
-		process.stderr.write(`[time: ${formatElapsed(Date.now() - start)}]\n`);
+		process.stderr.write(`[time: ${formatElapsed$1(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.";
@@ -13755,6 +13755,364 @@ async function readStdinToString() {
 	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
 	return Buffer.concat(chunks).toString("utf8");
 }
+var ChatProgressIndicator = class {
+	currentMessage = null;
+	frameIndex = 0;
+	lastLineLength = 0;
+	startedAt;
+	timer = null;
+	constructor(stream = process.stderr, now = Date.now) {
+		this.stream = stream;
+		this.now = now;
+		this.startedAt = this.now();
+	}
+	start(message) {
+		this.stopTimer();
+		this.currentMessage = message;
+		if (this.stream.isTTY) {
+			this.render(message);
+			this.timer = setInterval(() => this.render(message), 120);
+			this.timer.unref?.();
+			return;
+		}
+		this.stream.write(`${message}\n`);
+	}
+	update(message, options = {}) {
+		this.currentMessage = message;
+		if (this.stream.isTTY) {
+			this.stopTimer();
+			this.clearLine();
+			this.render(message);
+			this.timer = setInterval(() => this.render(message), 120);
+			this.timer.unref?.();
+			return;
+		}
+		this.stopTimer();
+		this.stream.write(`${message}\n`);
+		if (options.heartbeatMs !== void 0) {
+			this.timer = setInterval(() => {
+				this.stream.write(`${formatWaitingHeartbeat(message, this.now() - this.startedAt, options.timeoutSeconds)}\n`);
+			}, options.heartbeatMs);
+			this.timer.unref?.();
+		}
+	}
+	notice(message) {
+		if (this.stream.isTTY) {
+			const currentMessage = this.currentMessage;
+			this.clearLine();
+			this.stream.write(`${message}\n`);
+			if (currentMessage !== null && this.timer !== null) this.render(currentMessage);
+			return;
+		}
+		this.stream.write(`${message}\n`);
+	}
+	succeed(message) {
+		this.finish(`${message} after ${formatElapsed(this.now() - this.startedAt)}.`);
+	}
+	fail(message) {
+		this.finish(message);
+	}
+	finish(message) {
+		this.stopTimer();
+		this.currentMessage = null;
+		if (this.stream.isTTY) this.clearLine();
+		this.stream.write(`${message}\n`);
+	}
+	render(message) {
+		const frames = [
+			"-",
+			"\\",
+			"|",
+			"/"
+		];
+		const frame = frames[this.frameIndex % frames.length];
+		this.frameIndex += 1;
+		const line = `${frame} ${message} (${formatElapsed(this.now() - this.startedAt)})`;
+		this.lastLineLength = Math.max(this.lastLineLength, line.length);
+		this.stream.write(`\r${line}`);
+	}
+	clearLine() {
+		if (this.lastLineLength > 0) {
+			this.stream.write(`\r${" ".repeat(this.lastLineLength)}\r`);
+			this.lastLineLength = 0;
+		}
+	}
+	stopTimer() {
+		if (this.timer !== null) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+};
+function formatElapsed(ms) {
+	const seconds = Math.max(0, Math.round(ms / 1e3));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	const remainder = seconds % 60;
+	return remainder === 0 ? `${minutes}m` : `${minutes}m ${remainder}s`;
+}
+function formatWaitingHeartbeat(message, elapsedMs, timeoutSeconds) {
+	const timeout = timeoutSeconds === void 0 ? "" : timeoutSeconds === 0 ? ", no timeout" : `, timeout ${formatElapsed(timeoutSeconds * 1e3)}`;
+	return `${message} (${formatElapsed(elapsedMs)} elapsed${timeout})`;
+}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function commandFromArgv(argv) {
+	return argv.map(shellQuote).join(" ");
+}
+function resolveChatResponseBody(reply) {
+	if (reply.body_text && reply.body_text.length > 0) return {
+		body: reply.body_text,
+		format: "text"
+	};
+	if (reply.body_html && reply.body_html.length > 0) return {
+		body: reply.body_html,
+		format: "html"
+	};
+	if (reply.body_text !== null && reply.body_text !== void 0) return {
+		body: reply.body_text,
+		format: "text"
+	};
+	if (reply.body_html !== null && reply.body_html !== void 0) return {
+		body: reply.body_html,
+		format: "html"
+	};
+	return {
+		body: "",
+		format: "empty"
+	};
+}
+function matchDescription(strategy) {
+	return strategy === "strict" ? "strict, matched by reply_to_sent_email_id" : "fallback, matched by sender/time window";
+}
+function normalizeEmailAddress(value) {
+	return value.trim().toLowerCase();
+}
+function derivedReplySubject(parent) {
+	const subject = parent.subject?.trim();
+	if (!subject) return "Re: (no subject)";
+	return /^re:/i.test(subject) ? subject : `Re: ${subject}`;
+}
+function assertParentMatchesRecipient(parent, recipient) {
+	if (normalizeEmailAddress(parent.from_email) === normalizeEmailAddress(recipient)) return;
+	throw cliError$6(`Inbound email ${parent.id} is from ${parent.from_email}, not ${recipient}. Use \`primitive chat ${parent.from_email} --reply <message> --reply-to-email-id ${parent.id}\` or omit --reply-to-email-id to continue the latest inbound from ${recipient}.`);
+}
+function emailDetailFromEnvelope(envelope) {
+	return envelope?.data ?? envelope ?? null;
+}
+function buildCommand(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
+	};
+}
+function buildChatFollowUpCommands(context) {
+	const commands = [];
+	const continueParts = [
+		"primitive",
+		"chat",
+		context.recipient,
+		"--reply",
+		"<message>",
+		"--from",
+		context.from,
+		"--reply-to-email-id",
+		context.reply.id,
+		"--timeout",
+		String(context.timeoutSeconds)
+	];
+	if (context.json) continueParts.push("--json");
+	if (context.quiet) continueParts.push("--quiet");
+	if (context.strictOnly) continueParts.push("--strict-only");
+	else if (context.strictPhaseSeconds !== DEFAULT_STRICT_PHASE_SECONDS) continueParts.push("--strict-phase-seconds", String(context.strictPhaseSeconds));
+	commands.push(buildCommand("continue_chat", "Continue this chat", continueParts, { requiresMessage: true }));
+	commands.push(buildCommand("reply_direct", "Reply directly to the inbound email", [
+		"primitive",
+		"reply",
+		"--id",
+		context.reply.id,
+		"--from",
+		context.from,
+		"--body",
+		"<message>"
+	], { requiresMessage: true }));
+	commands.push(buildCommand("inspect_reply", "Inspect the full inbound email", [
+		"primitive",
+		"emails",
+		"get",
+		"--id",
+		context.reply.id
+	]));
+	commands.push(buildCommand("wait_for_more", "Wait for future replies to this send", [
+		"primitive",
+		"emails",
+		"wait",
+		"--reply-to-sent-email-id",
+		context.sent.id,
+		"--to",
+		context.from,
+		"--since",
+		context.reply.received_at,
+		"--timeout",
+		String(context.timeoutSeconds)
+	]));
+	return commands;
+}
+function buildChatRecoveryCommands(context) {
+	return [
+		buildCommand("wait_threaded_reply", "Wait for the threaded reply again", [
+			"primitive",
+			"emails",
+			"wait",
+			"--reply-to-sent-email-id",
+			context.sent.id,
+			"--to",
+			context.from,
+			"--since",
+			context.sentAtIso,
+			"--timeout",
+			String(context.timeoutSeconds)
+		]),
+		buildCommand("wait_fallback_reply", "Fallback wait by sender/time window", [
+			"primitive",
+			"emails",
+			"wait",
+			"--from",
+			context.recipient,
+			"--to",
+			context.from,
+			"--since",
+			context.sentAtIso,
+			"--timeout",
+			String(context.timeoutSeconds)
+		]),
+		buildCommand("inspect_sent_email", "Inspect the outbound send", [
+			"primitive",
+			"sent",
+			"get",
+			"--id",
+			context.sent.id
+		])
+	];
+}
+function buildChatJsonEnvelope(context) {
+	const responseBody = resolveChatResponseBody(context.reply);
+	return {
+		sent: context.sent,
+		reply: context.reply,
+		response_body: responseBody.body,
+		response_body_format: responseBody.format,
+		match: {
+			description: matchDescription(context.matchStrategy),
+			reply_to_sent_email_id: context.reply.reply_to_sent_email_id ?? null,
+			strategy: context.matchStrategy
+		},
+		follow_up_commands: buildChatFollowUpCommands(context)
+	};
+}
+function formatChatResponse(context) {
+	const accepted = context.sent.accepted.join(", ") || context.recipient;
+	const responseBody = resolveChatResponseBody(context.reply);
+	const lines = [
+		"Reply received",
+		"",
+		"Sent",
+		`  To: ${accepted}`,
+		`  From: ${context.sent.from || context.from}`,
+		`  Subject: ${context.subject}`,
+		`  Sent email id: ${context.sent.id}`,
+		`  Delivery status: ${context.sent.delivery_status ?? context.sent.status}`,
+		"",
+		"Reply",
+		`  Email id: ${context.reply.id}`,
+		`  From: ${context.reply.from_email}`,
+		`  To: ${context.reply.to_email}`,
+		`  Subject: ${context.reply.subject ?? "(no subject)"}`,
+		`  Received: ${context.reply.received_at}`,
+		`  Match: ${matchDescription(context.matchStrategy)}`
+	];
+	if (context.reply.reply_to_sent_email_id) lines.push(`  Reply to sent email id: ${context.reply.reply_to_sent_email_id}`);
+	if (context.reply.message_id) lines.push(`  Message-Id: ${context.reply.message_id}`);
+	lines.push("", "Helpful follow-up commands", "  Replace <message> before running commands that include it.", "  Commands are templates; use --json for parse-safe output.");
+	for (const { description, command } of buildChatFollowUpCommands(context)) lines.push(`  ${description}:`, `    ${command}`);
+	lines.push("", `Response body (${responseBody.format}; use --json for parsing)`, "----- BEGIN RESPONSE -----", responseBody.body || "(empty response)", "----- END RESPONSE -----");
+	return lines.join("\n");
+}
+function formatChatRecoveryContext(context) {
+	const lines = [
+		"",
+		"Sent message context",
+		`  To: ${context.sent.accepted.join(", ") || context.recipient}`,
+		`  From: ${context.sent.from || context.from}`,
+		`  Subject: ${context.subject}`,
+		`  Sent email id: ${context.sent.id}`,
+		`  Delivery status: ${context.sent.delivery_status ?? context.sent.status}`,
+		`  Poll since: ${context.sentAtIso}`,
+		"",
+		"Helpful recovery commands"
+	];
+	for (const { description, command } of buildChatRecoveryCommands(context)) lines.push(`  ${description}:`, `    ${command}`);
+	return lines.join("\n");
+}
+async function loadInboundEmailDetail(params) {
+	const result = await getEmail({
+		client: params.apiClient.client,
+		path: { id: params.id },
+		responseStyle: "fields"
+	});
+	if (result.error) {
+		const payload = extractErrorPayload(result.error);
+		writeErrorWithHints(payload);
+		surfaceUnauthorizedHint({
+			...params.authFailureContext,
+			payload
+		});
+		throw new Errors.CLIError(`Could not load inbound email ${params.id}.`, { exit: 1 });
+	}
+	const detail = emailDetailFromEnvelope(result.data);
+	if (!detail) throw new Errors.CLIError(`Could not load inbound email ${params.id}: the API returned no email body.`, { exit: 1 });
+	return detail;
+}
+async function findLatestInboundFromRecipient(params) {
+	const result = await searchEmails({
+		client: params.apiClient.client,
+		query: {
+			from: params.recipient,
+			to: params.from,
+			include_facets: "false",
+			limit: params.pageSize,
+			snippet: "false",
+			sort: "received_at_desc"
+		},
+		responseStyle: "fields"
+	});
+	if (result.error) {
+		const payload = extractErrorPayload(result.error);
+		writeErrorWithHints(payload);
+		surfaceUnauthorizedHint({
+			...params.authFailureContext,
+			payload
+		});
+		throw new Errors.CLIError("Could not find a prior chat reply.", { exit: 1 });
+	}
+	const row = (result.data?.data ?? []).find((email) => email.status === "accepted" || email.status === "completed");
+	if (!row) return null;
+	return loadInboundEmailDetail({
+		apiClient: params.apiClient,
+		authFailureContext: params.authFailureContext,
+		id: row.id
+	});
+}
 var ChatCommand = class ChatCommand extends Command {
 	static description = `Send a message to an address and wait for the reply.
 
@@ -13763,17 +14121,37 @@ var ChatCommand = class ChatCommand extends Command {
   \`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.
+  piped via stdin. The default output confirms the reply was received,
+  prints exchange metadata, shows the response body, and lists helpful
+  follow-up commands as templates. The default transcript is for humans;
+  agents and scripts should pass --json for parse-safe output.
+
+  To continue an existing chat, pass --reply '<message>'. By default,
+  the CLI replies to the latest inbound email from the recipient to
+  your sender address. For exact continuation, pass
+  --reply-to-email-id <inbound-email-id>. Reply mode uses Primitive's
+  reply endpoint, so the reply subject and threading headers are
+  derived from the inbound email instead of copied into CLI flags.
+
+  --json emits a structured envelope with both sides of the exchange,
+  a direct response_body field, match details, and follow-up command
+  metadata such as kind, argv, placeholders, and requires_message.
 
-  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.`;
+  Matching the reply: chat first waits in strict threading mode by
+  filtering inbound mail with reply_to_sent_email_id=<sent id>. If
+  no strict match arrives before the strict phase ends, and
+  --strict-only is not set, it falls back to a weaker sender/time
+  window match: from=<recipient>, to=<sender>, and since=<send time>.
+  The fallback can catch clients that strip threading headers, but it
+  is less exact than strict matching. Progress is written to stderr
+  while the CLI waits. Exits non-zero on timeout and prints recovery
+  commands when the send succeeded but no reply was returned.`;
 	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 --reply 'one more thing'",
+		"<%= config.bin %> chat help@agent.acme.dev --reply 'one more thing' --reply-to-email-id <inbound-email-id>",
 		"<%= config.bin %> chat help@agent.acme.dev 'follow up question' --json",
 		"<%= config.bin %> chat help@agent.acme.dev 'one more thing' --timeout 300"
 	];
@@ -13801,8 +14179,11 @@ var ChatCommand = class ChatCommand extends Command {
 		}),
 		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." }),
+		reply: Flags.string({ description: "Reply body. Continues the latest inbound email from the recipient to your sender address; pass --reply-to-email-id for an exact thread." }),
+		"reply-to-email-id": Flags.string({ description: "Inbound email id to continue exactly. Uses Primitive's reply endpoint, so recipient, subject, and threading headers are derived from the inbound email." }),
+		"in-reply-to": Flags.string({ description: "Raw Message-Id of the parent email to thread a new send against. Prefer --reply-to-email-id with --reply when continuing an inbound email stored by Primitive." }),
+		json: Flags.boolean({ description: "Emit a structured JSON envelope { sent, reply, response_body, response_body_format, match, follow_up_commands } on stdout instead of the human-readable transcript." }),
+		quiet: Flags.boolean({ description: "Suppress stderr progress updates while sending and waiting. Errors and recovery commands are still written to stderr." }),
 		timeout: Flags.integer({
 			default: DEFAULT_CHAT_TIMEOUT_SECONDS,
 			description: "Seconds to wait for a reply before exiting non-zero; 0 waits forever.",
@@ -13830,8 +14211,12 @@ var ChatCommand = class ChatCommand extends Command {
 	};
 	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$6("Message body is empty.");
+		const replyMode = flags.reply !== void 0 || flags["reply-to-email-id"] !== void 0;
+		if (flags.reply !== void 0 && args.message !== void 0 && args.message !== "") throw cliError$6("Pass the reply body either as --reply or as the positional message, not both.");
+		if (replyMode && flags.subject !== void 0) throw cliError$6("--subject is not used with --reply. Primitive derives the reply subject from the inbound email.");
+		if (replyMode && flags["in-reply-to"] !== void 0) throw cliError$6("Use --reply-to-email-id with --reply instead of raw --in-reply-to.");
+		const message = flags.reply !== void 0 ? flags.reply : args.message !== void 0 && args.message !== "" ? args.message : await readStdinToString();
+		if (!message.trim()) throw cliError$6(replyMode ? "Reply body is empty." : "Message body is empty.");
 		await runWithTiming(flags.time, async () => {
 			const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
 				apiKey: flags["api-key"],
@@ -13844,10 +14229,71 @@ var ChatCommand = class ChatCommand extends Command {
 				baseUrlOverridden,
 				configDir: this.config.configDir
 			};
-			const from = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
-			const subject = flags.subject ?? deriveSubject(message);
+			const progress = flags.quiet ? null : new ChatProgressIndicator(process.stderr);
+			let from;
+			let parentReply;
+			let subject;
+			if (replyMode) {
+				const replyContext = await (async () => {
+					let replyContextFailureMessage = "Could not load reply context.";
+					try {
+						if (flags["reply-to-email-id"] !== void 0) {
+							progress?.start(`Loading reply context for ${flags["reply-to-email-id"]}`);
+							const exactParentReply = await loadInboundEmailDetail({
+								apiClient,
+								authFailureContext,
+								id: flags["reply-to-email-id"]
+							});
+							replyContextFailureMessage = `Inbound email ${flags["reply-to-email-id"]} does not match recipient ${args.recipient}.`;
+							assertParentMatchesRecipient(exactParentReply, args.recipient);
+							return {
+								from: flags.from ?? exactParentReply.to_email,
+								parentReply: exactParentReply
+							};
+						}
+						const replyFrom = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
+						progress?.start(`Finding latest inbound email from ${args.recipient}`);
+						const latestParentReply = await findLatestInboundFromRecipient({
+							apiClient,
+							authFailureContext,
+							from: replyFrom,
+							pageSize: flags["page-size"],
+							recipient: args.recipient
+						});
+						if (!latestParentReply) {
+							replyContextFailureMessage = "No prior inbound email found.";
+							throw cliError$6(`No prior inbound email from ${args.recipient} to ${replyFrom}. Start a new chat with \`primitive chat ${args.recipient} <message>\`, pass --from, or pass --reply-to-email-id <inbound-email-id>.`);
+						}
+						replyContextFailureMessage = `Inbound email ${latestParentReply.id} does not match recipient ${args.recipient}.`;
+						assertParentMatchesRecipient(latestParentReply, args.recipient);
+						return {
+							from: replyFrom,
+							parentReply: latestParentReply
+						};
+					} catch (error) {
+						progress?.fail(replyContextFailureMessage);
+						throw error;
+					}
+				})();
+				from = replyContext.from;
+				parentReply = replyContext.parentReply;
+				subject = derivedReplySubject(replyContext.parentReply);
+			} else {
+				from = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
+				subject = flags.subject ?? deriveSubject(message);
+			}
 			const sentAtIso = (/* @__PURE__ */ new Date()).toISOString();
-			const sendResult = await sendEmail({
+			if (replyMode) progress?.update(`Sending reply to ${args.recipient}`);
+			else progress?.start(`Sending message to ${args.recipient}`);
+			const sendResult = parentReply !== void 0 ? await replyToEmail({
+				body: {
+					body_text: message,
+					from
+				},
+				client: apiClient.client,
+				path: { id: parentReply.id },
+				responseStyle: "fields"
+			}) : await sendEmail({
 				body: {
 					from,
 					to: args.recipient,
@@ -13859,6 +14305,7 @@ var ChatCommand = class ChatCommand extends Command {
 				responseStyle: "fields"
 			});
 			if (sendResult.error) {
+				progress?.fail(replyMode ? "Reply send failed." : "Message send failed.");
 				const errorPayload = extractErrorPayload(sendResult.error);
 				writeErrorWithHints(errorPayload);
 				surfaceUnauthorizedHint({
@@ -13869,39 +14316,78 @@ var ChatCommand = class ChatCommand extends Command {
 				return;
 			}
 			const sent = sendResult.data?.data;
-			if (!sent) throw cliError$6("Send succeeded but the API returned no data.");
-			const reply = await waitForReply({
-				apiClient,
-				authFailureContext,
-				from,
-				interval: flags.interval,
-				pageSize: flags["page-size"],
+			if (!sent) {
+				progress?.fail("Send succeeded but the API returned no data.");
+				throw cliError$6("Send succeeded but the API returned no data.");
+			}
+			const replyAddress = sent.from || from;
+			progress?.update(`${replyMode ? "Reply" : "Message"} sent; waiting for reply from ${args.recipient}`, {
+				heartbeatMs: 15e3,
+				timeoutSeconds: flags.timeout
+			});
+			const baseContext = {
+				from: replyAddress,
+				json: flags.json,
+				parentReply,
+				quiet: flags.quiet,
 				recipient: args.recipient,
+				sent,
 				sentAtIso,
-				sentId: sent.id,
 				strictOnly: flags["strict-only"],
 				strictPhaseSeconds: flags["strict-phase-seconds"],
+				subject,
 				timeoutSeconds: flags.timeout
-			});
-			if (reply === null) {
-				process.stderr.write(`Timed out after ${flags.timeout}s waiting for a reply from ${args.recipient}.\n`);
+			};
+			let replyResult;
+			try {
+				replyResult = await waitForReply({
+					apiClient,
+					authFailureContext,
+					from: replyAddress,
+					interval: flags.interval,
+					notice: (message) => {
+						if (progress) {
+							progress.notice(message);
+							return;
+						}
+						process.stderr.write(`${message}\n`);
+					},
+					pageSize: flags["page-size"],
+					recipient: args.recipient,
+					sentAtIso,
+					sentId: sent.id,
+					strictOnly: flags["strict-only"],
+					strictPhaseSeconds: flags["strict-phase-seconds"],
+					timeoutSeconds: flags.timeout
+				});
+			} catch (error) {
+				progress?.fail("Reply polling failed.");
+				process.stderr.write(`${formatChatRecoveryContext(baseContext)}\n`);
+				throw error;
+			}
+			if (replyResult === null) {
+				const timeoutMessage = `Timed out after ${flags.timeout}s waiting for a reply from ${args.recipient}.`;
+				progress?.fail(timeoutMessage);
+				if (progress === null) process.stderr.write(`${timeoutMessage}\n`);
+				process.stderr.write(`${formatChatRecoveryContext(baseContext)}\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);
-			}
+			progress?.succeed(`Reply received from ${replyResult.reply.from_email}`);
+			const outputContext = {
+				...baseContext,
+				matchStrategy: replyResult.matchStrategy,
+				reply: replyResult.reply
+			};
+			if (flags.json) this.log(JSON.stringify(buildChatJsonEnvelope(outputContext), null, 2));
+			else this.log(formatChatResponse(outputContext));
 		});
 	}
 };
 async function waitForReply(params) {
+	const notice = params.notice ?? ((message) => {
+		process.stderr.write(`${message}\n`);
+	});
 	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);
@@ -13970,11 +14456,14 @@ async function waitForReply(params) {
 				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");
+					if (!strictFilterUnsupported) notice(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." : "Strict-phase reply matching is not supported by this Primitive API host; falling back to time-window matching.");
 					strictFilterUnsupported = true;
 					continue;
 				}
-				return detail;
+				return {
+					reply: detail,
+					matchStrategy: phase.label
+				};
 			}
 			if (strictFilterUnsupported && phase.label === "strict") break;
 			if (lastAccepted !== void 0) continue;
@@ -13996,6 +14485,33 @@ function redactConfig(config) {
 		environments: Object.fromEntries(Object.entries(config.environments).map(([name, environment]) => [name, redactCliEnvironment(environment)]))
 	};
 }
+function switchCliEnvironment(configDir, environmentName) {
+	const environment = normalizeCliEnvironmentName(environmentName);
+	const config = loadOrCreateConfig(configDir);
+	if (!config.environments[environment]) throw new Errors.CLIError(`Primitive CLI environment ${environment} is not configured.`, { exit: 1 });
+	const previousEnvironment = resolveConfigEnvironment(config)?.name ?? null;
+	const nextConfig = {
+		...config,
+		current_environment: environment
+	};
+	const shouldClearCredentials = previousEnvironment !== environment;
+	let removedCredentials = false;
+	if (shouldClearCredentials) {
+		const releaseLock = acquireCliCredentialsLock(configDir);
+		try {
+			saveCliConfig(configDir, nextConfig);
+			removedCredentials = existsSync(credentialsPath(configDir));
+			deleteCliCredentials(configDir);
+		} finally {
+			releaseLock();
+		}
+	} else saveCliConfig(configDir, nextConfig);
+	return {
+		environment,
+		previousEnvironment,
+		removedCredentials
+	};
+}
 var ConfigSetCommand = class ConfigSetCommand extends Command {
 	static summary = "Set a Primitive CLI request environment";
 	static flags = {
@@ -14032,20 +14548,16 @@ var ConfigSetCommand = class ConfigSetCommand extends Command {
 };
 var ConfigUseCommand = class ConfigUseCommand extends Command {
 	static summary = "Switch the active Primitive CLI request environment";
+	static description = "Switch the active Primitive CLI request environment. When this switches to a different environment, the CLI removes saved OAuth credentials so the next authenticated command signs in against the newly active API host.";
 	static args = { environment: Args.string({
 		description: "Environment name to use",
 		required: true
 	}) };
 	async run() {
 		const { args } = await this.parse(ConfigUseCommand);
-		const environment = normalizeCliEnvironmentName(args.environment);
-		const config = loadOrCreateConfig(this.config.configDir);
-		if (!config.environments[environment]) throw new Errors.CLIError(`Primitive CLI environment ${environment} is not configured.`, { exit: 1 });
-		saveCliConfig(this.config.configDir, {
-			...config,
-			current_environment: environment
-		});
+		const { environment, removedCredentials } = switchCliEnvironment(this.config.configDir, args.environment);
 		process.stderr.write(`Primitive CLI environment ${environment} is active.\n`);
+		if (removedCredentials) process.stderr.write("Removed saved Primitive CLI credentials. Run `primitive signin` to authenticate in the active environment.\n");
 	}
 };
 var ConfigListCommand = class ConfigListCommand extends Command {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.31.5",
+  "version": "0.31.7",
   "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,