@agentcomms/whatsapp 0.12.1 → 0.12.2

package/dist/cli.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { $ as renderPrune, A as CommsError, B as colorEnabled, C as checkStorePath, F as approvalsOf, G as installExitStatus, H as escapeForDisplay, I as approveChangeAtTerminal, J as nameAvailable, K as isCommsError, L as canPrompt, M as absoluteSearchPath, N as agentMarker, O as CHANNELS, P as approvalKind, Q as renderInstall, R as channelManifest, S as storeIdentity, T as expandSource, U as exemptFromUpdateGate, V as commandPathOf, W as gatedChangeAtTerminal, X as openCore, Y as nameShapeProblem, Z as paint, _ as chatRefOf, a as listChats, at as updateGateAtTerminal, b as requireAccount, c as Presenter, ct as withFileLock, d as draftMessage, et as runCommand, f as Visibility, g as requireSupportedNode, h as WhatsAppIndex, i as CHAT_KINDS, it as truncateDisplay, j as EXIT_CODES, k as CHANNEL_SERVERS, l as innerText, lt as writeResult, m as WhatsAppContext, n as whatsappStatus, nt as serverPruneChange, o as readChat, p as listKey, q as lookupName, r as probeStore, s as searchMessages, st as windowsSystemProgram, t as syncAccount, tt as serverInstallChange, ut as VERSION, v as PLATFORM, w as defaultStorePath, x as requireNamedConfig, y as newWhatsAppAccount, z as childEnvironment } from "./sync-BiO86eEl.mjs";
+import { $ as renderPrune, A as CommsError, B as colorEnabled, C as checkStorePath, F as approvalsOf, G as installExitStatus, H as escapeForDisplay, I as approveChangeAtTerminal, J as nameAvailable, K as isCommsError, L as canPrompt, M as absoluteSearchPath, N as agentMarker, O as CHANNELS, P as approvalKind, Q as renderInstall, R as channelManifest, S as storeIdentity, T as expandSource, U as exemptFromUpdateGate, V as commandPathOf, W as gatedChangeAtTerminal, X as openCore, Y as nameShapeProblem, Z as paint, _ as chatRefOf, a as listChats, at as updateGateAtTerminal, b as requireAccount, c as Presenter, ct as withFileLock, d as draftMessage, et as runCommand, f as Visibility, g as requireSupportedNode, h as WhatsAppIndex, i as CHAT_KINDS, it as truncateDisplay, j as EXIT_CODES, k as CHANNEL_SERVERS, l as innerText, lt as writeResult, m as WhatsAppContext, n as whatsappStatus, nt as serverPruneChange, o as readChat, p as listKey, q as lookupName, r as probeStore, s as searchMessages, st as windowsSystemProgram, t as syncAccount, tt as serverInstallChange, ut as VERSION, v as PLATFORM, w as defaultStorePath, x as requireNamedConfig, y as newWhatsAppAccount, z as childEnvironment } from "./sync-C2_cXhZ0.mjs";
 import { rm } from "node:fs/promises";
 import path, { delimiter, join } from "node:path";
 import fs, { accessSync, constants as constants$1 } from "node:fs";
-import childProcess, { spawn } from "node:child_process";
 import { stripVTControlCharacters } from "node:util";
+import childProcess, { spawn } from "node:child_process";
 import process$1 from "node:process";
 import { EventEmitter } from "node:events";
 //#region ../../node_modules/.pnpm/commander@15.0.0/node_modules/commander/lib/error.js
