a2a-exposed 0.8.40 → 0.8.42

package/lib/status.mjs

@@ -2,11 +2,14 @@
 // calls only), so an agent that was interrupted can resume from the printed next step. The CLI fetches the agent card
 // itself, so agents need no curl (some agent sandboxes flag *.dev URLs in shell commands).
 import dns from "node:dns";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { isIP } from "node:net";
 import path from "node:path";
+import os from "node:os";
 import { promisify } from "node:util";
 import * as C from "./config.mjs";
+import { runtimeInfo } from "./runtime.mjs";
 import { CLI, cardUrlProblem, cfErrorCode, describeHttp, die, fingerprint, httpJson, isPrivateHost } from "./a2a.mjs";
 import { baseUrl, owner, ownerTry } from "./commands.mjs";
 import * as D from "./deploy.mjs";
@@ -14,6 +17,44 @@ import { buildLayers, layerValue, usablePin } from "./layers.mjs";
 import * as T from "./tunnel.mjs";
 import { cacheFile, readCache, newer } from "./update.mjs";
 
+/** Best-effort local check only. A terminal-attached process using this exact token file is ephemeral.
+ * Never return process arguments (they may contain credentials), or infer persistence from remote connections. */
+export function connectorPersistence(tokenFile, { platform = process.platform, run = spawnSync, exists = fs.existsSync, home = os.homedir() } = {}) {
+	if (!["darwin", "linux"].includes(platform) || !tokenFile) return "unknown";
+	try {
+		const ps = run("ps", ["-axo", "tty=,comm=,args="], { encoding: "utf8", timeout: 2000, maxBuffer: 1024 * 1024 });
+		if (ps.status !== 0 || ps.error) return "unknown";
+		const fileForms = [tokenFile, C.shellQuote(tokenFile), '"' + tokenFile.replaceAll('"', '\\"') + '"'];
+		const foreground = ps.stdout.split("\n").some((line) => {
+			const row = line.trim().match(/^(\S+)\s+(\S+)\s+(.+)$/);
+			if (!row || row[1] === "-" || row[1].startsWith("?")) return false;
+			if (path.basename(row[2]) !== "cloudflared" || !/\btunnel\s+run\b/.test(row[3])) return false;
+			return ["--token-file ", "--token-file="].some((flag) => fileForms.some((file) =>
+				row[3].endsWith(flag + file) || row[3].includes(flag + file + " --")));
+		});
+		if (!foreground) return "unknown";
+		const serviceFiles = platform === "darwin"
+			? ["/Library/LaunchDaemons/com.cloudflare.cloudflared.plist", "/Library/LaunchAgents/com.cloudflare.cloudflared.plist", path.join(home, "Library/LaunchAgents/com.cloudflare.cloudflared.plist")]
+			: ["/etc/systemd/system/cloudflared.service", "/usr/lib/systemd/system/cloudflared.service", path.join(home, ".config/systemd/user/cloudflared.service")];
+		if (serviceFiles.some(exists)) return "unknown";
+		const service = platform === "darwin"
+			? run("launchctl", ["list"], { encoding: "utf8", timeout: 2000, maxBuffer: 1024 * 1024 })
+			: run("systemctl", ["list-unit-files", "--type=service", "--no-pager", "--no-legend"], { encoding: "utf8", timeout: 2000, maxBuffer: 1024 * 1024 });
+		if (service.status !== 0 || service.error || /cloudflared/i.test(service.stdout)) return "unknown";
+		if (platform === "linux") {
+			const user = run("systemctl", ["--user", "list-unit-files", "--type=service", "--no-pager", "--no-legend"], { encoding: "utf8", timeout: 2000, maxBuffer: 1024 * 1024 });
+			if (user.status !== 0 || user.error || /cloudflared/i.test(user.stdout)) return "unknown";
+		}
+		// This describes the observed terminal process, not every possible custom service.
+		return "ephemeral";
+	} catch { return "unknown"; }
+}
+
+export function connectorLine(t) {
+	const state = t.connections == null ? "unknown" : t.connections > 0 ? `connected (${t.connections})` : "not connected (0)";
+	return `${state}, ${t.persistence === "ephemeral" ? "ephemeral (local terminal connector; no cloudflared service found)" : "persistence unknown"}`;
+}
+
 const DOH_URL = "https://cloudflare-dns.com/dns-query";
 const LOOKUP_MS = 5000;
 
