@agentcomms/whatsapp 0.9.0 → 0.11.0

package/dist/cli.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { $ as serverInstallChange, A as CommsError, B as escapeForDisplay, C as checkStorePath, F as approveChangeAtTerminal, G as lookupName, H as gatedChangeAtTerminal, I as canPrompt, J as openCore, K as nameAvailable, L as channelManifest, M as agentMarker, N as approvalKind, O as CHANNELS, P as approvalsOf, Q as runCommand, R as colorEnabled, S as storeIdentity, T as expandSource, U as installExitStatus, V as exemptFromUpdateGate, W as isCommsError, X as renderInstall, Y as paint, Z as renderPrune, _ as chatRefOf, a as listChats, at as withFileLock, b as requireAccount, c as Presenter, d as draftMessage, et as serverPruneChange, f as Visibility, g as requireSupportedNode, h as WhatsAppIndex, i as CHAT_KINDS, j as EXIT_CODES, k as CHANNEL_SERVERS, l as innerText, m as WhatsAppContext, n as whatsappStatus, nt as truncateDisplay, o as readChat, ot as writeResult, p as listKey, q as nameShapeProblem, r as probeStore, rt as updateGateAtTerminal, s as searchMessages, st as VERSION, t as syncAccount, v as PLATFORM, w as defaultStorePath, x as requireNamedConfig, y as newWhatsAppAccount, z as commandPathOf } from "./sync-DU_KB2pO.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-CinH_TIY.mjs";
 import { rm } from "node:fs/promises";
-import path from "node:path";
+import path, { delimiter, join } from "node:path";
 import childProcess, { spawn } from "node:child_process";
 import { stripVTControlCharacters } from "node:util";
-import fs from "node:fs";
+import fs, { accessSync, constants as constants$1 } from "node:fs";
 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
@@ -3161,18 +3161,17 @@ function clearChats(context, request) {
 }
 //#endregion
 //#region src/cli/opener.ts