@@ -3534,7 +3534,7 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 		ran = true;
 		exitCode = await runCommand(output(), async () => {
 			requireSupportedNode();
-			const { startWhatsAppStdioServer } = await import("./stdio-entry-BznXKJaK.mjs");
+			const { startWhatsAppStdioServer } = await import("./stdio-entry-irMynM6w.mjs");
 			await startWhatsAppStdioServer({
 				env,
 				...flags.account ? { account: String(flags.account) } : {}

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { u as composeDraft, ut as VERSION } from "./sync-BiO86eEl.mjs";
-import { t as createWhatsAppMcpServer } from "./server-BHwKQeXq.mjs";
+import { u as composeDraft, ut as VERSION } from "./sync-C2_cXhZ0.mjs";
+import { t as createWhatsAppMcpServer } from "./server-ag_r78jB.mjs";
 //#region src/index.ts
 /**
 * The library entry of `@agentcomms/whatsapp`.

package/dist/{server-BHwKQeXq.mjs → server-ag_r78jB.mjs}

@@ -1,4 +1,4 @@
-import { D as strictToolArguments, E as UNTRUSTED_NOTICE, a as listChats, d as draftMessage, i as CHAT_KINDS, m as WhatsAppContext, n as whatsappStatus, o as readChat, ot as updateToolGate, rt as toCommsError, s as searchMessages, t as syncAccount, ut as VERSION } from "./sync-BiO86eEl.mjs";
+import { D as strictToolArguments, E as UNTRUSTED_NOTICE, a as listChats, d as draftMessage, i as CHAT_KINDS, m as WhatsAppContext, n as whatsappStatus, o as readChat, ot as updateToolGate, rt as toCommsError, s as searchMessages, t as syncAccount, ut as VERSION } from "./sync-C2_cXhZ0.mjs";
 import { c as boolean, h as number, x as string } from "./schemas-DiGKNDNq.mjs";
 import { t as McpServer } from "./mcp-DXXb3Vv3-Co5BzjYe.mjs";
 //#region src/mcp/server.ts

package/dist/{stdio-entry-BznXKJaK.mjs → stdio-entry-irMynM6w.mjs}

@@ -1,4 +1,4 @@
-import { t as createWhatsAppMcpServer } from "./server-BHwKQeXq.mjs";
+import { t as createWhatsAppMcpServer } from "./server-ag_r78jB.mjs";
 //#region src/mcp/stdio-entry.ts
 /**
 * Starting the stdio server. On stdio, stdout is the protocol, so the console is redirected to stderr first — the

package/dist/{sync-BiO86eEl.mjs → sync-C2_cXhZ0.mjs}

@@ -6,14 +6,14 @@ import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { homedir, platform, userInfo } from "node:os";
 import { constants as constants$1 } from "node:fs";
-import { execFile, spawn } from "node:child_process";
 import { styleText } from "node:util";
+import { execFile, spawn } from "node:child_process";
 //#endregion
 //#region src/version.ts
 /** The package version, read from package.json at build time. */
-const VERSION$1 = "0.12.1";
+const VERSION$1 = "0.12.2";
 //#endregion
-//#region ../core/dist/update-check-Ba6REc8M.mjs
+//#region ../core/dist/update-check-B-WYPZae.mjs
 /**
 * Every failure a user or an agent can act on carries a specific, stable code from this registry, a message, an
 * optional one-line hint and structured `details`. The code decides the process exit status; agents and skills branch
@@ -392,9 +392,15 @@ async function takeOverStale(lockPath, staleMs) {
 async function withFileLock(lockPath, fn, options = {}) {
 	const timeoutMs = options.timeoutMs ?? 5e3;
 	const staleMs = options.staleMs ?? 3e4;
-	const deadline = Date.now() + timeoutMs;
+	const started = Date.now();
+	let deadline = started + timeoutMs;
+	/** `maxWaitMs`'s end: fixed when the wait begins, whatever the lock does. */
+	const limit = options.maxWaitMs === void 0 ? Number.POSITIVE_INFINITY : started + options.maxWaitMs;
 	const token = randomBytes(12).toString("hex");
 	let lastCode = "EEXIST";
+	/** The token of the holder this caller saw last, and how many times it has seen the lock change hands. */
+	let holder;
+	let handOvers = 0;
 	await ensurePrivateDir(dirname(lockPath));
 	for (;;) try {
 		const handle = await open(lockPath, "wx", 384);
@@ -409,10 +415,20 @@ async function withFileLock(lockPath, fn, options = {}) {
 		const code = error.code;
 		if (!CONTENDED.has(code ?? "")) throw error;
 		lastCode = code ?? lastCode;
-		if (code === "EEXIST" && await isStale(lockPath, await readLock(lockPath), staleMs)) {
-			await takeOverStale(lockPath, staleMs);
-			continue;
+		if (code === "EEXIST") {
+			const body = await readLock(lockPath);
+			if (await isStale(lockPath, body, staleMs)) {
+				await takeOverStale(lockPath, staleMs);
+				continue;
+			}
+			const seen = typeof body?.token === "string" ? body.token : void 0;
+			if (seen !== void 0 && seen !== holder) {
+				if (holder !== void 0) handOvers += 1;
+				holder = seen;
+				if (options.timeoutPerHolder) deadline = Date.now() + timeoutMs;
+			}
 		}
+		if (Date.now() > limit) throw new CommsError("LOCK_TIMEOUT", `gave up waiting for ${lockPath}: the wait hit its overall limit of ${(limit - started) / 1e3} s`, { hint: (handOvers > 0 ? `It changed hands ${handOvers} time(s) while this waited, never to this process: busy rather than stuck. Retry in a moment.` : "Retry in a moment. If it persists and no other process is running, delete the lock file.") + (lastCode === "EEXIST" ? "" : ` (last error: ${lastCode})`) });
 		if (Date.now() > deadline) throw new CommsError("LOCK_TIMEOUT", `another agent-communications process is holding ${lockPath}`, { hint: `Retry in a moment. If it persists and no other process is running, delete the lock file.` + (lastCode === "EEXIST" ? "" : ` (last error: ${lastCode})`) });
 		await setTimeout$1(25 + Math.floor(Math.random() * 50));
 	}
@@ -2135,6 +2151,32 @@ function refusalFor(record) {
 	const kind = approvalKind(record);
 	return kind === "change" ? refuseChange : kind === "download" ? refuseDownload : refuse;
 }
+/**
+* A claim whose caller was cancelled before it changed anything (`ClaimOptions.signal`).
+*
+* `USAGE` and `cancelled:`, the words every cancellation in this repository is reported in, with `details.reason`
+* saying so for a caller that branches on it — and in the record's own kind: a question is not an approval, and
+* nothing is sent by answering one. The record is as it was, and the hint says so.
+*/
+function cancelledClaim(record) {
+	const kind = approvalKind(record);
+	if (kind === "download") return new CommsError("USAGE", "cancelled: nothing was saved", {
+		hint: "The question was not used: the same call, made again with the same answer, can still use it until it expires.",
+		details: {
+			choiceId: record.approvalId,
+			state: record.state,
+			reason: "cancelled"
+		}
+	});
+	return new CommsError("USAGE", `cancelled: ${kind === "change" ? "nothing was changed" : "nothing was sent"}`, {
+		hint: "The approval was not used: the same call, made again, can still use it until it expires.",
+		details: {
+			approvalId: record.approvalId,
+			state: record.state,
+			reason: "cancelled"
+		}
+	});
+}
 var ApprovalStore = class {
 	directory;
 	#now;
@@ -2338,6 +2380,7 @@ var ApprovalStore = class {
 		const result = await this.#transition(approvalId, (current) => {
 			this.#requireKind(current, "send");
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (code, reason) => {
 				failure = {
 					code,
@@ -2448,6 +2491,7 @@ var ApprovalStore = class {
 		const result = await this.#transition(approvalId, (current) => {
 			this.#requireKind(current, "change");
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (reason) => {
 				failure = {
 					code: "APPROVAL_VOID",
@@ -2575,6 +2619,9 @@ var ApprovalStore = class {
 	* gave it in the conversation. Under `confirm`, only a question the person answered at a terminal or in a trusted
 	* form can be claimed; a pending one is refused, and left as it is, so they can still answer it. One used, voided or
 	* expired is refused as an approval in that state is.
+	*
+	* `options.signal` is the download's cancellation, asked under the lock as a send's is (`ClaimOptions.signal`): a
+	* download cancelled while this waited saves nothing and leaves the question open, the answer still unused.
 	*/
 	async claimForDownload(approvalId, live, options = {}) {
 		const digest = downloadDigest(live);
@@ -2582,6 +2629,7 @@ var ApprovalStore = class {
 		const result = await this.#transition(approvalId, (current) => {
 			this.#requireKind(current, "download");
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (reason) => {
 				failure = {
 					code: "APPROVAL_VOID",
@@ -2850,6 +2898,219 @@ function nameAvailable(config, kind, name, platform) {
 	}
 	return { ok: true };
 }
+function okEnvelope(data) {
+	return {
+		ok: true,
+		schemaVersion: 1,
+		data
+	};
+}
+function errorEnvelope(error) {
+	const body = {
+		code: error.code,
+		message: error.message
+	};
+	if (error.hint !== void 0) body.hint = error.hint;
+	if (error.details !== void 0) body.details = error.details;
+	return {
+		ok: false,
+		schemaVersion: 1,
+		error: body
+	};
+}
+const defaultStreams = {
+	stdout: process.stdout,
+	stderr: process.stderr,
+	stdin: process.stdin
+};
+function colorEnabled(env, stream, flag) {
+	if (flag === false) return false;
+	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+	if (env.TERM === "dumb") return false;
+	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "0") return true;
+	return Boolean(stream.isTTY);
+}
+/** True when a human could answer a prompt: both ends are terminals, no --json/--no-input, not CI. */
+function canPrompt(env, streams, options) {
+	if (options.json || options.noInput) return false;
+	if (env.CI && env.CI !== "0" && env.CI !== "false") return false;
+	return Boolean(streams.stdin?.isTTY && streams.stdout.isTTY);
+}
+/** Environment variables well-known coding agents set. Used only as a speed bump, never as a security boundary. */
+const AGENT_MARKERS = [
+	"CLAUDECODE",
+	"CLAUDE_CODE_ENTRYPOINT",
+	"CODEX_SANDBOX",
+	"CODEX_HOME",
+	"CURSOR_AGENT",
+	"GEMINI_CLI",
+	"AGENT_COMMS_AGENT"
+];
+function agentMarker(env) {
+	for (const name of AGENT_MARKERS) if (env[name] !== void 0 && env[name] !== "") return name;
+	return null;
+}
+function paint(color, format, text) {
+	return color ? styleText(format, text, { validateStream: false }) : text;
+}
+/**
+* A command line for a person to copy and run, each word quoted only where the shell it is pasted into would need it.
+* Every command this package prints to be run — a change to run again with its approval, a folder to take out, an
+* entry to register again or remove — is quoted here, so no printer quotes for a shell of its own.
+*
+* Everywhere but Windows that shell is a POSIX one, and a word goes in single quotes, inside which nothing is special
+* but the quote itself. Windows has two shells, and neither reads single quotes that way: cmd.exe does not take them
+* as quotes at all, so `'C:\Profiles\First Last\outgoing'` reached the command as two words, quote marks and all, and
+* PowerShell does, but escapes a quote inside them by doubling it rather than as `'\''`. A command printed on Windows
+* has to be safe in both, because nothing says which one it will be pasted into (CUE-306) — and safe is not enough:
+* the program has to receive the same words from either. Three readers stand between the line and the program. cmd.exe
+* hands the program the line as it is, and the program's own parser (the C runtime's, Node's) splits it. PowerShell
+* reads the line itself, a double-quoted word with its backslashes as plain characters, and then writes a new command
+* line for the program: Windows PowerShell 5.1 the old way ("Legacy" in about_Parsing, "Passing arguments to native
+* applications") — a word quoted only when it holds whitespace, as it is, and an empty word dropped — and PowerShell
+* 7.3 and later its own way ("Standard") — quoted when it must be, with every backslash before a quote doubled. For a
+* `.cmd` script, which is how npm installs `agentcomms`, `claude` and `codex` on Windows, PowerShell 7 goes back to the
+* old way, and cmd.exe then reads that new line. So on Windows:
+*
+* - A word of letters, digits and `_ + = : . / \`, with `@` and `-` anywhere but first, is left as it is: no reader
+*   does anything with it, and a backslash is an ordinary character to all of them, at the end too. A first `@` is
+*   splatting to PowerShell, and a `,` its array operator — two words — so a word with either is quoted. So is a word
+*   that starts with a digit, which PowerShell may read as a number (`1kb`, `0x10`), and one that starts with `-` but
+*   is not a plain option, which PowerShell may read as a parameter of its own and split (`-name.x`).
+* - A word that double quotes bring through all three readers whole goes in double quotes. Inside them cmd.exe reads
+*   `& | < > ^ ( )` and spaces as ordinary characters, and PowerShell reads everything as ordinary but `$`, the
+*   backtick and a double quote. What is left special in one or the other is kept out: a double quote, which ends the
+*   quoting in both — and PowerShell takes the curly ones, `“ ” „`, for one too; `$` and the backtick, PowerShell's
+*   expansion and escape; `%`, which cmd.exe expands as `%NAME%` before it looks at quotes at all; `!`, which it
+*   expands as `!NAME!` inside quotes too wherever delayed expansion is on, and which then makes a `^` inside quotes an
+*   escape; and any control or formatting character — a line break ends the command in cmd.exe even inside quotes, a
+*   tab pasted into cmd.exe can complete a file name, and a right-to-left override shows a line other than the one
+*   that runs. Three more cannot come through: an empty word, which Windows PowerShell drops; a word ending in a
+*   backslash, which the C runtime reads with the closing quote as `\"` — and doubled for it, PowerShell 7 passes both
+*   backslashes on where cmd.exe and Windows PowerShell pass one; and a word with `& | < > ^ ( )` but no whitespace,
+*   which PowerShell passes to a `.cmd` script unquoted, for cmd.exe to run `&whoami` from or to split at `|`.
+* - With any other word in it, no line is printed at all (`line` is null), and the printers show the command's words
+*   as JSON instead, saying it has to be typed. Not a line with the word left out: a placeholder in its place was
+*   still a command that ran — `claude mcp remove NAME` removed whatever entry was called `NAME`, and an install
+*   hint's `--force` replaced it — and before that, a word quoted for PowerShell's single quotes, which cmd.exe reads
+*   as characters, ran `whoami` from a server named `$x&whoami&`. See `commandAsJson` for why the JSON runs nothing.
+*
+* Everywhere else there is always a line: single quotes make any word safe.
+*/
+function shellCommand(words, platform = process.platform) {
+	if (platform !== "win32") return {
+		words,
+		line: words.map(posixShellWord).join(" "),
+		platform
+	};
+	const printed = words.map(windowsShellWord);
+	return {
+		words,
+		line: printed.includes(null) ? null : printed.join(" "),
+		platform
+	};
+}
+/** The same command with more words at its end — the approval it is to be run again with — for the same shell. */
+function withWords(command, ...more) {
+	return shellCommand([...command.words, ...more], command.platform);
+}
+function posixShellWord(word) {
+	return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* The word as cmd.exe, Windows PowerShell and PowerShell 7 all hand it to a program, or null when no printing of it
+* does (see `shellCommand`). Bare: a plain option, or ordinary characters that do not start like a number.
+*/
+function windowsShellWord(word) {
+	if (/^(?:--?[A-Za-z][A-Za-z0-9-]*|(?!\+?\.?\d)[\w+=:./\\][\w@+=:./\\-]*)$/.test(word)) return word;
+	if (word === "" || word.endsWith("\\")) return null;
+	if (/["$`%!\u201C-\u201E]|[\p{C}\p{Zl}\p{Zp}]/u.test(word)) return null;
+	if (/[&|<>^()]/.test(word) && !/\s/.test(word)) return null;
+	return `"${word}"`;
+}
+/**
+* The words of a command as a JSON array, for a command that cannot be printed as a line: something to read, and to
+* parse, and nothing to run.
+*
+* Pasted into either Windows shell by mistake, it runs nothing. PowerShell refuses it before running anything: a `[`
+* opens a type name, and a quoted string is none. cmd.exe looks for a program called `["agentcomms"` or the like, and
+* finds none — and nothing in the line is anything else to it: every character it acts on, inside quotes or out (`%`,
+* `!`), is written as a `\u` escape, and so is every double quote inside a word, so the quotes cmd.exe sees are the
+* JSON's own, in pairs, and `&`, `|`, `<`, `>`, `^` and the parentheses are only ever inside them, where it reads them
+* as characters. `$` and the backtick are escaped too, so that PowerShell would expand nothing even if it read on, and
+* so is everything outside printable ASCII — a line break, a curly quote, a right-to-left override. A backslash is
+* doubled, as JSON has it.
+*/
+function commandAsJson(words) {
+	const word = (text) => {
+		let json = "";
+		for (let index = 0; index < text.length; index++) {
+			const code = text.charCodeAt(index);
+			const char = text[index];
+			if (char === "\\") json += "\\\\";
+			else if (code >= 32 && code <= 126 && !"\"%!$`".includes(char)) json += char;
+			else json += `\\u${code.toString(16).padStart(4, "0")}`;
+		}
+		return `"${json}"`;
+	};
+	return `[${words.map(word).join(",")}]`;
+}
+/** What is said beside a command shown as JSON. */
+const TO_TYPE = "the command's words, written as JSON: one of them cannot be quoted the same way for cmd.exe and for PowerShell, so type the command yourself, with that word quoted for the shell you use";
+/** A command in backticks, for a sentence — as its words in JSON, saying it has to be typed, when it has no line. */
+function inlineCommand(command) {
+	return command.line === null ? `\`${commandAsJson(command.words)}\` (${TO_TYPE})` : `\`${command.line}\``;
+}
+/** A command as text of its own — a list's line, a field's value — or its words in JSON, saying it has to be typed. */
+function commandText(command) {
+	return command.line === null ? `${commandAsJson(command.words)} (${TO_TYPE})` : command.line;
+}
+/** Writes a successful result: the envelope with --json, otherwise the human rendering. */
+function writeResult(data, options, human, streams = defaultStreams) {
+	if (options.json) {
+		streams.stdout.write(`${JSON.stringify(okEnvelope(data))}\n`);
+		return;
+	}
+	const text = human(data);
+	if (text) streams.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+/** Writes an error and returns the exit code to use. */
+function writeError(error, options, streams = defaultStreams) {
+	const commsError = toCommsError(error);
+	if (options.json) streams.stdout.write(`${JSON.stringify(errorEnvelope(commsError))}\n`);
+	else {
+		streams.stderr.write(`${paint(options.color, "red", "error")}: ${commsError.message}\n`);
+		if (commsError.hint) streams.stderr.write(`${paint(options.color, "dim", "hint")}: ${commsError.hint}\n`);
+	}
+	return commsError.exitCode;
+}
+/** Runs a command body and exits with the documented code. Unexpected errors keep only their message. */
+async function runCommand(options, body, streams = defaultStreams) {
+	try {
+		await body();
+		return EXIT_CODES.OK;
+	} catch (error) {
+		return writeError(error, options, streams);
+	}
+}
+/**
+* The first two steps of `requirePerson` — an agent is refused, then anything without a terminal — for a command
+* whose code is not its own to make up.
+*
+* `agentcomms approve` asks for a code the approval store issued and will check, so it cannot use `askChallenge`;
+* but it refuses in exactly the same order and words, because it is the same gate.
+*/
+function refuseUnlessPerson(env, streams, gate) {
+	const marker = agentMarker(env);
+	if (marker) throw new CommsError("LOOSENING_REFUSED", gate.refusedToAgent, {
+		hint: `Ask the user to run \`${gate.command}\` in their own terminal.`,
+		details: { marker }
+	});
+	const prompting = {};
+	if (gate.json !== void 0) prompting.json = gate.json;
+	if (gate.noInput !== void 0) prompting.noInput = gate.noInput;
+	if (!canPrompt(env, streams, prompting)) throw new CommsError("LOOSENING_REFUSED", gate.refusedWithoutTerminal, { hint: `Run \`${gate.command}\` directly in a terminal.` });
+}
 /**
 * Enough of TOML to read codex's `config.toml`, and a refusal for anything else.
 *
@@ -3923,13 +4184,13 @@ function snippetFor(client, name, entry) {
 * Project-scoped entries are not looked at: every write here targets user scope, so they are not what would be
 * replaced.
 */
-function claimName(product, options, name, existing) {
+function claimName(product, options, name, existing, platform) {
 	const taken = existing.filter((server) => server.client === options.client && server.name === name && server.scope !== "project");
 	const foreign = taken.find((server) => !isProductServer(server, product));
 	if (foreign) {
 		const what = foreign.packageName ?? (foreign.url ? displayUrl(foreign.url) : void 0) ?? (foreign.command || "something else");
 		const other = name === product.binary ? `${product.binary}-${product.defaultServerName}` : product.binary;
-		throw new CommsError("CONFIG", `${options.client} already has an MCP server called "${name}", and it is not this one (it runs ${what})`, { hint: `Register this one under another name: \`${installCommand$1(product, options, other)}\`. --force does not replace a server this did not install.` });
+		throw new CommsError("CONFIG", `${options.client} already has an MCP server called "${name}", and it is not this one (it runs ${what})`, { hint: `Register this one under another name: ${inlineCommand(installCommand$1(product, options, other, [], platform))}. --force does not replace a server this did not install.` });
 	}
 	if (taken.length > 0 && !options.force) {
 		for (const pin of PIN_OPTIONS) {
@@ -3937,14 +4198,14 @@ function claimName(product, options, name, existing) {
 			const served = taken.map((server) => product.narrowingOf(server.args)[pin]).find(Boolean);
 			if (!wanted || !served || served === wanted) continue;
 			const second = `${product.defaultServerName}-${wanted.split("/")[0]}`;
-			throw new CommsError("CONFIG", `${options.client} already has this server registered as "${name}"`, { hint: `That entry serves ${served}; to serve ${wanted} as well, register a second entry under its own name: \`${installCommand$1(product, options, second === name ? `${name}-2` : second)}\`.` });
+			throw new CommsError("CONFIG", `${options.client} already has this server registered as "${name}"`, { hint: `That entry serves ${served}; to serve ${wanted} as well, register a second entry under its own name: ${inlineCommand(installCommand$1(product, options, second === name ? `${name}-2` : second, [], platform))}.` });
 		}
 		const npx = taken.some((server) => server.args.some((argument) => argument.startsWith(`${product.npxPackage}@`)));
 		const again = {
 			...keepNarrowing(product, options, taken).options,
 			launcher: options.launcher ?? (npx ? "npx" : void 0)
 		};
-		throw new CommsError("CONFIG", `${options.client} already has this server registered as "${name}"`, { hint: `Pass --force to replace it — that is how an upgrade reaches a client: \`${installCommand$1(product, again, name, ["--force"])}\`.` });
+		throw new CommsError("CONFIG", `${options.client} already has this server registered as "${name}"`, { hint: `Pass --force to replace it — that is how an upgrade reaches a client: ${inlineCommand(installCommand$1(product, again, name, ["--force"], platform))}.` });
 	}
 	return taken;
 }
@@ -3987,8 +4248,11 @@ function keepNarrowing(product, options, previous) {
 * workspace on the machine; for Gmail it dropped `--inbox` and `--read-only` the same way. Doctor's repair already
 * rebuilds these flags for exactly that reason. The product's `serverArgs` are the install command's own flags for
 * the pin and the narrowing, so they are repeated as they are.
+*
+* A pin kept from the entry being replaced was read from the client's file, which may hold anything, so on Windows the
+* command can come back with no line to paste; every hint gives it with `inlineCommand`, which shows it as words then.
 */
-function installCommand$1(product, options, name, extra = []) {
+function installCommand$1(product, options, name, extra, platform) {
 	const words = [
 		product.binary,
 		"mcp",
@@ -4000,7 +4264,7 @@ function installCommand$1(product, options, name, extra = []) {
 	words.push(...product.serverArgs(options));
 	if (options.launcher && options.launcher !== "managed") words.push("--launcher", options.launcher);
 	words.push(...extra);
-	return words.map((word) => /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`).join(" ");
+	return shellCommand(words, platform);
 }
 /**
 * A command's exit status and what it printed, kept here and never shown: codex prints an entry's env. Started as
@@ -4043,8 +4307,13 @@ function capture$1(env, command, args) {
 * or a failure that is not "no such server", stops the install: not knowing is not the same as nothing there.
 * Nothing codex prints is repeated, because its answer carries the entry's env.
 */
-async function codexRegistration(env, binary, name, path) {
-	const unknown = () => new CommsError("CONFIG", `codex would not say what it has registered as "${name}", so nothing was written`, { hint: `Look with \`codex mcp get ${name}\`. If it is not an older copy of this server, choose another --name; \`--print\` shows the entry to add by hand.` });
+async function codexRegistration(env, binary, name, path, platform) {
+	const unknown = () => new CommsError("CONFIG", `codex would not say what it has registered as "${name}", so nothing was written`, { hint: `Look with ${inlineCommand(shellCommand([
+		"codex",
+		"mcp",
+		"get",
+		name
+	], platform))}. If it is not an older copy of this server, choose another --name; \`--print\` shows the entry to add by hand.` });
 	let answer;
 	try {
 		answer = await capture$1(env, binary, [
@@ -4147,10 +4416,10 @@ async function preflightInstall(context, product, options) {
 		const blind = scan.unreadable.find((file) => file.path === own);
 		if (blind) throw new CommsError("CONFIG", `${blind.path} could not be read (${blind.reason}), so what is already registered there cannot be checked; nothing was written`, { hint: "Fix the file, or add the entry by hand: `--print` shows it without writing anything." });
 	}
-	let previous = writes ? claimName(product, options, name, existing) : [];
+	let previous = writes ? claimName(product, options, name, existing, context.platform) : [];
 	if (writes && binary && options.client === "codex") {
-		const reported = await codexRegistration(context.env, binary, name, configPath ?? "codex");
-		if (reported) previous = claimName(product, options, name, [reported]);
+		const reported = await codexRegistration(context.env, binary, name, configPath ?? "codex", context.platform);
+		if (reported) previous = claimName(product, options, name, [reported], context.platform);
 	}
 	const { options: effective, kept } = keepNarrowing(product, options, previous);
 	const node = await resolveNode(context.env);
@@ -4277,7 +4546,19 @@ async function mcpInstall(context, product, options, planned) {
 	const { cliName, binary, own, configPath, writes } = target;
 	const warnings = (product.warnAbout?.(existing.filter((server) => server.client === options.client)) ?? []).filter(Boolean);
 	if (kept.length > 0) {
-		const removal = options.client === "claude-code" ? `\`claude mcp remove ${name} --scope user\`` : options.client === "codex" ? `\`codex mcp remove ${name}\`` : `delete "${name}" from ${configPath}`;
+		const removal = options.client === "claude-code" ? inlineCommand(shellCommand([
+			"claude",
+			"mcp",
+			"remove",
+			name,
+			"--scope",
+			"user"
+		], context.platform)) : options.client === "codex" ? inlineCommand(shellCommand([
+			"codex",
+			"mcp",
+			"remove",
+			name
+		], context.platform)) : `delete "${name}" from ${configPath}`;
 		warnings.push(`Kept ${kept.join(" ")} from the "${name}" entry this replaced, because this install did not say otherwise. To register it wider on purpose, remove that entry first (${removal}), then install without them.`);
 	}
 	if (!writes) {
@@ -4372,7 +4653,7 @@ async function mcpInstall(context, product, options, planned) {
 					restored = false;
 				}
 				throw new CommsError("CONFIG", restored ? `could not register "${name}"; the previous entry was put back` : `could not register "${name}", and the previous entry could not be put back either — ${cliName} now has no server called "${name}"`, {
-					hint: restored ? "Check the client is not running, then try again." : `Re-register it with \`${installCommand$1(product, effective, name)}\`. The old entry is in ${backupPath}.`,
+					hint: restored ? "Check the client is not running, then try again." : `Re-register it with ${inlineCommand(installCommand$1(product, effective, name, [], context.platform))}. The old entry is in ${backupPath}.`,
 					cause: error
 				});
 			}
@@ -4381,7 +4662,17 @@ async function mcpInstall(context, product, options, planned) {
 		} catch (error) {
 			const message = error instanceof CommsError ? error.message : String(error);
 			if (/already exists/i.test(message)) throw new CommsError("CONFIG", `${cliName} already has an MCP server called "${name}", somewhere this could not read`, {
-				hint: `Look at it with \`${cliName} mcp get ${name}\`. If it is an older ${product.binary}, remove it with \`${cliName} mcp remove ${name}\` and run this again; if not, choose another --name.`,
+				hint: `Look at it with ${inlineCommand(shellCommand([
+					cliName,
+					"mcp",
+					"get",
+					name
+				], context.platform))}. If it is an older ${product.binary}, remove it with ${inlineCommand(shellCommand([
+					cliName,
+					"mcp",
+					"remove",
+					name
+				], context.platform))} and run this again; if not, choose another --name.`,
 				cause: error
 			});
 			throw error;
@@ -4717,19 +5008,32 @@ function rivalPatterns(packages) {
 function escapeRegExp(text) {
 	return text.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 }
-function gmailRemoval({ client, name: server, path, scope }) {
+/**
+* The command that removes a registered server, in its client's own terms — the name as the client's file has it,
+* which may be anything, so on Windows it can have no line to paste, and is shown as its words, to be typed
+* (`shellCommand`). Never as a line with the name left out: that removed whatever entry had the stand-in's name.
+*/
+function removalCommand(client, name, platform) {
+	return commandText(shellCommand([
+		client,
+		"mcp",
+		"remove",
+		name
+	], platform));
+}
+function gmailRemoval({ client, name: server, path, scope }, platform) {
 	if (scope === "project") return `remove "${server}" from the project entry in ${path} by hand`;
 	switch (client) {
-		case "claude-code": return `claude mcp remove ${server}`;
-		case "codex": return `codex mcp remove ${server}`;
+		case "claude-code": return removalCommand("claude", server, platform);
+		case "codex": return removalCommand("codex", server, platform);
 		default: return `remove the "${server}" entry from ${path}, then restart ${client}`;
 	}
 }
 /**
 * Registered servers that are one of `packages` — another server for the same service whose send tools no approval
-* step gates — each with why it matters and how to remove it.
+* step gates — each with why it matters and how to remove it. `platform` is the shell the removal is quoted for.
 */
-function findRivalPackageServers(servers, packages) {
+function findRivalPackageServers(servers, packages, platform = process.platform) {
 	const patterns = rivalPatterns(packages);
 	const findings = [];
 	for (const server of servers) {
@@ -4740,7 +5044,7 @@ function findRivalPackageServers(servers, packages) {
 			...server,
 			packageName: known.name,
 			reason: `${known.name} exposes send tools that no approval step gates`,
-			removal: gmailRemoval(server)
+			removal: gmailRemoval(server, platform)
 		});
 	}
 	return findings;
@@ -4866,107 +5170,6 @@ function requireChannelManifest(channel) {
 	if (manifest === void 0) throw notAChannel(channel);
 	return manifest;
 }
-function okEnvelope(data) {
-	return {
-		ok: true,
-		schemaVersion: 1,
-		data
-	};
-}
-function errorEnvelope(error) {
-	const body = {
-		code: error.code,
-		message: error.message
-	};
-	if (error.hint !== void 0) body.hint = error.hint;
-	if (error.details !== void 0) body.details = error.details;
-	return {
-		ok: false,
-		schemaVersion: 1,
-		error: body
-	};
-}
-const defaultStreams = {
-	stdout: process.stdout,
-	stderr: process.stderr,
-	stdin: process.stdin
-};
-function colorEnabled(env, stream, flag) {
-	if (flag === false) return false;
-	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
-	if (env.TERM === "dumb") return false;
-	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "0") return true;
-	return Boolean(stream.isTTY);
-}
-/** True when a human could answer a prompt: both ends are terminals, no --json/--no-input, not CI. */
-function canPrompt(env, streams, options) {
-	if (options.json || options.noInput) return false;
-	if (env.CI && env.CI !== "0" && env.CI !== "false") return false;
-	return Boolean(streams.stdin?.isTTY && streams.stdout.isTTY);
-}
-/** Environment variables well-known coding agents set. Used only as a speed bump, never as a security boundary. */
-const AGENT_MARKERS = [
-	"CLAUDECODE",
-	"CLAUDE_CODE_ENTRYPOINT",
-	"CODEX_SANDBOX",
-	"CODEX_HOME",
-	"CURSOR_AGENT",
-	"GEMINI_CLI",
-	"AGENT_COMMS_AGENT"
-];
-function agentMarker(env) {
-	for (const name of AGENT_MARKERS) if (env[name] !== void 0 && env[name] !== "") return name;
-	return null;
-}
-function paint(color, format, text) {
-	return color ? styleText(format, text, { validateStream: false }) : text;
-}
-/** Writes a successful result: the envelope with --json, otherwise the human rendering. */
-function writeResult(data, options, human, streams = defaultStreams) {
-	if (options.json) {
-		streams.stdout.write(`${JSON.stringify(okEnvelope(data))}\n`);
-		return;
-	}
-	const text = human(data);
-	if (text) streams.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
-}
-/** Writes an error and returns the exit code to use. */
-function writeError(error, options, streams = defaultStreams) {
-	const commsError = toCommsError(error);
-	if (options.json) streams.stdout.write(`${JSON.stringify(errorEnvelope(commsError))}\n`);
-	else {
-		streams.stderr.write(`${paint(options.color, "red", "error")}: ${commsError.message}\n`);
-		if (commsError.hint) streams.stderr.write(`${paint(options.color, "dim", "hint")}: ${commsError.hint}\n`);
-	}
-	return commsError.exitCode;
-}
-/** Runs a command body and exits with the documented code. Unexpected errors keep only their message. */
-async function runCommand(options, body, streams = defaultStreams) {
-	try {
-		await body();
-		return EXIT_CODES.OK;
-	} catch (error) {
-		return writeError(error, options, streams);
-	}
-}
-/**
-* The first two steps of `requirePerson` — an agent is refused, then anything without a terminal — for a command
-* whose code is not its own to make up.
-*
-* `agentcomms approve` asks for a code the approval store issued and will check, so it cannot use `askChallenge`;
-* but it refuses in exactly the same order and words, because it is the same gate.
-*/
-function refuseUnlessPerson(env, streams, gate) {
-	const marker = agentMarker(env);
-	if (marker) throw new CommsError("LOOSENING_REFUSED", gate.refusedToAgent, {
-		hint: `Ask the user to run \`${gate.command}\` in their own terminal.`,
-		details: { marker }
-	});
-	const prompting = {};
-	if (gate.json !== void 0) prompting.json = gate.json;
-	if (gate.noInput !== void 0) prompting.noInput = gate.noInput;
-	if (!canPrompt(env, streams, prompting)) throw new CommsError("LOOSENING_REFUSED", gate.refusedWithoutTerminal, { hint: `Run \`${gate.command}\` directly in a terminal.` });
-}
 /**
 * One renderer for every surface a send preview is shown on — the chat, an elicitation form, a terminal. Text the
 * draft's author controls (body, subject, display names, file names, link text) must not be able to change how the
@@ -5420,21 +5623,25 @@ function renderChangePreview(record) {
 * it on the second call, with its id.
 *
 * A change that loosens no setting and does nothing irreversible is applied directly: asking a person to agree to
-* something that needs no agreement teaches them to agree without reading. It refuses an approval id, as a report
-* refuses one (`refuseApprovalWithoutChange`), rather than applying and dropping it: the update check's stop lets a
-* call claiming an approval through (design 2026-09-28 §2), and one that is then never claimed would carry any
-* approval the store holds — one an agent had just had prepared for "not now", say — past the stop, to a tightening
-* or a cancellation made where the call itself was stopped.
+* something that needs no agreement teaches them to agree without reading. It refuses an approval id — in the change's
+* own words when it has them (`refuseApproval`) — as a report refuses one (`refuseApprovalWithoutChange`), rather than
+* applying and dropping it: the update check's stop lets a call claiming an approval through (design 2026-09-28 §2),
+* and one that is then never claimed would carry any approval the store holds — one an agent had just had prepared for
+* "not now", say — past the stop, to a tightening or a cancellation made where the call itself was stopped.
 */
 async function gatedChange(core, change, options) {
 	const request = await change.plan(await core.config.load());
 	const loosens = classifyChange(request.before, request.after).loosened.length > 0;
 	const acts = (request.effects ?? []).length > 0;
 	if (!loosens && !acts) {
-		if (options.approvalId) throw new CommsError("USAGE", "nothing was changed: as things stand this change needs no approval, so it takes none", {
-			hint: "Make the same call again without the approval: it applies at once and asks nobody. An approval is spent only on the change it was prepared for.",
-			details: { approvalId: options.approvalId }
-		});
+		if (options.approvalId) {
+			const refusal = await change.refuseApproval?.(options.approvalId);
+			if (refusal !== void 0) throw refusal;
+			throw new CommsError("USAGE", "nothing was changed: as things stand this change needs no approval, so it takes none", {
+				hint: "Make the same call again without the approval: it applies at once and asks nobody. An approval is spent only on the change it was prepared for.",
+				details: { approvalId: options.approvalId }
+			});
+		}
 		return {
 			status: "applied",
 			result: await change.apply(void 0, request)
@@ -5476,8 +5683,10 @@ async function gatedChangeAtTerminal(core, change, options) {
 	const { prepared } = first;
 	if (!(agentMarker(options.env) === null && canPrompt(options.env, streams, { json: options.output.json === true }))) {
 		if (options.output.json !== true) streams.stdout.write(`${prepared.preview}\n\n`);
+		const carrying = [options.approvalFlag ?? "--approval", prepared.approvalId];
+		const { command } = options;
 		throw new CommsError("APPROVAL_PENDING", `this change needs approval first: ${prepared.summary}`, {
-			hint: approvalHint(prepared, `${options.command} ${options.approvalFlag ?? "--approval"} ${prepared.approvalId}`, approveCommand),
+			hint: approvalHint(prepared, typeof command === "string" ? `${command} ${carrying.join(" ")}` : withWords(command, ...carrying), approveCommand),
 			details: {
 				approvalId: prepared.approvalId,
 				policy: prepared.policy,
@@ -5511,7 +5720,8 @@ async function gatedChangeAtTerminal(core, change, options) {
 * its registration step and says why in its report — so the two say it in the same words.
 */
 function approvalHint(prepared, rerun, approveCommand) {
-	return prepared.policy === "confirm" ? `Show the person the preview. They run \`${approveCommandOf({ approveCommand })} ${prepared.approvalId}\`; then run \`${rerun}\`.` : `Show the person the preview. Once they say yes, run \`${rerun}\`.`;
+	const run = typeof rerun === "string" ? `\`${rerun}\`` : inlineCommand(rerun);
+	return prepared.policy === "confirm" ? `Show the person the preview. They run \`${approveCommandOf({ approveCommand })} ${prepared.approvalId}\`; then run ${run}.` : `Show the person the preview. Once they say yes, run ${run}.`;
 }
 /**
 * Approves a configuration change at a terminal, the way a person approves a send: read the preview, type the code.
@@ -6048,7 +6258,7 @@ function isPrerelease(version) {
 	return VERSION_PATTERN.exec(version)?.[4] !== void 0;
 }
 /** The package version, read from package.json at build time. */
-const VERSION = "0.12.1";
+const VERSION = "0.12.2";
 /**
 * Registering, pruning and listing the MCP servers of every channel, from the core.
 *
@@ -6306,7 +6516,7 @@ function serverPruneChange(core, env, request, own) {
 	};
 	const { packageName, version } = ownProduct(request.channel, own) ?? {
 		packageName: channelServer(request.channel).packageName,
-		version: "0.12.1"
+		version: "0.12.2"
 	};
 	const product = {
 		packageName,
@@ -6930,7 +7140,7 @@ async function askLine(streams, question) {
 }
 channelServer("core").packageName;
 //#endregion
-//#region ../core/dist/tool-arguments-CohGlMUZ.mjs
+//#region ../core/dist/tool-arguments-BMmJnuY4.mjs
 const APPLIED = Symbol.for("agentcomms.strictToolArguments");
 const TARGET = "draft-2020-12";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcomms/whatsapp",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "WhatsApp for coding agents, read-only: list, read and search the chats WhatsApp for Mac keeps on this Mac, and draft replies as links the person sends. No network client; it never sends.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "commander": "^15.0.0",
     "zod": "^4.6.5",
-    "@agentcomms/core": "0.12.1"
+    "@agentcomms/core": "0.12.2"
   },
   "agentcomms": {
     "contract": 1,
@@ -87,5 +87,5 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test --test-timeout=600000 \"test/**/*.test.ts\""
   },
-  "gitHead": "62c13e382939518b8464df3e0f582d07b3bea4cd"
+  "gitHead": "224763228ecc63ce403f0d12988865cfaa981f2a"
 }