@@ -284,7 +325,7 @@ export function nextStep(s) {
 	const n = nextStepCore(s);
 	const version = s.cliVersion || D.VERSION;
 	if (s.deployment !== "hosted" && s.workerVersion && s.latestVersion && newer(s.latestVersion, s.workerVersion) && !newer(s.workerVersion, version))
-		n.also.push(`a2a-exposed ${s.latestVersion} is available: run npx -y a2a-exposed@latest deploy`);
+		n.also.push(`a2a-exposed ${s.latestVersion} is available: run ${CLI} deploy`);
 	const sh = (s.peerTokenShadowed || []).map((k) => `${k} is set in the environment and overrides the different peer token saved in ${s.configFile} (e.g. a stale value from before \`connect\` stored a new one): send/poll use the environment value. Unset ${k} where it is set to use the saved token`);
 	const addr = s.addresses;
 	if (addr && Array.isArray(addr.announcePending) && addr.announcePending.length)
@@ -362,7 +403,7 @@ function nextStepCore(s) {
 		if (s.pairing && s.pairing.mode === "human" && !s.pairing.passwordSet)
 			also.push(`peers can't connect yet: run \`${CLI} pair set-password --web\` and send your human the one-time link (or they run \`${CLI} pair set-password\` in a terminal); never set it yourself`);
 		if (s.pairing && s.pairing.pending) also.push(`${s.pairing.pending} pending pairing request(s): \`${CLI} pair list\`, then tell your human (never approve on your own)`);
-		return done(`none: the façade is up and forwards paired peers' A2A calls to the upstream. Peers connect with \`${CLI} connect ${s.baseUrl}\``, also);
+		return done(`none: the façade is up and forwards paired peers' A2A calls to the upstream. Peers connect with \`${C.DEFAULT_CLI_COMMAND} connect ${s.baseUrl}\``, also);
 	}
 	const t = s.tunnel;
 	if (t && !t.complete) return fail(`a previous \`tunnel create\` did not finish: run \`${CLI} tunnel rm\`, then \`${CLI} tunnel create\``);
@@ -402,7 +443,7 @@ function nextStepCore(s) {
 		return done2(`no wake webhook, so ${poll}.`, [`optional: ${tunnel}`, ...(pub ? [`optional: ${pub}`] : [])]);
 	}
 	return done2(`none: setup is complete. Check a real wake with \`${CLI} wake test\`.`,
-		[`peers connect with \`${CLI} connect ${s.baseUrl}\` (your human approves each one); \`${CLI} token issue <peer>\` is the manual fallback`]);
+		[`peers connect with \`${C.DEFAULT_CLI_COMMAND} connect ${s.baseUrl}\` (your human approves each one); \`${CLI} token issue <peer>\` is the manual fallback`]);
 }
 
 function hostOf(url) {
@@ -465,7 +506,7 @@ function finishLayers(s, extra) {
  *  `net.lookup` and `net.doh` replace the system resolver and DNS-over-HTTPS in tests. */
 export async function collect(net = {}) {
 	const s = {
-		configFile: C.CONFIG_FILE,
+		configFile: C.CONFIG_FILE, runtime: runtimeInfo(),
 		deployment: C.deploymentKind(),
 		deployed: !!(C.get("A2A_D1_ID") && C.get("A2A_WORKER_NAME")),
 		worker: C.get("A2A_WORKER_NAME"), d1: C.get("A2A_D1_NAME"), account: C.get("CLOUDFLARE_ACCOUNT_ID"), cfProfile: C.get("CF_PROFILE"),
@@ -535,7 +576,8 @@ export async function collect(net = {}) {
 			const url = T.wakeUrl(tunnelHost || "?", C.get("A2A_TUNNEL_PATH") || "/");
 			s.tunnel = { hostname: tunnelHost, wakeUrl: url, origin: C.get("A2A_TUNNEL_ORIGIN"), complete: T.tunnelComplete(), tokenFileOk: T.tokenFileOk(),
 				tokenFile: C.get("A2A_TUNNEL_TOKEN_FILE") || "<config dir>/tunnel-token", workerUrlMatches: s.wake?.urlFingerprint === fingerprint(url),
-				secretsAt: Number(C.get("A2A_TUNNEL_SECRETS_AT")) || 0, connections: null };
+				secretsAt: Number(C.get("A2A_TUNNEL_SECRETS_AT")) || 0, connections: null,
+				persistence: connectorPersistence(C.get("A2A_TUNNEL_TOKEN_FILE")) };
 			if (haveCf && C.get("A2A_TUNNEL_ID")) {
 				try {
 					const t = T.cfCall(dir, ["tunnels", "get", C.get("A2A_TUNNEL_ID")], { allowNotFound: true });
@@ -609,6 +651,7 @@ export async function status(o) {
 	else {
 		const rows = [
 			["config", s.configFile],
+			["runtime", `Node ${s.runtime.node} (${s.runtime.execPath})${s.runtime.warning ? `; WARNING: ${s.runtime.warning}` : ""}`],
 			["deployment", s.deployment === "hosted" ? "hosted" : s.deployed ? `Worker ${s.worker}, D1 ${s.d1 || s.worker}${s.account ? `, account ${s.account}` : ""}${s.cfProfile ? `, cf profile ${s.cfProfile}` : ""}${s.cron ? ", cron flush on" : ""}` : "none"],
 			["base URL", s.baseUrl ? `${s.baseUrl} (${s.baseUrlEnv ? `from the exported A2A_BASE_URL; ${s.configFile} has ${s.baseUrlSaved || "none"}` : s.urlKind})` : "(not saved)"],
 		];
@@ -636,6 +679,7 @@ export async function status(o) {
 			const t = s.tunnel;
 			rows.push(["tunnel", !t ? "none" : `${t.wakeUrl} -> ${t.origin || "?"}; ${!t.complete ? "INCOMPLETE" : t.tokenFileOk ? "set up" : "set up, but the connector token file is MISSING"}` +
 				(t.connections != null ? `; ${tunnelStateLabel(t.state)}, ${t.connections} connector connection(s)` : t.error ? `; state unknown (${t.error})` : "")]);
+			if (t) rows.push(["connector", connectorLine(t)]);
 			if (s.zones) rows.push(["zones", s.zones.length ? s.zones.join(", ") : "none on this account"]);
 			const addr = s.addresses;
 			if (addr) {

package/lib/tunnel.mjs

@@ -22,7 +22,7 @@ const step = (s) => console.error(`==> ${s}`);
 export const ORIGIN_DEFAULTS = {
 	"openclaw-wake": ["http://127.0.0.1:18789", "/hooks/wake"],
 	"openclaw-agent": ["http://127.0.0.1:18789", "/hooks/agent"],
-	hermes: ["http://127.0.0.1:8644", ""], // path is /webhooks/<subscription name>: pass --tunnel-path
+	hermes: ["http://127.0.0.1:8644", "/webhooks/a2a-wake"],
 	generic: ["", ""],
 };
 export const HOSTED_PRESETS = ["grok-bot", "claude-code"];
@@ -99,7 +99,7 @@ export function pickTunnelHostname({ tunnelHostname, tunnelZone, inboxHost, zone
 	return die([
 		`this Cloudflare account has ${usable.length} zones; choose one for the wake hostname (the A2A endpoint URL is unchanged):`,
 		zoneList(usable),
-		"Re-run with --tunnel-zone <zone>  (or --tunnel-hostname wake-<name>.<zone>).",
+		`List choices with \`${CLI} tunnel zones --json\`. Re-run with --tunnel-zone <zone>  (or --tunnel-hostname wake-<name>.<zone>).`,
 	].join("\n"));
 }
 
@@ -156,7 +156,9 @@ export function connectorInstructions(tokenFile, token = "") {
 		"Run the connector there (outbound TCP/UDP 7844 to Cloudflare must be allowed):",
 		`  cloudflared tunnel run --token-file ${tokenFile}        # cloudflared 2025.4+`,
 		`  cloudflared tunnel run --token ${t}`,
-		`  sudo cloudflared service install ${t}   # as a system service (starts on boot)`,
+		`  sudo cloudflared service install ${t}   # optional system service (starts on boot)`,
+		"  On macOS, service install needs an admin password at a terminal; do not run it unattended.",
+		"  Without admin access, keep the --token-file command in a terminal, or use a user LaunchAgent (untested).",
 		token ? "  (token shown because of --show-token: treat it like a password)"
 			: `  The tunnel token is in ${tokenFile} (chmod 600). Copy that file to the agent's machine if it is another machine.`,
 	].join("\n");
@@ -281,9 +283,13 @@ export function preflight(o) {
 	if (HOSTED_PRESETS.includes(preset)) die(`preset ${preset} wakes a hosted service; a tunnel is only for local-only webhooks (openclaw-*, hermes, generic)`);
 	const [dOrigin, dPath] = ORIGIN_DEFAULTS[preset] || ["", ""];
 	const origin = o["tunnel-origin"] || C.get("A2A_TUNNEL_ORIGIN") || dOrigin;
-	const wpath = o["tunnel-path"] || C.get("A2A_TUNNEL_PATH") || dPath;
+	if (o["hermes-route"] !== undefined && (preset !== "hermes" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(o["hermes-route"])))
+		die("--hermes-route requires --preset hermes and a route name of 1–64 letters, digits, underscores or hyphens");
+	if (o["hermes-route"] && o["tunnel-path"]) die("choose --hermes-route or --tunnel-path, not both");
+	if (o["hmac-secret-stdin"] && preset !== "hermes") die("--hmac-secret-stdin requires --preset hermes");
+	const wpath = o["hermes-route"] ? `/webhooks/${o["hermes-route"]}` : o["tunnel-path"] || C.get("A2A_TUNNEL_PATH") || dPath;
 	if (!origin) die(`--tunnel-origin is required for preset ${preset} (the local webhook, e.g. http://127.0.0.1:8080)`);
-	if (!wpath || !wpath.startsWith("/")) die(`--tunnel-path is required for preset ${preset} and must start with / (e.g. /webhooks/a2a for Hermes)`);
+	if (!wpath || !wpath.startsWith("/")) die(`--tunnel-path is required for preset ${preset} and must start with / (e.g. /webhooks/a2a-wake for Hermes)`);
 	if (o["tunnel-hostname"] && !HOST_RE.test(o["tunnel-hostname"])) die("--tunnel-hostname must be a hostname like wake-abc.example.com");
 	if (o["tunnel-zone"] && !HOST_RE.test(o["tunnel-zone"].toLowerCase())) die("--tunnel-zone must be a zone name like example.com");
 	if (o["tunnel-zone"] && o["tunnel-hostname"]) die("pass --tunnel-zone or --tunnel-hostname, not both");
@@ -292,10 +298,18 @@ export function preflight(o) {
 }
 
 export async function create(o) {
-	D.checkNode();
 	const dir = needDeployment(o);
-	if (tunnelStarted()) return resume(dir, o);
+	D.checkNode();
+	if (tunnelStarted() && !tunnelComplete()) return resume(dir, o, {});
 	const { preset, origin, wpath } = preflight(o);
+	if (o.preset && o.preset !== C.get("WAKE_PRESET", "generic"))
+		die(`the deployed preset must match --preset ${preset}; run \`${CLI} wake set --preset ${preset}\` first`);
+	const agentAuth = tunnelAuth(o);
+	if (tunnelStarted()) {
+		if (tunnelComplete() && ((o["tunnel-origin"] && origin !== C.get("A2A_TUNNEL_ORIGIN")) || ((o["tunnel-path"] || o["hermes-route"]) && wpath !== C.get("A2A_TUNNEL_PATH"))))
+			die("a tunnel already exists with a different origin/path; run tunnel rm before changing it");
+		return resume(dir, o, agentAuth);
+	}
 	const worker = D.workerName();
 	try {
 		const preview = await owner("GET", "/owner/wake/preview");
@@ -346,20 +360,22 @@ export async function create(o) {
 
 		const url = wakeUrl(hostname, wpath);
 		step("uploading Worker secrets: WAKE_WEBHOOK_URL, WAKE_ACCESS_CLIENT_ID, WAKE_ACCESS_CLIENT_SECRET" +
-			(process.env.WAKE_WEBHOOK_KEY ? ", WAKE_WEBHOOK_KEY" : "") + (process.env.WAKE_HMAC_SECRET ? ", WAKE_HMAC_SECRET" : ""));
+			(process.env.WAKE_WEBHOOK_KEY ? ", WAKE_WEBHOOK_KEY" : "") + (agentAuth.WAKE_HMAC_SECRET ? ", WAKE_HMAC_SECRET" : ""));
 		const secrets = { WAKE_WEBHOOK_URL: url, WAKE_ACCESS_CLIENT_ID: st.client_id, WAKE_ACCESS_CLIENT_SECRET: st.client_secret };
-		for (const k of ["WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET"]) if (process.env[k]) secrets[k] = process.env[k];
+		Object.assign(secrets, agentAuth);
 		await putSecrets(dir, worker, secrets);
 		createdSecrets = Object.keys(secrets);
 
+		if (preset === "hermes" && /^\/webhooks\/[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(wpath)) console.error(hermesInstructions(wpath.slice("/webhooks/".length)));
 		console.log(url);
 		console.error(`\nAccess application "${label}" (id ${app.id}); service token id ${st.id}; tunnel id ${tun.id}.`);
 		console.error(`tunnel ready: wakes go to ${url} -> ${origin}${wpath} on the agent's machine`);
 		console.error(connectorInstructions(tokenFile, o["show-token"] ? token : ""));
 		console.error(`\nTo undo this, run \`${CLI} tunnel rm\`.`);
 		console.error(`Then (Worker secrets apply within about 15 to 40 seconds; wait about 30 seconds): ${CLI} tunnel status   and   ${CLI} wake test`);
-		if (!process.env.WAKE_WEBHOOK_KEY && !process.env.WAKE_HMAC_SECRET && preset !== "generic")
+		if (!Object.keys(agentAuth).length && preset !== "generic")
 			console.error(`note: no WAKE_WEBHOOK_KEY / WAKE_HMAC_SECRET in the environment; keep the ${preset} webhook's own auth too (export it and run \`wake set\`)`);
+		console.error("created: tunnel, DNS, Access app, token\nconnector: not running (start it now)\npersistent service: not installed (optional)");
 	} catch (e) {
 		console.error("==> rolling back what was created");
 		await remove(o, { quiet: true, secretNames: createdSecrets }).catch((r) => console.error(`rollback incomplete: ${r.message}; re-run \`${CLI} tunnel rm\``));
@@ -367,6 +383,31 @@ export async function create(o) {
 	}
 }
 
+/** No prompt, argv secret, or config.env persistence. */
+function tunnelAuth(o) {
+	const auth = {};
+	for (const key of ["WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET"]) if (process.env[key]) auth[key] = process.env[key];
+	if (o["hmac-secret-stdin"]) {
+		if (process.stdin.isTTY) die("--hmac-secret-stdin requires a protected file redirected to stdin; terminal prompts are not supported");
+		const secret = fs.readFileSync(0, "utf8").replace(/\r?\n$/, "");
+		if (!secret || secret.length > 4096 || /[\u0000-\u001f\u007f]/.test(secret))
+			die("--hmac-secret-stdin requires one non-empty line of at most 4096 printable characters");
+		auth.WAKE_HMAC_SECRET = secret;
+	}
+	return auth;
+}
+
+export function hermesInstructions(route) {
+	return [
+		"Hermes receiver (run subscribe once; keep its generated secret in protected storage):",
+		`  hermes cron create "every 6h" "Use the a2a-exposed skill. Run '${CLI} inbox'; follow the owner's handling mode and approval rules. Report peer, task and outcome without peer text or secrets; if empty, respond only [SILENT]." --skill a2a-exposed --name a2a-inbox --deliver origin`,
+		`  hermes webhook subscribe ${route} --events a2a_wake --cron-job a2a-inbox --prompt "A2A wake: {kind} from {from}, context {contextId}. Run: {hint}"`,
+		"Do not recreate an existing subscription: that can change its signing secret.",
+		`After starting the connector: ${CLI} wake check`,
+		"Recipe: https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/hermes.md",
+	].join("\n");
+}
+
 /** Download the tunnel's connector token into <config dir>/tunnel-token (chmod 600) and save its path. */
 function fetchTokenFile(dir, tunnelId) {
 	const tok = cfCall(dir, ["tunnels", "token", "get", tunnelId]);
@@ -396,7 +437,7 @@ export const tunnelComplete = () =>
  *  are re-uploaded if the Worker lacks them (e.g. the first run was interrupted), together with WAKE_WEBHOOK_KEY /
  *  WAKE_HMAC_SECRET when exported (as on a first run); a missing connector token file is downloaded again. A partial
  *  tunnel must be removed first. */
-async function resume(dir, o) {
+async function resume(dir, o, agentAuth) {
 	if (!tunnelComplete())
 		die(`a previous \`tunnel create\` did not finish (some ids are saved, see \`${CLI} status\`); run \`${CLI} tunnel rm\`, then \`${CLI} tunnel create\` again`);
 	const host = C.get("A2A_TUNNEL_HOSTNAME");
@@ -409,8 +450,6 @@ async function resume(dir, o) {
 	const url = wakeUrl(host, C.get("A2A_TUNNEL_PATH") || "/");
 	let p = null;
 	try { p = await owner("GET", "/owner/wake/preview"); } catch (e) { console.error(`warning: Worker not reachable (${e.message}); cannot check its wake secrets`); }
-	const agentAuth = {};
-	for (const k of ["WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET"]) if (process.env[k]) agentAuth[k] = process.env[k];
 	const lacksTunnel = p && (!p.hasAccessServiceToken || p.fingerprints?.url !== fingerprint(url));
 	if (lacksTunnel || Object.keys(agentAuth).length) {
 		const secrets = { WAKE_WEBHOOK_URL: url, WAKE_ACCESS_CLIENT_ID: C.get("A2A_TUNNEL_ACCESS_CLIENT_ID"), WAKE_ACCESS_CLIENT_SECRET: C.get("A2A_TUNNEL_ACCESS_CLIENT_SECRET"), ...agentAuth };
@@ -420,6 +459,7 @@ async function resume(dir, o) {
 	const preset = C.get("WAKE_PRESET", "generic");
 	if (p && !p.hasKey && !p.hasHmacSecret && !Object.keys(agentAuth).length && preset !== "generic")
 		console.error(`warning: the Worker has no WAKE_WEBHOOK_KEY / WAKE_HMAC_SECRET, so the ${preset} webhook will reject wakes; export it and run \`${CLI} tunnel create\` again`);
+	if (preset === "hermes" && /^\/webhooks\/[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(C.get("A2A_TUNNEL_PATH"))) console.error(hermesInstructions(C.get("A2A_TUNNEL_PATH").slice("/webhooks/".length)));
 	console.log(url);
 	console.error(`tunnel already set up: wakes go to ${url} -> ${C.get("A2A_TUNNEL_ORIGIN")}${C.get("A2A_TUNNEL_PATH")} (nothing new created; to change it: tunnel rm, then tunnel create)`);
 	console.error(connectorInstructions(C.get("A2A_TUNNEL_TOKEN_FILE")));
@@ -543,8 +583,12 @@ export async function remove(o, { quiet = false, allowMissingProject = false, sk
 }
 
 export async function tunnel(sub, o) {
+	if (sub === "zones") {
+		const zones = usableZones(listZones(needDeployment(o))).map(({ id, name, status }) => ({ id, name, status: status || "active" }));
+		return console.log(o.json ? JSON.stringify(zones, null, 2) : zoneList(zones) || "No active zones; use polling.");
+	}
 	if (sub === "create") return create(o);
 	if (sub === "status") return status(o);
 	if (sub === "rm") return remove(o);
-	die("usage: tunnel create|status|rm");
+	die("usage: tunnel create|zones|status|rm");
 }

package/lib/update.mjs

@@ -2,6 +2,7 @@
 // version and caches it; every run only reads that cache (no network call in the foreground). Off with
 // A2A_NO_UPDATE_CHECK=1, DO_NOT_TRACK=1, NO_UPDATE_NOTIFIER, CI, and when running from a source checkout.
 import fs from "node:fs";
+import { CLI_COMMAND } from "./config.mjs";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
@@ -31,7 +32,7 @@ export function newer(a, b) {
 /** The notice for `current`, given the cache contents (or "" when up to date / unknown). */
 export function notice(current, cache) {
 	if (!cache || !cache.latest || !newer(cache.latest, current)) return "";
-	return `a2a-exposed ${cache.latest} is available (you have ${current}): run npx -y a2a-exposed@latest deploy (updates the Worker; applies new D1 migrations). With a global install, npm i -g a2a-exposed@latest first. Silence: A2A_NO_UPDATE_CHECK=1`;
+	return `a2a-exposed ${cache.latest} is available (you have ${current}): run ${CLI_COMMAND} deploy (updates the Worker; applies new D1 migrations). With a global install, npm i -g a2a-exposed@latest first. Silence: A2A_NO_UPDATE_CHECK=1`;
 }
 
 export const due = (cache, now = Date.now()) => !cache || !(now - (cache.checkedAt || 0) < CHECK_INTERVAL_MS);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.8.40",
+	"version": "0.8.42",
 	"description": "Give any AI agent a public A2A (Agent2Agent) endpoint: a Cloudflare Worker, a wake webhook, or scheduled checks",
 	"type": "module",
 	"bin": {

package/worker/cloudflare.config.ts

@@ -28,7 +28,7 @@ const plain: Record<string, string> = {
 	PROVIDER_ORGANIZATION: v("A2A_PROVIDER_ORGANIZATION"),
 	PROVIDER_URL: v("A2A_PROVIDER_URL"),
 	DOCUMENTATION_URL: v("A2A_DOCUMENTATION_URL"),
-	WAKE_PRESET: v("WAKE_PRESET") || "generic", // grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
+	WAKE_PRESET: v("WAKE_PRESET") || "generic", // grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | mausbot | generic
 	WAKE_AGENT_ID: v("WAKE_AGENT_ID"), // openclaw presets (default "main")
 	WAKE_KEY_HEADER: v("WAKE_KEY_HEADER"), // generic preset (default "authorization")
 	WAKE_KEY_PREFIX: e.WAKE_KEY_PREFIX ?? "", // generic preset; unset = "Bearer "

package/worker/src/index.ts

@@ -7,7 +7,7 @@
 import { VERSION } from "./version.ts";
 import * as A from "./a2a.ts";
 import * as F from "./facade.ts";
-import { renderWake, redact, cloudflareErrorHint, wakeUrlIsTunnelHost, defaultBusySeconds, defaultDebounceSeconds, defaultMaxPerHour, type WakeConfig, type WakeEvent } from "./wake.ts";
+import { renderWake, mausbotConfigProblem, redact, cloudflareErrorHint, wakeUrlIsTunnelHost, defaultBusySeconds, defaultDebounceSeconds, defaultMaxPerHour, type WakeConfig, type WakeEvent } from "./wake.ts";
 import { fetchCheckedPeer, fetchCheckedWake } from "./wake-target.ts";
 import { withDeadline } from "./deadline.ts";
 import * as Addr from "./address.ts";
@@ -397,7 +397,8 @@ async function requeueWake(ctx: TenantContext, ectx: ExecutionContext, payload:
 }
 
 async function wake(ctx: TenantContext, ectx: ExecutionContext, contextId: string, taskId: string, from: string, preview: string, kind = "inbound") {
-	const payload: Json = { contextId, taskId, taskIds: [taskId], from, preview: preview.slice(0, 300), kind };
+	const payload: Json = { contextId, taskId, taskIds: [taskId], from, preview: preview.slice(0, 300), kind,
+		...(preset(ctx) === "mausbot" ? { deliveryId: crypto.randomUUID() } : {}) };
 	const now = Date.now(), deb = debounceMs(ctx);
 	let row: Json = await loadWake(ctx, contextId, from);
 	// A pre-peer row (peer '') is this conversation when it names this peer, or names nobody yet.
@@ -833,7 +834,7 @@ const rpcSend: Rpc = async (params, label, version, ctx, ectx) => {
 	const directReply = directReplyParams(params);
 	const conf = params.configuration || {};
 	const push = conf.taskPushNotificationConfig || conf.pushNotificationConfig;
-	const pushCfg = push ? normPushCfg(push, version) : null;
+	const pushCfg = push ? { ...normPushCfg(push, version), _role: "message push" } : null;
 	let task: Json = null;
 	if (msg.taskId) {
 		task = await ownedTask(ctx, msg.taskId, label);
@@ -895,7 +896,7 @@ const rpcPushSet: Rpc = async (p, label, version, ctx) => {
 	else if (p.config && typeof p.config === "object") { taskId = p.taskId || String(p.parent || "").split("/").pop(); cfg = p.config; }
 	else { taskId = p.taskId; cfg = { id: p.id, url: p.url, token: p.token, authentication: p.authentication }; }
 	const t = await ownedTask(ctx, taskId, label);
-	const c = normPushCfg(cfg, version);
+	const c = { ...normPushCfg(cfg, version), _role: "task push config" };
 	t._push = [...t._push.filter((x: Json) => x.id !== c.id), c];
 	await saveTaskStmt(ctx, t).run();
 	return pubCfg(t.id, c, version);
@@ -1236,8 +1237,8 @@ async function sendPush(ctx: TenantContext, ectx: ExecutionContext, task: Json,
 	try {
 		const r = await doFetch(ctx, ectx, cfg.url, { method: "POST", headers, body: JSON.stringify(body), signal });
 		return [r.status >= 200 && r.status < 300, `HTTP ${r.status}`];
-	} catch (e) {
-		return [false, String(e).slice(0, 200)];
+	} catch {
+		return [false, "push request failed"];
 	}
 }
 
@@ -1249,8 +1250,9 @@ async function notifyPeer(ctx: TenantContext, ectx: ExecutionContext, t: Json, s
 			? await withDeadline(7000, (step) => sendPush(ctx, ectx, t, cfg, step), signal)
 			: await sendPush(ctx, ectx, t, cfg);
 		signal?.throwIfAborted();
-		results.push({ url: cfg.url, ok, info });
-		await histStmt(ctx, t.contextId, { dir: "out", peer: t._peer, taskId: t.id, event: "push", state: t.status.state, text: `${ok ? "ok" : "FAILED"} ${info}` }).run();
+		const result = { role: cfg._role === "message push" ? "message push" : "task push config", host: new URL(cfg.url).host, fingerprint: await A.fingerprint(cfg.url), ok, info };
+		results.push(result);
+		await histStmt(ctx, t.contextId, { dir: "out", peer: t._peer, taskId: t.id, event: "push", state: t.status.state, text: `${result.role} ${result.host} [${result.fingerprint}]: ${ok ? "ok" : "FAILED"} ${info}`, data: result }).run();
 	}
 	return results;
 }
@@ -1263,6 +1265,7 @@ type ReplyDelivery = {
 	target?: { alias?: string; host: string };
 	httpStatus?: number;
 	detail: string;
+	push?: Json[];
 };
 
 const DIRECT_REPLY_META = "a2a.exposed/reply-delivery";
@@ -1694,12 +1697,13 @@ async function deliverReplyMessage(ctx: TenantContext, ectx: ExecutionContext, t
 	if (task._push?.length) {
 		const pushed = await notifyPeer(ctx, ectx, task, signal);
 		const failed = pushed.find((x: Json) => !x.ok);
-		const target = safeTarget(undefined, String((failed || pushed[0])?.url || ""));
+		const host = (failed || pushed[0])?.host;
+		const target = host ? { host } : undefined;
 		const info = String((failed || pushed[0])?.info || "");
 		const http = /^HTTP (\d{3})$/.exec(info);
 		const httpStatus = http && http[0] === info ? Number(http[1]) : undefined;
 		return {
-			status: failed ? "delivery-failed" : "delivered", method: "push", taskId: task.id, state,
+			status: failed ? "delivery-failed" : "delivered", method: "push", taskId: task.id, state, push: pushed,
 			...(target ? { target } : {}), ...(httpStatus !== undefined && httpStatus >= 100 && httpStatus <= 599 ? { httpStatus } : {}),
 			detail: failed ? "A task push failed; the reply remains stored on the task." : "Delivered as the task's existing push update.",
 		};
@@ -2122,7 +2126,7 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 		if (seg[2] === "working" && m === "POST") {
 			if (A.TERMINAL.has(t.status.state)) return json({ error: `task is already ${t.status.state}` }, 409);
 			t.status = { state: "working", timestamp: A.nowIso() };
-			await ctx.DB.batch([saveTaskStmt(ctx, t), histStmt(ctx, t.contextId, { dir: "local", taskId: t.id, event: "state", state: "working" })]);
+			await ctx.DB.batch([saveTaskStmt(ctx, t), histStmt(ctx, t.contextId, { dir: "local", peer: t._peer, taskId: t.id, event: "state", state: "working" })]);
 			await ackPendingWakes(ctx, [{ taskId: t.id, contextId: t.contextId }]);
 			return json({ task: ownerTaskView(t), push: await notifyPeer(ctx, ectx, t) });
 		}
@@ -2163,11 +2167,14 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 				if (raced?.result_json) return json({ task: ownerTaskView(await loadTask(ctx, t.id)), delivery: JSON.parse(raced.result_json), idempotent: true });
 				return json({ error: "this reply is already being delivered; retry to read its result" }, 409);
 			}
+			const forced = !!b.force && A.TERMINAL.has(t.status.state);
+			const previousState = t.status.state;
 			if (state === "completed" || b.artifact) t.artifacts.push({ artifactId: A.newId(), name: b.artifactName || "response", parts: [{ kind: "text", text: b.text }] });
 			t.history.push(msg);
 			t.status = { state, timestamp: now, message: msg };
 			await ctx.DB.batch([saveTaskStmt(ctx, t), msgStmt(ctx, t, msg),
-				histStmt(ctx, t.contextId, { dir: "out", peer: t._peer, taskId: t.id, role: "agent", state, text: b.text })]);
+				histStmt(ctx, t.contextId, { dir: "out", peer: t._peer, taskId: t.id, role: "agent", state, text: b.text,
+					...(forced ? { event: "forced", data: { forced: true, previousState, state } } : {}) })]);
 			await ackPendingWakes(ctx, [{ taskId: t.id, contextId: t.contextId }]);
 			let delivery: ReplyDelivery;
 			try { delivery = await withDeadline(18000, (signal) => deliverReplyMessage(ctx, ectx, t, msg, state, b.text, signal)); }
@@ -2191,7 +2198,13 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 		if (fromFilter !== null && !PEER_FILTER.test(fromFilter)) return json({ error: "from is invalid" }, 400);
 		// Without `from`, rows for every peer that owns this context id (a task or an outbound task), plus local notes.
 		// With `from`, one peer's rows only, so another peer's conversation is not in this read.
-		const rows = await ctx.DB.prepare(fromFilter ? `SELECT * FROM (
+		const rows = await ctx.DB.prepare(`SELECT h.*,
+			(SELECT status_json FROM tasks WHERE id = h.task_id AND context_id = h.context_id
+			 AND (h.peer IS NULL OR h.peer = '' OR peer = h.peer)) AS current_status_json,
+			(SELECT json_object('state', state, 'timestamp', ts) FROM history latest
+			 WHERE latest.context_id = h.context_id AND latest.task_id = h.task_id AND latest.peer IS h.peer
+			 AND latest.state IS NOT NULL ORDER BY latest.seq DESC LIMIT 1) AS current_history_json
+			FROM (${fromFilter ? `SELECT * FROM (
 			SELECT * FROM history WHERE context_id = ? AND (
 				peer = ?
 				OR (
@@ -2212,10 +2225,12 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 					AND NOT EXISTS (SELECT 1 FROM outbound WHERE context_id = ?)
 				)
 			) ORDER BY seq DESC LIMIT ?
-		) ORDER BY seq`).bind(...(fromFilter
+		) ORDER BY seq`} ) h ORDER BY h.seq`).bind(...(fromFilter
 			? [seg[1], fromFilter, seg[1], fromFilter, seg[1], fromFilter, n]
 			: [seg[1], seg[1], seg[1], seg[1], seg[1], n])).all();
-		return json((rows.results as Json[]).map((r) => ({ ...r, data: r.data_json ? JSON.parse(r.data_json) : undefined, data_json: undefined })));
+		return json((rows.results as Json[]).map((r) => ({ ...r, data: r.data_json ? JSON.parse(r.data_json) : undefined, data_json: undefined,
+			currentState: r.current_status_json ? (({ state, timestamp }) => ({ state, timestamp }))(JSON.parse(r.current_status_json))
+				: r.current_history_json ? JSON.parse(r.current_history_json) : undefined, current_status_json: undefined, current_history_json: undefined })));
 	}
 	if (seg[0] === "history" && !seg[1] && m === "POST") {
 		const b = await body();
@@ -2408,6 +2423,8 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 			preview: "Example message preview", kind: "test", publicUrl: ctx.PUBLIC_URL };
 		if (preset(ctx) === "openbot" && !ctx.WAKE_HMAC_SECRET?.trim())
 			return json({ error: "OpenBot requires WAKE_HMAC_SECRET from the routine settings" }, 400);
+		const mausbotProblem = mausbotConfigProblem(wakeConfig(ctx));
+		if (mausbotProblem) return json({ error: mausbotProblem }, 400);
 		const req = await renderWake(wakeConfig(ctx), ev, { requestId: "preview" });
 		return json({ preset: preset(ctx), configured: !!req, debounceSeconds: debounceMs(ctx) / 1000, busySeconds: busySecondsReported(ctx, ectx), maxPerHour: maxPerHour(ctx),
 			hasKey: !!ctx.WAKE_WEBHOOK_KEY, hasHmacSecret: !!ctx.WAKE_HMAC_SECRET,

package/worker/src/mcp.ts

@@ -346,6 +346,10 @@ export const TOOLS: { name: string; title: string; description: string; inputSch
 			status: str("Delivery outcome", { enum: ["delivered", "stored-only", "delivery-failed"] }),
 			method: str("Path used", { enum: ["push", "a2a-message", "stored"] }),
 			target: { type: "object", properties: { alias: str("Paired peer alias"), host: str("Destination host") }, required: ["host"], additionalProperties: false },
+			push: { type: "array", items: { type: "object", properties: {
+				role: str("Callback origin", { enum: ["task push config", "message push"] }), host: str("Callback host"),
+				fingerprint: str("First 12 hex characters of SHA-256 of the callback URL"), ok: { type: "boolean" }, info: str("Safe push result"),
+			}, required: ["role", "host", "fingerprint", "ok", "info"], additionalProperties: false } },
 			httpStatus: { type: "integer", minimum: 100, maximum: 599 }, detail: str("Safe delivery summary"),
 		}, required: ["taskId", "state", "status", "method", "detail"], additionalProperties: false } },
 	{ name: "send", title: "Send to peer", annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },

package/worker/src/version.ts

@@ -1,2 +1,2 @@
 /** Inbox build. Keep this equal to `version` in cli/package.json. */
-export const VERSION = "0.8.40";
+export const VERSION = "0.8.42";

package/worker/src/wake.ts

@@ -10,6 +10,7 @@ export type WakeEvent = {
 	preview: string;
 	kind: string; // "inbound" | "outbound_update" | "test" | "pairing_request"
 	publicUrl: string;
+	deliveryId?: string; // MausBot wake identity, retained by Retry-After retries
 	pairing?: PairingInfo; // kind "pairing_request"
 };
 
@@ -48,7 +49,7 @@ export type WakeConfig = {
 
 export type WakeRequest = { url: string; method: "POST"; headers: Record<string, string>; body: string };
 
-export const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "generic"] as const;
+export const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "mausbot", "generic"] as const;
 
 /** Default debounce window per preset (seconds), used when WAKE_DEBOUNCE_SECONDS is unset. */
 export function defaultDebounceSeconds(preset: string): number {
@@ -190,9 +191,24 @@ async function hermesSign(headers: Record<string, string>, secret: string, body:
 	headers["X-Webhook-Signature-V2"] = await hmacSha256Hex(secret, `${ts}.${body}`);
 }
 
-/** Build the HTTP request, return null without a URL, or throw when OpenBot signing is missing. */
+/** MausBot uses header auth, never a capability URL containing a secret. */
+export function mausbotConfigProblem(cfg: WakeConfig): string {
+	if (cfg.preset !== "mausbot" || !cfg.url) return "";
+	try {
+		const url = new URL(cfg.url);
+		if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || !/^\/hooks\/wh_[A-Za-z0-9_-]+$/.test(url.pathname))
+			return "MausBot requires an HTTPS /hooks/<endpointId> URL without credentials, query or fragment; use WAKE_WEBHOOK_KEY for Bearer auth";
+	} catch { return "MausBot requires an HTTPS /hooks/<endpointId> URL"; }
+	if (!cfg.key?.trim() || cfg.key.length > 4096 || /[\u0000-\u001f\u007f]/.test(cfg.key))
+		return "MausBot requires WAKE_WEBHOOK_KEY from protected environment/secret storage";
+	return "";
+}
+
+/** Build the HTTP request, return null without a URL, or throw when required preset auth/config is missing. */
 export async function renderWake(cfg: WakeConfig, ev: WakeEvent, opts: { nowMs?: number; requestId?: string } = {}): Promise<WakeRequest | null> {
 	if (!cfg.url) return null;
+	const mausbotProblem = mausbotConfigProblem(cfg);
+	if (mausbotProblem) throw new Error(mausbotProblem);
 	if (cfg.preset === "openbot" && !cfg.hmacSecret?.trim()) throw new Error("OpenBot requires WAKE_HMAC_SECRET from the routine settings");
 	const cli = cfg.cliCommand || DEFAULT_CLI;
 	const nowMs = opts.nowMs ?? Date.now();
@@ -221,6 +237,12 @@ export async function renderWake(cfg: WakeConfig, ev: WakeEvent, opts: { nowMs?:
 			// `name` is the hook name OpenClaw filters match. It stays "A2A inbox". The wake text itself starts with "A2A endpoint:".
 			body = JSON.stringify({ message: wakeSummary(ev, cli), name: "A2A inbox", agentId: cfg.agentId || "main", sessionMode: "isolated", deliver: false });
 			break;
+		case "mausbot":
+			bearer();
+			// A task can wake more than once. Retry the same wake identity, not every update on that task.
+			headers["idempotency-key"] = `${ev.taskId}:${ev.deliveryId || requestId}`;
+			body = JSON.stringify(wakePayload(ev, cli));
+			break;
 		case "openbot": {
 			const ts = String(Math.floor(nowMs / 1000));
 			headers["x-openbot-timestamp"] = ts;

package/worker/test/push-config.test.ts

@@ -159,3 +159,70 @@ test("1.0 list pages configs and 0.3 delete returns null", async (t) => {
 	hides(del.text, token);
 	assert.equal(s.logs.some((line) => line.includes(token)), false);
 });
+
+test("push results identify callbacks without URLs, and forced replies preserve transitions", async (t) => {
+	const s = setup();
+	t.after(s.restore);
+	const originalFetch = globalThis.fetch;
+	t.after(() => { globalThis.fetch = originalFetch; });
+	const attempted: string[] = [];
+	globalThis.fetch = (async (url: any) => {
+		attempted.push(String(url));
+		return new Response(null, { status: String(url).includes("first") ? 401 : 200 });
+	}) as typeof fetch;
+	const ada = (await s.owner("POST", "/owner/peers", { label: "ada" })).token;
+	const first = "https://hooks.example.net/private/first?token=first-secret";
+	const second = "https://hooks.example.net/private/second?token=second-secret";
+	const sent = await s.call(ada, "message/send", {
+		message: { kind: "message", role: "user", messageId: crypto.randomUUID(), parts: [{ kind: "text", text: "hello" }] },
+		configuration: { pushNotificationConfig: { id: "message", url: first } },
+	});
+	const { id: taskId, contextId } = sent.data.result;
+	await s.call(ada, "tasks/pushNotificationConfig/set", { taskId, pushNotificationConfig: { id: "task", url: second } });
+	const working = await s.owner("POST", `/owner/tasks/${taskId}/working`, {});
+	assert.deepEqual(working.push.map((r: any) => [r.role, r.host, r.ok, r.info]), [
+		["message push", "hooks.example.net", false, "HTTP 401"], ["task push config", "hooks.example.net", true, "HTTP 200"],
+	]);
+	assert.deepEqual(working.push.map((r: any) => r.fingerprint), [(await sha256(first)).slice(0, 12), (await sha256(second)).slice(0, 12)]);
+	assert.doesNotMatch(JSON.stringify(working.push), /token=|first-secret|second-secret|private|https:/);
+	const done = await s.owner("POST", `/owner/tasks/${taskId}/reply`, { text: "done", state: "completed" });
+	assert.deepEqual(done.delivery.push, working.push);
+	assert.equal(done.task.status.state, "completed");
+	const blocked = await s.owner("POST", `/owner/tasks/${taskId}/reply`, { text: "question", state: "input-required" });
+	assert.match(blocked.error, /already completed/);
+	const forced = await s.owner("POST", `/owner/tasks/${taskId}/reply`, { text: "question", state: "input-required", force: true });
+	assert.equal(forced.task.status.state, "input-required");
+	const history = await s.owner("GET", `/owner/history/${contextId}?from=ada`);
+	const transitions = history.filter((r: any) => r.event === "forced");
+	assert.equal(transitions.length, 1);
+	assert.deepEqual(transitions[0].data, { forced: true, previousState: "completed", state: "input-required" });
+	assert.ok(history.every((r: any) => r.currentState.state === "input-required"));
+	assert.deepEqual(history.at(-1).currentState, { state: "input-required", timestamp: forced.task.status.timestamp });
+	assert.doesNotMatch(JSON.stringify(history), /first-secret|second-secret|private/);
+	const count = attempted.length;
+	const retry = await s.owner("POST", `/owner/tasks/${taskId}/reply`, { text: "question", state: "input-required", force: true });
+	assert.equal(retry.idempotent, true);
+	assert.equal(attempted.length, count);
+	const after = await s.owner("GET", `/owner/history/${contextId}?n=1&from=ada`);
+	assert.deepEqual(after[0].currentState, history.at(-1).currentState);
+	globalThis.fetch = (async () => { throw new Error(`failed ${first}`); }) as typeof fetch;
+	const failed = await s.owner("POST", `/owner/tasks/${taskId}/reply`, { text: "final", state: "completed" });
+	assert.doesNotMatch(JSON.stringify(failed.delivery), /first-secret|second-secret|private/);
+	assert.equal(failed.delivery.push[0].info, "push request failed");
+});
+
+test("limited outbound history reports the latest state for that peer only", async (t) => {
+	const s = setup();
+	t.after(s.restore);
+	const contextId = "outbound-history";
+	const taskId = "remote-task";
+	await s.owner("POST", "/owner/history", { contextId, taskId, peer: "ada", state: "working", ts: "2026-11-07T01:00:00.000Z" });
+	await s.owner("POST", "/owner/history", { contextId, taskId, peer: "bob", state: "failed", ts: "2026-11-07T01:01:00.000Z" });
+	await s.owner("POST", "/owner/history", { contextId, taskId, peer: "ada", event: "note", text: "latest note without a state" });
+	const rows = await s.owner("GET", `/owner/history/${contextId}?from=ada&n=1`);
+	assert.equal(rows.length, 1);
+	assert.equal(rows[0].event, "note");
+	assert.deepEqual(rows[0].currentState, { state: "working", timestamp: "2026-11-07T01:00:00.000Z" });
+	assert.equal(rows[0].current_history_json, undefined);
+	assert.equal(rows[0].current_status_json, undefined);
+});