-function openLink(url, platform = process.platform) {
+function openLink(url, platform = process.platform, deps = {}) {
 	if (!/^(?:whatsapp:\/\/send\?|https:\/\/wa\.me\/)/.test(url)) return false;
-	const [command, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
-		"/c",
-		"start",
-		"",
-		url
-	]] : ["xdg-open", [url]];
+	const env = deps.env ?? process.env;
+	const command = linkOpener(platform, env);
+	if (command === null) return false;
+	const args = platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
 	try {
-		const child = spawn(command, args, {
+		const child = (deps.spawn ?? spawn)(command, args, {
 			stdio: "ignore",
-			detached: true
+			detached: true,
+			env: childEnvironment(env, platform)
 		});
 		child.on("error", () => void 0);
 		child.unref();
@@ -3181,6 +3180,19 @@ function openLink(url, platform = process.platform) {
 		return false;
 	}
 }
+/** The opener's full path, or null when there is none that can be named without looking in the current folder. */
+function linkOpener(platform, env) {
+	if (platform === "win32") return windowsSystemProgram("rundll32.exe", env);
+	if (platform === "darwin") return "/usr/bin/open";
+	for (const directory of absoluteSearchPath((env.PATH ?? "").split(delimiter), platform)) {
+		const candidate = join(directory, "xdg-open");
+		try {
+			accessSync(candidate, constants$1.X_OK);
+			return candidate;
+		} catch {}
+	}
+	return null;
+}
 //#endregion
 //#region src/cli/render.ts
 /**
@@ -3522,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-Blz5voaW.mjs");
+			const { startWhatsAppStdioServer } = await import("./stdio-entry-r40LJtFu.mjs");
 			await startWhatsAppStdioServer({
 				env,
 				...flags.account ? { account: String(flags.account) } : {}

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { st as VERSION, u as composeDraft } from "./sync-DU_KB2pO.mjs";
-import { t as createWhatsAppMcpServer } from "./server-3qn7im60.mjs";
+import { u as composeDraft, ut as VERSION } from "./sync-CinH_TIY.mjs";
+import { t as createWhatsAppMcpServer } from "./server-BLF6Xumr.mjs";
 //#region src/index.ts
 /**
 * The library entry of `@agentcomms/whatsapp`.

package/dist/{server-3qn7im60.mjs → server-BLF6Xumr.mjs}

@@ -1,4 +1,4 @@
-import { D as strictToolArguments, E as UNTRUSTED_NOTICE, a as listChats, d as draftMessage, i as CHAT_KINDS, it as updateToolGate, m as WhatsAppContext, n as whatsappStatus, o as readChat, s as searchMessages, st as VERSION, t as syncAccount, tt as toCommsError } from "./sync-DU_KB2pO.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-CinH_TIY.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-Blz5voaW.mjs → stdio-entry-r40LJtFu.mjs}

@@ -1,4 +1,4 @@
-import { t as createWhatsAppMcpServer } from "./server-3qn7im60.mjs";
+import { t as createWhatsAppMcpServer } from "./server-BLF6Xumr.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-DU_KB2pO.mjs → sync-CinH_TIY.mjs}

@@ -1,19 +1,19 @@
 import { C as unknown, b as strictObject, c as boolean, h as number, i as _enum, m as looseObject, p as literal, s as array, x as string, y as record } from "./schemas-DiGKNDNq.mjs";
 import { access, chmod, constants, link, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, utimes } from "node:fs/promises";
-import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import path, { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { domainToASCII, fileURLToPath, pathToFileURL } from "node:url";
 import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { homedir, platform } from "node:os";
+import { homedir, platform, userInfo } from "node:os";
 import { execFile, spawn } from "node:child_process";
 import { styleText } from "node:util";
 import { constants as constants$1 } from "node:fs";
 //#endregion
 //#region src/version.ts
 /** The package version, read from package.json at build time. */
-const VERSION$1 = "0.9.0";
+const VERSION$1 = "0.11.0";
 //#endregion
-//#region ../core/dist/update-gate-BwIKJmH7.mjs
+//#region ../core/dist/update-gate-BMcLWU3V.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
@@ -1033,7 +1033,7 @@ const APP_DIR_NAME = "agent-communications";
 function resolvePaths(options = {}) {
 	const env = options.env ?? process.env;
 	const platform = options.platform ?? process.platform;
-	const home = options.home ?? ((platform === "win32" ? env.USERPROFILE : env.HOME) || homedir());
+	const home = options.home ?? homeOf(env, platform);
 	const configDir = resolve(env.AGENT_COMMS_CONFIG_DIR || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, "agent-communications") : platform === "win32" ? join(env.APPDATA || join(home, "AppData", "Roaming"), "agent-communications") : join(home, ".config", "agent-communications")));
 	const explicitConfigDir = Boolean(env.AGENT_COMMS_CONFIG_DIR);
 	const localRoot = platform === "win32" && !explicitConfigDir ? join(env.LOCALAPPDATA || join(home, "AppData", "Local"), APP_DIR_NAME) : configDir;
@@ -1045,10 +1045,40 @@ function resolvePaths(options = {}) {
 		downloadsDir: resolve(join(home, "Downloads", APP_DIR_NAME))
 	};
 }
-/** Expands a leading `~` to the home directory. Nothing else is expanded. */
-function expandHome(path, home = homedir()) {
+/**
+* The home the environment names, which is where Node's own `homedir()` looks for the running process — `HOME`, or
+* `USERPROFILE` on Windows. Asking `homedir()` directly ignored an environment passed in, so every test that gave the
+* harness a temporary HOME still had its data and downloads resolved to the real ones: one day of test runs left 748
+* backups of fixture entries in the maintainer's own data directory.
+*
+* Its own function since a download asks where to save: the person's Downloads folder is `<this>/Downloads`, and a
+* folder they type as `~/…` is expanded from it — the same home every other path here is resolved from. When the
+* environment names none, the account's own home is taken ({@link accountHome}); `account` is for a test to say what
+* that is.
+*/
+function homeOf(env = process.env, platform = process.platform, account = accountHome) {
+	return (platform === "win32" ? env.USERPROFILE : env.HOME) || account();
+}
+/**
+* The home the account itself has, for when the environment names none: the password database's (`os.userInfo()`),
+* which no variable moves, rather than `homedir()`, which reads `HOME` first — from this process's environment, not the
+* one the caller passed, and so from somewhere the caller did not say. Only when there is no such entry — some
+* containers run as an id with none — is `homedir()` asked instead.
+*/
+function accountHome() {
+	try {
+		const home = userInfo().homedir;
+		if (home) return home;
+	} catch {}
+	return homedir();
+}
+/**
+* Expands a leading `~` to the home directory. Nothing else is expanded. `joinPaths` is the platform's own, for a path
+* judged for another platform than this one: a Linux home joined on Windows would otherwise take its backslashes.
+*/
+function expandHome(path, home = homedir(), joinPaths = join) {
 	if (path === "~") return home;
-	if (path.startsWith("~/") || path.startsWith("~\\")) return join(home, path.slice(2));
+	if (path.startsWith("~/") || path.startsWith("~\\")) return joinPaths(home, path.slice(2));
 	return path;
 }
 /**
@@ -1855,6 +1885,55 @@ function challengeMatches(answer, storedHash) {
 	const b = Buffer.from(storedHash, "hex");
 	return a.length === b.length && timingSafeEqual(a, b);
 }
+/**
+* The digest a download's question is bound to: the account, the download, the request, the files it listed and the
+* names it showed them under.
+*
+* The files and names keep their order, since the question showed them in it; the request is canonical JSON, so the
+* same arguments digest the same however an object happened to list its keys.
+*/
+function downloadDigest(download) {
+	return sha256Hex(canonicalJson$1({
+		kind: "download",
+		target: {
+			kind: download.target.kind,
+			name: download.target.name,
+			id: download.target.id
+		},
+		operation: download.operation,
+		request: download.request,
+		files: [...download.files],
+		names: [...download.names]
+	}));
+}
+/**
+* Why a download claimed is not the one its question was asked for, in a sentence — the first difference found. Only
+* the words; what refuses is the digest.
+*/
+function downloadDrift(asked, now) {
+	if (asked.target.id !== now.target.id || asked.target.kind !== now.target.kind) return `the question was about ${asked.target.name}, not ${now.target.name}`;
+	if (asked.operation !== now.operation) return "the question was asked for another kind of download";
+	if (canonicalJson$1(asked.request) !== canonicalJson$1(now.request)) return "the question was asked about a different request: other messages, other files or another limit";
+	if (canonicalJson$1(asked.files) !== canonicalJson$1(now.files)) return "the files are not the ones the question listed";
+	const renamed = asked.files.find((_, index) => asked.names[index] !== now.names[index]);
+	if (renamed !== void 0) return `${renamed} would now be saved under another name than the one the question showed: it was renamed since`;
+	return "the download is not the one the question was asked for";
+}
+/**
+* Why a download's question cannot be claimed under this change policy — the stricter of `livePolicy` and the one it
+* was asked under — or null. Changes nothing, so a download can ask before it looks at a folder, and the store asks
+* again as it claims.
+*
+* Under `chat` nothing stops it: the person's answer, relayed from the conversation, is the answer. Anything stricter
+* needs the answer recorded on the question by a channel an agent cannot answer — the person's own terminal, or a
+* form a trusted client showed them. An answer carried in a tool's arguments or a command's flags is refused however
+* it was worded, with the command that answers it named, and the question left open for the person.
+*/
+function downloadClaimRefusal(record, livePolicy, pendingHint) {
+	if (stricterPolicy(livePolicy, record.requiredPolicy) === "chat") return null;
+	if (record.state === "approved" && (record.approvedVia === "terminal" || record.approvedVia === "elicitation") && record.download?.answer !== void 0) return null;
+	return refuseDownload("APPROVAL_PENDING", "the change policy here is confirm, so the person answers where to save themselves — at their own terminal, not through an agent", record, pendingHint ?? "Ask the person to answer it at their own terminal, with the approve command of the channel the files come from and this choice id; then make the download again with the choice id alone.");
+}
 /** The kind of a record. Absent is a send: every record written before changes had approvals. */
 function approvalKind(record) {
 	return record.kind ?? "send";
@@ -1903,6 +1982,11 @@ function changeDrift(approved, now) {
 	if (canonicalJson$1(approved.effects) !== canonicalJson$1(now.effects)) return "what it does outside the configuration is not what was approved";
 	return "the change is not the one that was approved";
 }
+/**
+* What to do with a download's question, for a caller that took it for something else: it is answered, not approved
+* with a code — in the chat, or at the person's own terminal with the command of the channel that asked.
+*/
+const DOWNLOAD_ANSWER_HINT = "It is answered, not approved with a code: the person says where in the chat, or — under a confirm change policy — at their own terminal, with the `approve` command of the channel the files come from and this id. The download that asked is then made again with this id.";
 const POLICY_RANK = {
 	chat: 0,
 	confirm: 1,
@@ -1931,18 +2015,36 @@ function refuseChange(code, reason, record, hint) {
 		} : {}
 	});
 }
+/**
+* The same refusal for a download's question, which saves nothing until it is claimed.
+*
+* Its hint says to ask again rather than to prepare anything: what the person is shown again is the question, and it
+* is the download itself that asks it.
+*/
+function refuseDownload(code, reason, record, hint) {
+	return new CommsError(code, `nothing was saved: ${reason}`, {
+		hint: hint ?? "Make the download again without an answer, and show the person the new question.",
+		details: record ? {
+			choiceId: record.approvalId,
+			state: record.state
+		} : {}
+	});
+}
 /** The refusal in the words of the record's own kind. */
 function refusalFor(record) {
-	return approvalKind(record) === "change" ? refuseChange : refuse;
+	const kind = approvalKind(record);
+	return kind === "change" ? refuseChange : kind === "download" ? refuseDownload : refuse;
 }
 var ApprovalStore = class {
 	directory;
 	#now;
 	#ttlMs;
+	#downloadTtlMs;
 	constructor(stateDir, options = {}) {
 		this.directory = join(stateDir, "approvals");
 		this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
 		this.#ttlMs = options.ttlMs ?? 6e5;
+		this.#downloadTtlMs = options.downloadTtlMs ?? 18e5;
 	}
 	#path(approvalId, suffix = ".json") {
 		if (!APPROVAL_ID_PATTERN.test(approvalId)) throw refuse("USAGE", `"${approvalId}" is not an approval id`);
@@ -2030,6 +2132,11 @@ var ApprovalStore = class {
 	}
 	#stateError(record) {
 		const refusal = refusalFor(record);
+		if (approvalKind(record) === "download") {
+			if (record.state === "expired") return refusal("APPROVAL_EXPIRED", "the question expired before it was answered", record);
+			if (record.state === "revoked") return refusal("APPROVAL_VOID", `the question was voided (${record.reason ?? "revoked"})`, record);
+			return refusal("APPROVAL_VOID", record.state === "used" ? "the question was answered already, and an answer is used once" : `the question is ${record.state}`, record);
+		}
 		if (record.state === "expired") return refusal("APPROVAL_EXPIRED", "the approval expired before it was used", record);
 		if (record.state === "revoked") return refusal("APPROVAL_VOID", `the approval was voided (${record.reason ?? "revoked"})`, record);
 		return refusal("APPROVAL_REQUIRED", `the approval is ${record.state}`, record);
@@ -2041,8 +2148,11 @@ var ApprovalStore = class {
 	* somebody is about to approve, because an agent passed its id to a change, would punish the wrong party.
 	*/
 	#requireKind(record, kind) {
-		if (approvalKind(record) === kind) return;
+		const actual = approvalKind(record);
+		if (actual === kind) return;
 		const id = record.approvalId;
+		if (actual === "download") throw (kind === "change" ? refuseChange : refuse)("USAGE", `${id} is a question about where to save files, not ${kind === "send" ? "a send" : "a configuration change"}`, record, DOWNLOAD_ANSWER_HINT);
+		if (kind === "download") throw refuseDownload("USAGE", `${id} is ${actual === "change" ? "a configuration change" : "a send"}, not a question about where to save files`, record, "Pass the choice id the download’s question came with, and the person’s answer beside it.");
 		throw kind === "send" ? refuse("USAGE", `approval ${id} is for a configuration change, not a send`, record, `A person approves it with \`agentcomms approve ${id}\` — or ${channelApproveCommands()}, whichever is installed — and it permits only the change it was prepared for.`) : refuseChange("USAGE", `approval ${id} is for a send, not a configuration change`, record, `It is approved with the command that prepared it — ${channelApproveCommands({ sending: true })} — and permits only that send.`);
 	}
 	/** Issues a new challenge to show a human; only its hash is kept. */
@@ -2264,6 +2374,139 @@ var ApprovalStore = class {
 		await this.#markClaimed(result);
 		return result;
 	}
+	/**
+	* A download's question, pending, bound to `downloadDigest(input.download)` — computed here, never taken from the
+	* caller, as a change's digest is. It stands in for the draft revision too.
+	*
+	* `policy` is the change policy of the mailbox or workspace the files come from, as it stands when the question is
+	* asked: where a stranger's files land on this machine is a change to it, and is answered the way that account's
+	* other changes are approved. A claim holds the question to the stricter of this and the policy then.
+	*/
+	async createDownload(input) {
+		const now = this.#now();
+		const download = {
+			summary: input.download.summary,
+			target: { ...input.download.target },
+			operation: input.download.operation,
+			request: JSON.parse(canonicalJson$1(input.download.request)),
+			files: [...input.download.files],
+			names: [...input.download.names],
+			folders: {
+				downloads: input.download.folders.downloads,
+				current: input.download.folders.current
+			},
+			...input.download.listing === void 0 ? {} : { listing: input.download.listing.map((file) => ({
+				name: file.name,
+				size: file.size,
+				...file.renamed === void 0 ? {} : { renamed: file.renamed },
+				...file.flags === void 0 || file.flags.length === 0 ? {} : { flags: [...file.flags] }
+			})) }
+		};
+		const digest = downloadDigest(download);
+		const policy = input.policy === "chat" ? "chat" : "confirm";
+		const record = {
+			approvalId: newApprovalId(),
+			kind: "download",
+			digestVersion: 1,
+			inboxId: download.target.id,
+			draftId: "download",
+			draftMessageId: digest,
+			digest,
+			policy,
+			requiredPolicy: policy,
+			riskFlags: [],
+			expect: {
+				to: [],
+				cc: [],
+				bcc: [],
+				subject: download.summary
+			},
+			challengeAttempts: 0,
+			state: "pending",
+			createdAt: now.toISOString(),
+			expiresAt: new Date(now.getTime() + this.#downloadTtlMs).toISOString(),
+			updatedAt: now.toISOString(),
+			download
+		};
+		await this.#write(record);
+		return record;
+	}
+	/**
+	* Records the person's answer to a download's question, given where an agent cannot give it: at their own terminal,
+	* or in a form a trusted client showed them. The question moves to `approved`, carrying the answer, and waits for
+	* the download to claim it — which it may then do under `confirm`, and which saves where this answer says.
+	*
+	* Only a pending question can be answered, and only once: a second answer is refused, not taken over the first.
+	*/
+	async answerDownload(approvalId, via, answer) {
+		const recorded = answer.choice === "other" ? {
+			choice: "other",
+			folder: answer.folder
+		} : { choice: answer.choice };
+		return await this.#transition(approvalId, (current) => {
+			this.#requireKind(current, "download");
+			if (current.state === "approved") throw refuseDownload("APPROVAL_VOID", "the question was answered already, and it is answered once", current);
+			if (current.state !== "pending") throw this.#stateError(current);
+			if (!current.download || downloadDigest(current.download) !== current.digest) throw refuseDownload("APPROVAL_VOID", "the question does not describe the download it is bound to", current);
+			return {
+				...current,
+				state: "approved",
+				approvedVia: via,
+				approvedDigest: current.digest,
+				download: {
+					...current.download,
+					answer: recorded
+				}
+			};
+		});
+	}
+	/**
+	* Claims a download's question, once, for the download the caller is about to make — and returns it, with the
+	* folders it offered, so that `downloads` and `current` in the answer mean the paths the person read, and with the
+	* answer the person recorded, when they recorded one.
+	*
+	* `live` is the download as the caller computes it now: the same account, the same request, the same files under
+	* the same names — the person answered for those files and no others. Any other is refused, and the question left
+	* open, as it was: a second call that got an argument wrong is the agent's slip, not the person's, and voiding the
+	* question for it would make the person answer again for nothing. It still expires, and is claimed once.
+	*
+	* `options.policy` is the change policy of that account now, and the stricter of it and the one the question was
+	* asked under decides. Under `chat`, a pending question is claimed with the answer the caller carries: the person
+	* 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.
+	*/
+	async claimForDownload(approvalId, live, options = {}) {
+		const digest = downloadDigest(live);
+		let failure = null;
+		const result = await this.#transition(approvalId, (current) => {
+			this.#requireKind(current, "download");
+			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			const voidWith = (reason) => {
+				failure = {
+					code: "APPROVAL_VOID",
+					reason
+				};
+				return {
+					...current,
+					state: "revoked",
+					reason
+				};
+			};
+			if (!current.download || downloadDigest(current.download) !== current.digest) return voidWith("the question does not describe the download it is bound to");
+			if (digest !== current.digest) throw refuseDownload("USAGE", `${downloadDrift(current.download, live)}; the question is still open`, current, "Call again with the same arguments the question was asked with, and its choice id. If the files themselves changed, make the download again without an answer, and show the person the new question.");
+			const refusal = downloadClaimRefusal(current, options.policy ?? "chat", options.pendingHint);
+			if (refusal !== null) throw refusal;
+			return {
+				...current,
+				state: "used"
+			};
+		});
+		const failed = failure;
+		if (failed) throw refuseDownload(failed.code, failed.reason, result);
+		await this.#markClaimed(result);
+		return result;
+	}
 	/** Records the outcome of the one send attempt. */
 	async complete(approvalId, outcome) {
 		return this.#transition(approvalId, (current) => {
@@ -3144,6 +3387,59 @@ function packageFrom(server) {
 	const line = [server.command, ...server.args].join(" ");
 	return /(@[\w.-]+\/[\w.-]+|(?<=\s)[\w.-]+-mcp)(?=@|\s|$)/.exec(line)?.[1];
 }
+/**
+* The programs this package starts, named so that no folder it happens to be in can stand in for them.
+*
+* A bare name is looked up, and on Windows the lookup starts in the current folder: libuv tries it before `PATH`, and
+* so does every program that looks a name up with `SearchPath` or `CreateProcess`. The current folder is where a
+* command was run or a server was started — and, since a download asks where to save, one of the three places a
+* stranger's file may be saved into. A `reg.exe` or `rundll32.exe` saved there would then be what runs the next time
+* this package reads the registry or opens a browser. So a Windows program is named by its full path, under the Windows
+* folder, and every process started on Windows is told, by `NoDefaultCurrentDirectoryInExePath`, not to look in its
+* own current folder for the programs it starts in turn.
+*/
+/** An environment variable by name, whatever its case: Windows's are case-blind, an object passed in is not. */
+function envValue(env, name) {
+	const wanted = name.toLowerCase();
+	for (const [key, value] of Object.entries(env)) if (key.toLowerCase() === wanted && value) return value;
+}
+/**
+* The Windows folder: `%SystemRoot%` (or `%windir%`) when it names a folder on a drive, and `C:\Windows` otherwise.
+* A value that is not a drive's absolute path — relative, a share, a device path — is not taken: it would be looked up
+* against the current folder, or on another machine, which is what naming the program in full is to avoid.
+*/
+function windowsFolder(env = process.env) {
+	for (const name of ["SystemRoot", "windir"]) {
+		const value = envValue(env, name);
+		if (value !== void 0 && /^[A-Za-z]:[\\/]/.test(value)) return path.win32.resolve(value);
+	}
+	return "C:\\Windows";
+}
+/** A program of Windows's own by its full path: `%SystemRoot%\System32\<name>`, never a bare name to look up. */
+function windowsSystemProgram(name, env = process.env) {
+	return path.win32.join(windowsFolder(env), "System32", name);
+}
+/**
+* The environment a child process is started with: `env` as it is, and on Windows also
+* `NoDefaultCurrentDirectoryInExePath=1`, so that the child — `rundll32.exe`, a Node started again — never takes a
+* program from its current folder either. Elsewhere nothing is added: a Unix shell looks in the current folder only
+* when `PATH` says to.
+*/
+function childEnvironment(env = process.env, platform = process.platform) {
+	if (platform !== "win32") return env;
+	return {
+		...env,
+		NoDefaultCurrentDirectoryInExePath: "1"
+	};
+}
+/**
+* The directories of a search path that name a folder on their own: absolute, and on Windows on a drive. An empty
+* entry means the current folder to a Unix shell, and a relative one is read against it; either would make the program
+* found — and run — depend on where this was started, which is where a download may have saved a stranger's file.
+*/
+function absoluteSearchPath(entries, platform = process.platform) {
+	return entries.filter((entry) => platform === "win32" ? /^[A-Za-z]:[\\/]/.test(entry) : entry !== "" && path.posix.isAbsolute(entry));
+}
 /** The install options that pin a server to one account: the generic one, and Gmail's and Slack's own names. */
 const PIN_OPTIONS = Object.freeze([
 	"account",
@@ -3199,9 +3495,14 @@ function clientCliSearch(env) {
 /**
 * The first of `directories` that holds an executable `name`. PATH is read by the caller, once: a test that counts
 * how often the installer looks at PATH counts exactly the looks it means.
+*
+* Only absolute directories are looked in, whoever the caller. An empty entry of PATH is the current folder to a
+* shell, and a relative one is read against it: the `node`, `npx` or `claude` found there — and then run, or written
+* into a client's config to be run — would be whatever is in the folder this was started from, which is where a
+* download may have saved a stranger's file.
 */
 async function executableIn(name, directories, env) {
-	const paths = directories.filter(Boolean);
+	const paths = absoluteSearchPath(directories);
 	const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
 	for (const directory of paths) for (const extension of extensions) {
 		const candidate = join(directory, name + extension.toLowerCase());
@@ -3348,13 +3649,20 @@ async function findNpmCli() {
 	} catch {}
 	throw new CommsError("CONFIG", "npm could not be found next to this Node installation", { hint: "Install with `--launcher npx` instead, which runs the published package directly." });
 }
+/**
+* A command run to its end. Its environment is this process's, and on Windows also tells it never to take a program
+* from its current folder: `npm` and a client's command both start programs of their own by name.
+*/
 function run(command, args) {
 	return new Promise((resolvePromise, reject) => {
-		const child = spawn(command, args, { stdio: [
-			"ignore",
-			"ignore",
-			"pipe"
-		] });
+		const child = spawn(command, args, {
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			],
+			env: childEnvironment(process.env)
+		});
 		let stderr = "";
 		child.stderr?.on("data", (chunk) => {
 			stderr += String(chunk);
@@ -3580,14 +3888,20 @@ function installCommand$1(product, options, name, extra = []) {
 	words.push(...extra);
 	return words.map((word) => /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`).join(" ");
 }
-/** A command's exit status and what it printed, kept here and never shown: codex prints an entry's env. */
+/**
+* A command's exit status and what it printed, kept here and never shown: codex prints an entry's env. Started as
+* `run` starts one, so that on Windows it takes no program from its current folder either.
+*/
 function capture$1(command, args) {
 	return new Promise((resolvePromise, reject) => {
-		const child = spawn(command, args, { stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		] });
+		const child = spawn(command, args, {
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			env: childEnvironment(process.env)
+		});
 		let stdout = "";
 		let stderr = "";
 		child.stdout?.on("data", (chunk) => {
@@ -4040,11 +4354,27 @@ async function verifyEntry(entry, product) {
 		await client.close().catch(() => void 0);
 	}
 }
-/** Every running process's command line, or null when they cannot be listed. */
-async function runningCommandLines() {
+/** Where `ps` is looked for, in order: the system's own directories, never PATH. */
+const PS_DIRECTORIES = ["/bin", "/usr/bin"];
+/**
+* Every running process's command line, or null when they cannot be listed.
+*
+* `ps` is started by its full path, `/bin/ps` or else `/usr/bin/ps`, never by its bare name: a name is looked up, and
+* a lookup can reach the folder this was started from — where a download may have saved a stranger's `ps`, which would
+* then run, and whose answer would decide what is deleted. With neither there, the processes cannot be listed.
+*
+* `directories` and `list` are for tests: where to look for `ps`, and what runs the one found.
+*/
+async function runningCommandLines(options = {}) {
 	if (process.platform === "win32") return null;
+	const ps = await executableIn("ps", options.directories ?? PS_DIRECTORIES, process.env);
+	if (ps === null) return null;
+	return (options.list ?? commandLinesFrom)(ps);
+}
+/** What `ps` at this path says is running: one command line per process, or null when it fails. */
+function commandLinesFrom(ps) {
 	return new Promise((resolvePromise) => {
-		execFile("ps", [
+		execFile(ps, [
 			"-A",
 			"-o",
 			"args="
@@ -4780,6 +5110,7 @@ async function claimChange(core, approvalId, expect, options) {
 async function changeRecord(core, approvalId) {
 	const record = await core.approvals.get(approvalId);
 	if (!record) throw new CommsError("NOT_FOUND", `no approval ${approvalId}`, { hint: "Prepare the change again; an approval expires ten minutes after it is made." });
+	if (approvalKind(record) === "download") throw new CommsError("USAGE", `${approvalId} is a question about where to save files, not a configuration change`, { hint: DOWNLOAD_ANSWER_HINT });
 	if (approvalKind(record) !== "change") throw new CommsError("USAGE", `approval ${approvalId} is for a send, not a configuration change`, { hint: `Approve it with the command that prepared it: ${channelApproveCommands({ sending: true })}.` });
 	if (!record.change || changeDigest(record.change) !== record.digest) throw new CommsError("BAD_DATA", "this approval does not describe the change it is bound to", {
 		hint: "Nothing was approved. Prepare the change again.",
@@ -5627,7 +5958,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.9.0";
+const VERSION = "0.11.0";
 /**
 * Registering, pruning and listing the MCP servers of every channel, from the core.
 *
@@ -5882,7 +6213,7 @@ function serverPruneChange(core, env, request, own) {
 	};
 	const { packageName, version } = ownProduct(request.channel, own) ?? {
 		packageName: channelServer(request.channel).packageName,
-		version: "0.9.0"
+		version: "0.11.0"
 	};
 	const product = {
 		packageName,
@@ -6227,6 +6558,10 @@ Object.freeze({
 	lookup: true
 });
 Object.freeze({ kind: "change" });
+Object.freeze({
+	kind: "download",
+	argument: "choiceId"
+});
 /**
 * Whether a call claims an approval the person already gave (§2): an approval this machine's approval store holds —
 * every channel keeps its approvals there — that is still waiting to be used, pending or approved, and of the kind the
@@ -6278,7 +6613,8 @@ function updateToolGate(options) {
 			surface: "server"
 		});
 		if (pending === null) return null;
-		if (await claimsApproval(options.core, args.approvalId, options.approvals?.[tool])) return null;
+		const claim = options.approvals?.[tool];
+		if (await claimsApproval(options.core, args[claim?.argument ?? "approvalId"], claim)) return null;
 		return stoppedCall(pending, {
 			server: options.server,
 			tool
@@ -6343,9 +6679,10 @@ function commandPathOf(command) {
 }
 /**
 * The approvals a Commander command claims: its `--approval`, the `--mcp-approval` Gmail's `setup` carries beside it,
-* and an argument named `approvalId` — `agent-gmail send cancel <approvalId>`, `agent-resend send execute
-* <approvalId>`, the commands whose tools take it as `approvalId`. What the gate hands `claimsApproval`, as a tool
-* call's `approvalId` is handed it. Commander has read the arguments by the time a `preAction` hook runs.
+* the `--choice` a download carries its question's id in, and an argument named `approvalId` — `agent-gmail send
+* cancel <approvalId>`, `agent-resend send execute <approvalId>`, the commands whose tools take it as `approvalId`.
+* What the gate hands `claimsApproval`, as a tool call's `approvalId` is handed it. Commander has read the arguments
+* by the time a `preAction` hook runs.
 */
 function approvalsOf(command) {
 	const options = command.opts();
@@ -6353,6 +6690,7 @@ function approvalsOf(command) {
 	return [
 		options.approval,
 		options.mcpApproval,
+		options.choice,
 		...named
 	];
 }
@@ -6499,7 +6837,7 @@ async function askLine(streams, question) {
 	}
 }
 //#endregion
-//#region ../core/dist/tool-arguments-Cx3Of7xZ.mjs
+//#region ../core/dist/tool-arguments-5aAzuZnA.mjs
 const APPLIED = Symbol.for("agentcomms.strictToolArguments");
 const TARGET = "draft-2020-12";
 /**
@@ -6517,7 +6855,7 @@ const TARGET = "draft-2020-12";
 * in, because what it asks the registry with is each server's own — and WhatsApp's is nothing at all. A call it
 * answers reaches nothing, as a refused one does.
 */
-function strictToolArguments(server, refuse, gate) {
+function strictToolArguments(server, refuse, gate, retired = {}) {
 	const target = server;
 	if (typeof target.registerTool !== "function") throw new Error("strictToolArguments needs an MCP server: this has no registerTool");
 	if (target[APPLIED]) return;
@@ -6533,7 +6871,7 @@ function strictToolArguments(server, refuse, gate) {
 			inputSchema: passThrough(schema)
 		}, async (input, context) => {
 			const parsed = await schema.safeParseAsync(input ?? {});
-			if (!parsed.success) return refuse(refusal(name, published, input, parsed.error.issues));
+			if (!parsed.success) return refuse(refusal(name, published, input, parsed.error.issues, retired[name] ?? {}));
 			const stopped = gate ? await gate(name, parsed.data) : null;
 			if (stopped !== null) return stopped;
 			return declared ? handler(parsed.data, context) : handler(context);
@@ -6577,12 +6915,22 @@ function passThrough(schema) {
 	} };
 }
 /** A USAGE refusal naming what was wrong and what the tool takes. */
-function refusal(tool, published, input, issues) {
+function refusal(tool, published, input, issues, retired) {
 	const properties = published.properties ?? {};
 	const takes = Object.keys(properties);
 	const required = new Set(published.required ?? []);
 	const signature = takes.length === 0 ? `${tool} takes no arguments.` : `${tool} takes ${spoken(takes.map((key) => required.has(key) ? `\`${key}\` (required)` : `\`${key}\``), "and")}.`;
 	const unknown = issues.flatMap((issue) => issue.code === "unrecognized_keys" && issue.path.length === 0 ? issue.keys : []);
+	const removed = unknown.filter((key) => Object.hasOwn(retired, key));
+	if (removed.length > 0) return new CommsError("USAGE", `${tool} no longer takes ${spoken(removed.map((key) => `\`${key}\``), "or")}`, {
+		hint: removed.map((key) => retired[key]).join(" "),
+		details: {
+			tool,
+			retired: removed,
+			unknown,
+			takes
+		}
+	});
 	if (unknown.length > 0) return new CommsError("USAGE", `${tool} does not take ${spoken(unknown.map((key) => `\`${key}\``), "or")}`, {
 		hint: takes.length === 0 ? signature : `${signature} Leave out anything else.`,
 		details: {
@@ -10096,4 +10444,4 @@ async function syncAccount(context, request) {
 	});
 }
 //#endregion
-export { serverInstallChange as $, CommsError as A, escapeForDisplay as B, checkStorePath as C, strictToolArguments as D, UNTRUSTED_NOTICE as E, approveChangeAtTerminal as F, lookupName as G, gatedChangeAtTerminal as H, canPrompt as I, openCore as J, nameAvailable as K, channelManifest as L, agentMarker as M, approvalKind as N, CHANNELS as O, approvalsOf as P, runCommand as Q, colorEnabled as R, storeIdentity as S, expandSource as T, installExitStatus as U, exemptFromUpdateGate as V, isCommsError as W, renderInstall as X, paint as Y, renderPrune as Z, chatRefOf as _, listChats as a, withFileLock as at, requireAccount as b, Presenter as c, draftMessage as d, serverPruneChange as et, Visibility as f, requireSupportedNode as g, WhatsAppIndex as h, CHAT_KINDS as i, updateToolGate as it, EXIT_CODES as j, CHANNEL_SERVERS as k, innerText as l, WhatsAppContext as m, whatsappStatus as n, truncateDisplay as nt, readChat as o, writeResult as ot, listKey as p, nameShapeProblem as q, probeStore as r, updateGateAtTerminal as rt, searchMessages as s, VERSION$1 as st, syncAccount as t, toCommsError as tt, composeDraft as u, PLATFORM as v, defaultStorePath as w, requireNamedConfig as x, newWhatsAppAccount as y, commandPathOf as z };
+export { renderPrune as $, CommsError as A, colorEnabled as B, checkStorePath as C, strictToolArguments as D, UNTRUSTED_NOTICE as E, approvalsOf as F, installExitStatus as G, escapeForDisplay as H, approveChangeAtTerminal as I, nameAvailable as J, isCommsError as K, canPrompt as L, absoluteSearchPath as M, agentMarker as N, CHANNELS as O, approvalKind as P, renderInstall as Q, channelManifest as R, storeIdentity as S, expandSource as T, exemptFromUpdateGate as U, commandPathOf as V, gatedChangeAtTerminal as W, openCore as X, nameShapeProblem as Y, paint as Z, chatRefOf as _, listChats as a, updateGateAtTerminal as at, requireAccount as b, Presenter as c, withFileLock as ct, draftMessage as d, runCommand as et, Visibility as f, requireSupportedNode as g, WhatsAppIndex as h, CHAT_KINDS as i, truncateDisplay as it, EXIT_CODES as j, CHANNEL_SERVERS as k, innerText as l, writeResult as lt, WhatsAppContext as m, whatsappStatus as n, serverPruneChange as nt, readChat as o, updateToolGate as ot, listKey as p, lookupName as q, probeStore as r, toCommsError as rt, searchMessages as s, windowsSystemProgram as st, syncAccount as t, serverInstallChange as tt, composeDraft as u, VERSION$1 as ut, PLATFORM as v, defaultStorePath as w, requireNamedConfig as x, newWhatsAppAccount as y, childEnvironment as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcomms/whatsapp",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "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.9.0"
+    "@agentcomms/core": "0.11.0"
   },
   "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": "7db27256fda2e40fcc2a4958c50bf77bff871ef1"
+  "gitHead": "bcc1392f8380dbf523a910a87de652a18faead6f"
 }