a2a-exposed 0.8.39 → 0.8.41

package/lib/deploy.mjs

@@ -33,7 +33,9 @@ export const CLAUDE_CODE_NOTE = [
 	"  Then open the new session from the routine's runs and confirm it ran the inbox command without errors.",
 ].join("\n");
 
-const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "generic"];
+export const MAUSBOT_NOTE = "note (mausbot): the first test may only capture a verification sample. Verify and enable the webhook in MausBot, then run wake test again. HTTP 202 proves acceptance; check that the bot reads the inbox and replies.";
+
+const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "mausbot", "generic"];
 // WAKE_ACCESS_*: Cloudflare Access service token for a wake URL behind Access (set by `tunnel create`, or exported
 // by hand for your own Access-protected endpoint)
 export const WAKE_SECRETS = ["WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "WAKE_ACCESS_CLIENT_ID", "WAKE_ACCESS_CLIENT_SECRET"];
@@ -203,7 +205,7 @@ export function deploySecretsFromEnv() {
 
 const csv = (s) => String(s || "").split(",").map((x) => x.trim()).filter(Boolean);
 
-/** Save init/deploy flags. Returns { from, to } when the public URL switches between a custom domain and
+/** Validate init/deploy flags, check Node before writing, then save them. Returns { from, to } when the public URL switches between a custom domain and
  *  workers.dev (or to another custom domain), so the caller can tell the user what changed. */
 function applyFlags(o) {
 	const upd = {};
@@ -273,6 +275,8 @@ function applyFlags(o) {
 	if (upd.A2A_AGENT_SKILLS) {
 		try { if (!Array.isArray(JSON.parse(upd.A2A_AGENT_SKILLS))) throw 0; } catch { die("--agent-skills must be a JSON array of A2A AgentSkill objects"); }
 	}
+	// Report local input errors before Node guidance, but never save or deploy on unsupported Node.
+	checkNode();
 	C.saveConfig(upd);
 	return switched;
 }
@@ -562,7 +566,6 @@ function deployedBase() {
 }
 
 export async function init(o) {
-	checkNode();
 	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
 	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
@@ -702,7 +705,6 @@ export async function upstreamTokenCheck(o, { upstreamChanged = false } = {}) {
 }
 
 export async function deploy(o) {
-	checkNode();
 	if (!C.get("A2A_D1_ID")) die(`no saved deployment; run \`${CLI} init\` first`);
 	// init saves A2A_WORKER_NAME before it creates the D1 database, so a saved D1 without a name is a hand-edited config:
 	// refuse rather than guess, so a redeploy never creates a second Worker next to the one this config deployed.
@@ -744,7 +746,35 @@ function guardTunnelUrl() {
 	if (host !== th) die(`this deployment wakes through the tunnel https://${th} (tunnel create); unset WAKE_WEBHOOK_URL, or run \`${CLI} tunnel rm\` first`);
 }
 
+/** Delivery diagnostic only: a test wake has no task or execution receipt. */
+export async function checkWake(o, { request = fetch, callOwner = owner } = {}) {
+	if (C.get("WAKE_PRESET") !== "hermes") die("wake check requires the hermes preset; inspect wake preview first, then use wake set --preset hermes");
+	const local = o["local-url"] || `${C.get("A2A_TUNNEL_ORIGIN", "http://127.0.0.1:8644")}${C.get("A2A_TUNNEL_PATH", "/webhooks/a2a-wake")}`;
+	let url;
+	try { url = new URL(local); } catch { die("--local-url must be a loopback HTTP(S) webhook URL"); }
+	if (!["http:", "https:"].includes(url.protocol) || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) || url.username || url.password || url.search || url.hash)
+		die("--local-url must be a loopback HTTP(S) webhook URL without credentials, query or fragment");
+	let status;
+	try {
+		const response = await request(url, { method: "POST", headers: { "content-type": "application/json", "user-agent": "a2a-exposed-cli" },
+			body: JSON.stringify({ event_type: "a2a_wake", kind: "test" }), redirect: "manual", signal: AbortSignal.timeout(10_000) });
+		status = response.status;
+		await response.body?.cancel();
+	} catch { die("unsigned local check could not reach the webhook; start the Hermes gateway and check --local-url"); }
+	const result = { unsigned: { status, refused: status === 401 || status === 403 }, signed: null, receiverExecution: "not-verified" };
+	if (result.unsigned.refused) {
+		const signed = await callOwner("POST", "/owner/wake/test", {});
+		result.signed = { status: Number.isInteger(signed.status) ? signed.status : null, delivered: signed.configured !== false && Number.isInteger(signed.status) && signed.status >= 200 && signed.status < 300 };
+	}
+	console.log(JSON.stringify(result, null, 2));
+	if (!result.unsigned.refused || !result.signed?.delivered) {
+		process.exitCode = 1;
+		console.error(!result.unsigned.refused ? "unsigned local POST must return 401 or 403; check the route's HMAC secret. Signed delivery was skipped." : "signed Worker delivery failed; run wake preview and tunnel status, then retry after secrets propagate");
+	} else console.error("delivery checks passed; receiver execution is not verified. Test wakes create no inbox task; inspect the Hermes job output for execution.");
+}
+
 export async function wake(sub, o) {
+	if (sub === "check") return checkWake(o);
 	if (sub === "fingerprint") {
 		const fp = localFingerprints();
 		if (!Object.values(fp).some(Boolean)) die(`no ${WAKE_SECRETS.join(" / ")} in the environment`);
@@ -769,6 +799,7 @@ export async function wake(sub, o) {
 		console.log(JSON.stringify(r, null, 2));
 		if (!(r.status >= 200 && r.status < 300)) process.exitCode = 1;
 		else if (C.get("WAKE_PRESET") === "claude-code") console.error(CLAUDE_CODE_NOTE);
+		if (r.preset === "mausbot" || C.get("WAKE_PRESET") === "mausbot") console.error(MAUSBOT_NOTE);
 		return;
 	}
 	if (sub === "set") {
@@ -779,6 +810,7 @@ export async function wake(sub, o) {
 		await deploy(o); // wake set = save settings + upload secrets + redeploy, in one step
 		console.error(`wake settings deployed. Next: ${CLI} wake preview, then ${CLI} wake test`);
 		if (C.get("WAKE_PRESET") === "claude-code") console.error(CLAUDE_CODE_NOTE);
+		if (C.get("WAKE_PRESET") === "mausbot") console.error(MAUSBOT_NOTE);
 		return;
 	}
 	if (sub === "unset") {
@@ -796,5 +828,5 @@ export async function wake(sub, o) {
 		if (problems.length) die(`could not remove wake secrets:\n  ${problems.join("\n  ")}`);
 		return console.error("wake secrets removed (wake is now a no-op; use polling)");
 	}
-	die("usage: wake set|unset|test|preview|fingerprint");
+	die("usage: wake set|unset|test|check|preview|fingerprint");
 }

package/lib/hosted.mjs

@@ -4,7 +4,7 @@ import * as C from "./config.mjs";
 import { controlOrigin, deviceLogin } from "./account.mjs";
 import { CliError, upstreamUrlProblem } from "./a2a.mjs";
 
-export const SETUP_SCOPES = ["agents:read", "agents:create", "agents:owner-token", "wake:write", "wake:test"];
+export const SETUP_SCOPES = ["agents:read", "agents:create", "agents:owner-token", "wake:write", "wake:test", "upstream:write", "upstream:test"];
 const SETUP_UNSUPPORTED = "This service does not expose scoped hosted setup capabilities. Check the --control-url service origin. Use the service dashboard to create an agent and configure Wake settings, or hosted MCP create_agent/set_wake with human confirmation and secret entry. Do not run init or deploy to repair a hosted address; no setup approval was requested.";
 const NEXT = "Run hosted capabilities --json to list scopes and presets; login --machine NAME --scopes SCOPES to approve setup.";
 const fail = (code, next) => { const error = new CliError(next); error.result = { ok: false, code, next }; throw error; };
@@ -36,17 +36,30 @@ function originFor(o = {}) {
 async function request(origin, path, { token = "", method = "GET", body, fetchImpl = fetch } = {}) {
 	let response, data;
 	const discovery = method === "GET" && path === "/api/v1/setup/capabilities";
+	const wakeRequest = /^\/api\/v1\/agents\/[^/]+\/wake(?:\/test)?$/.test(path);
 	try {
 		response = await fetchImpl(`${origin}${path}`, {
 			method, redirect: "error", signal: AbortSignal.timeout(30_000),
 			headers: { accept: "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}), ...(body === undefined ? {} : { "content-type": "application/json" }) },
 			...(body === undefined ? {} : { body: JSON.stringify(body) }),
 		});
-		if (!(discovery && response.status === 404)) data = await response.json();
+		if (!(discovery && response.status === 404)) {
+			try { data = await response.json(); }
+			catch (error) {
+				if (wakeRequest && [401, 403, 404].includes(response.status)) data = {};
+				else throw error;
+			}
+		}
 	} catch { fail("unavailable", "Hosted setup did not answer with JSON. Check the service and try again. Do not repeat a create request until hosted list confirms its result."); }
 	if (discovery && response.status === 404) fail("unsupported", SETUP_UNSUPPORTED);
 	if (!data || typeof data !== "object" || Array.isArray(data)) fail("invalid_response", "The hosted service returned an invalid setup response.");
 	if (!response.ok) {
+		if (wakeRequest && [401, 403, 404].includes(response.status)) {
+			const code = ["invalid_grant", "insufficient_scope"].includes(data.error) ? data.error : `http_${response.status}`;
+			fail(code, response.status === 404
+				? "This service does not expose the hosted wake API for this agent. Check --control-url and the selected agent; use dashboard Wake settings or hosted MCP set_wake. No settings were changed."
+				: "Hosted wake access was refused. Check that A2A_BASE_URL and A2A_OWNER_TOKEN belong to the same agent and service, or approve the required setup scopes. Use dashboard Wake settings or hosted MCP set_wake if needed. No settings were changed.");
+		}
 		if (response.status === 429 && data.error === "too_many_references") {
 			const seconds = retryAfter(response, data);
 			const next = seconds === undefined
@@ -62,6 +75,7 @@ async function request(origin, path, { token = "", method = "GET", body, fetchIm
 		const code = known.includes(data.error) ? data.error : `http_${response.status}`;
 		const next = code === "taken" || code === "reserved_name" ? "Choose another --name using hosted names --name NAME --json before creating."
 			: code === "limit" ? "The account is at its agent limit. Read hosted capacity --json and review account plans."
+			: code === "conflict" && path.includes("/upstream") ? "Upstream settings changed. Run hosted upstream preview --agent NAME --json, then repeat with its explicit --version."
 			: code === "conflict" ? "Wake settings changed. Run wake preview --json, then test the draft again."
 			: code === "invalid_reference" ? "The wake reference was already used, expired or does not match this draft. Run wake prepare again with the draft inputs and a new --reference-file."
 			: code === "invalid_grant" || code === "insufficient_scope" ? NEXT
@@ -74,7 +88,7 @@ async function request(origin, path, { token = "", method = "GET", body, fetchIm
 export async function capabilities(o = {}) {
 	const data = await request(originFor(o), "/api/v1/setup/capabilities");
 	if (!Array.isArray(data.scopes) || !Array.isArray(data.wake?.presets)) fail("unsupported", SETUP_UNSUPPORTED);
-	return { ok: true, code: "capabilities", next: "Select explicit scopes and a wake preset from this listing.", scopes: data.scopes.filter(s => SETUP_SCOPES.includes(s)), presets: data.wake.presets.filter(s => /^[a-z-]+$/.test(s)), preflight: data.preflight === true, secret_reference: data.wake.secret_reference === true, wake_removal: data.wake.removal === true, secure_link_create: data.wake.secure_link_create === true };
+	return { ok: true, code: "capabilities", next: "Select explicit scopes and a wake preset from this listing.", scopes: data.scopes.filter(s => SETUP_SCOPES.includes(s)), presets: data.wake.presets.filter(s => /^[a-z-]+$/.test(s)), upstream: data.upstream?.configuration === true && data.upstream?.verify === true, preflight: data.preflight === true, secret_reference: data.wake.secret_reference === true, wake_removal: data.wake.removal === true, secure_link_create: data.wake.secure_link_create === true };
 }
 
 export async function login(o = {}) {
@@ -197,8 +211,6 @@ export async function status(o = {}) {
 
 export async function wake(sub, o = {}) {
 	if (!["preview", "test", "set", "prepare", "remove", "unset"].includes(sub)) fail("usage", "Use wake preview|test|set|prepare|remove. List presets with hosted capabilities --json.");
-	if (sub === "set" && C.deploymentKind() === "hosted" && !o.agent)
-		fail("hosted_config", "This is a hosted config. Use dashboard Wake settings or hosted MCP set_wake; the human enters wake secrets on the confirmation page. For scoped CLI setup, run hosted capabilities --json, then hosted list --json to select an explicit --agent NAME before wake set --agent NAME --url URL --preset P --json. No wake settings were changed.");
 	const removing = sub === "remove" || sub === "unset";
  const preparingRemoval = sub === "prepare" && o.clear === true;
  if (o.clear && !preparingRemoval) fail("usage", "Use wake prepare --clear for an MCP removal reference, or wake remove --version N. Run wake preview --json to list the current version.");
@@ -225,7 +237,7 @@ export async function wake(sub, o = {}) {
 	const { origin, token, name } = wakeCredential(o, sub !== "prepare" && !o["reference-file"] && !o["reference-env"]), path = `/api/v1/agents/${encodeURIComponent(name)}/wake`;
 	const current = await request(origin, path, { token });
 	if (!Number.isSafeInteger(current.version)) fail("invalid_response", "The service did not return a valid wake version. Saved settings were not changed.");
-	if (sub === "preview") return { ok: true, code: "preview", next: "Test an explicit draft before saving.", version: current.version, preset: current.preset, configured: Boolean(current.url), key_header: ["hermes", "openbot"].includes(current.preset) ? "" : ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent"].includes(current.preset) ? "Authorization" : current.keyHeader || "Authorization", url: previewUrl(current.url) };
+	if (sub === "preview") return { ok: true, code: "preview", next: "Test an explicit draft before saving.", version: current.version, preset: current.preset, configured: Boolean(current.url), key_header: ["hermes", "openbot"].includes(current.preset) ? "" : ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "mausbot"].includes(current.preset) ? "Authorization" : current.keyHeader || "Authorization", url: previewUrl(current.url) };
  if (removing || preparingRemoval) {
   const version = Number(o.version);
   if (version !== current.version) fail("conflict", "Wake settings changed. Run wake preview --agent NAME --json, review them, then repeat removal with its explicit --version.");
@@ -248,6 +260,7 @@ export async function wake(sub, o = {}) {
 	}
 	const url = o.url || process.env.WAKE_WEBHOOK_URL || current.url;
 	const preset = o.preset || current.preset || "generic";
+	if (!url) fail("wake_unconfigured", "No hosted wake URL is configured. Run hosted capabilities --json to list presets, then wake set --preset P with WAKE_WEBHOOK_URL and protected wake credentials. Alternatively use dashboard Wake settings or hosted MCP set_wake; no settings were changed.");
 	const problem = upstreamUrlProblem(url);
 	if (problem) fail("url", "Pass --url with a public HTTPS webhook URL without credentials. Use polling if no public webhook is available.");
 	const available = await capabilities({ "control-url": origin });
@@ -283,6 +296,34 @@ export async function wake(sub, o = {}) {
 	return { ok, code, saved: result.saved === true, next: ok ? sub === "set" ? "Check the receiver for the test wake." : "The draft passed. Run wake set with the same inputs to test and save." : `Saved settings were not changed. ${recovery[code] || "Check the receiver, credentials and draft, then test again."}` };
 }
 
+/** Hosted upstream configuration uses only scoped setup or this agent's owner credential. */
+export async function upstream(sub, o = {}) {
+	if (!["preview", "set", "clear", "verify"].includes(sub)) fail("usage", "Use hosted upstream preview|set|clear|verify --agent NAME --json. Select NAME with hosted list --json and scopes with hosted capabilities --json.");
+	const allowed = new Set(["agent", "json", "control-url", ...(sub === "preview" ? [] : ["version"]), ...(sub === "set" ? ["url", "upstream-token-file", "upstream-token-env", "access-client-id-file", "access-client-id-env", "access-client-secret-file", "access-client-secret-env"] : [])]);
+	if (Object.keys(o).some(key => !allowed.has(key))) fail("usage", "Use only the options for hosted upstream preview|set|clear|verify shown in --help; secret inputs belong only to set.");
+	if (sub !== "preview" && (!/^(0|[1-9][0-9]*)$/.test(String(o.version ?? "")) || !Number.isSafeInteger(Number(o.version)))) fail("version", "Pass --version N from hosted upstream preview --agent NAME --json; no version is selected automatically.");
+	let body = { version: Number(o.version) };
+	if (sub === "set") {
+		const url = String(o.url || "");
+		if (!url || upstreamUrlProblem(url)) fail("url", "Pass --url with a public HTTPS A2A address; use hosted upstream clear to remove it.");
+		body = { ...body, url, token: secret(o, "upstream-token", "UPSTREAM_TOKEN"), accessClientId: secret(o, "access-client-id", "UPSTREAM_ACCESS_CLIENT_ID"), accessClientSecret: secret(o, "access-client-secret", "UPSTREAM_ACCESS_CLIENT_SECRET") };
+		if (Boolean(body.accessClientId) !== Boolean(body.accessClientSecret)) fail("access", "Supply both Access credentials through protected files or named environment variables. A new address requires both.");
+	}
+	const { origin, token, name } = wakeCredential(o, true);
+	if (!(await capabilities({ "control-url": origin })).upstream) fail("unsupported", "This service does not expose upstream configuration. Run hosted capabilities --json before selecting an operation.");
+	const path = `/api/v1/agents/${encodeURIComponent(name)}/upstream`;
+	const current = await request(origin, path, { token });
+	if (!Number.isSafeInteger(current.version) || typeof current.configured !== "boolean") fail("invalid_response", "No valid upstream version was returned. Run hosted upstream preview --agent NAME --json before retrying.");
+	if (sub === "preview") return { ok: true, code: "upstream", version: current.version, configured: current.configured, next: "Review this version, then pass --version N to set, clear or verify. Addresses and credentials are never printed." };
+
+	if (Number(o.version) !== current.version) fail("conflict", "Upstream settings changed. Run hosted upstream preview --agent NAME --json, review the version and repeat the explicit operation.");
+
+	const result = await request(origin, sub === "verify" ? `${path}/verify` : path, { token, method: sub === "verify" ? "POST" : sub === "clear" ? "DELETE" : "PUT", body });
+	const reasons = ["reachable", "access_credentials_missing", "access_rejected", "upstream_auth_missing", "upstream_auth_rejected", "tunnel_down", "upstream_unavailable", "network", "unexpected_response", "misconfigured"];
+	const ok = result.ok === true && (sub === "verify" ? result.reason === "reachable" : sub === "clear" ? result.removed === true : result.saved === true);
+	return { ok, code: sub === "verify" ? reasons.includes(result.reason) ? result.reason : "unexpected_response" : ok ? sub === "clear" ? "removed" : "saved" : "failed", ...(Number.isSafeInteger(result.version) ? { version: result.version } : {}), next: sub === "verify" ? ok ? "The saved upstream is reachable. You may pair and send a message." : "Check the connection layer named by code, then verify again. Keep Access and agent authentication enabled." : "Run hosted upstream preview --json, then verify with its explicit version before pairing." };
+}
+
 export async function output(run, o = {}) {
 	try {
 		const result = await run();

package/lib/main.mjs

@@ -25,6 +25,7 @@ Usage: npx -y a2a-exposed@latest <command> [options]
        --help, -h                    print this help
 
 Setup options: --skip-install skips dependency installation when dependencies already exist.
+Local option and missing-deployment errors appear before Node version guidance; deployment still requires Node 22.18+.
 
 Hosted setup:
   hosted capabilities --json   list setup scopes, wake presets and service capabilities
@@ -36,9 +37,19 @@ Hosted setup:
                                 check one name anonymously before device approval; never lists other agents
   hosted capacity --json      read account room with agents:read (or agents:create); reserves nothing
   hosted list --json           list hosted agents with agents:read or agents:create before choosing an agent
+  hosted upstream preview|set|clear|verify --agent NAME --json
+                                list scopes with hosted capabilities and agents with hosted list first
+                                preview returns version; set/clear/verify require --version N
+                                set takes --url URL and --upstream-token-file FILE|--upstream-token-env VAR,
+                                --access-client-id-file FILE|--access-client-id-env VAR and
+                                --access-client-secret-file FILE|--access-client-secret-env VAR
+                                files require mode 600; defaults UPSTREAM_TOKEN/UPSTREAM_ACCESS_CLIENT_ID/
+                                UPSTREAM_ACCESS_CLIENT_SECRET; never pass secret values as arguments
   hosted create --name NAME --json
                                 create and save the owner credential in this config directory;
                                 use a separate --config-dir for each agent
+                                manual fallback: human creates the address in a signed-in dashboard session,
+                                then saves A2A_BASE_URL + A2A_OWNER_TOKEN in protected config or routine secrets
   wake preview|test|set --agent NAME [--url URL] [--preset P] --json
                                 hosted settings: read, test a draft, or test then save it
                                 secrets: --key-file, --key-env, --key-stdin, --hmac-secret-file, --hmac-secret-env,
@@ -133,8 +144,9 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
   wake set [--preset P] [--agent-id A] [--key-header H] [--key-prefix X] [--body-template JSON]
            [--cli-command CMD] [--debounce S] [--busy S] [--max-per-hour N]
                                 self-hosted: save wake settings, upload wake secrets from env, and redeploy
-                                hosted config without --agent: stop with dashboard Wake settings / hosted MCP set_wake guidance
-                                hosted CLI: list hosted capabilities --json and hosted list --json, then select --agent NAME
+                                hosted config: use the saved address and owner token to test then save; no deploy
+                                hosted CLI: list hosted capabilities --json for presets; scoped setup selects --agent from hosted list --json
+                                mausbot: HTTPS /hooks/<endpointId> + WAKE_WEBHOOK_KEY Bearer auth from protected env
                                 openbot: human supplies WAKE_HMAC_SECRET via protected env/secret storage, never chat or argv
                                 the Worker refuses unsigned openbot wakes (a webhook key is not a signing secret)
                                 --busy S        seconds a conversation stays busy after a sent wake.
@@ -152,6 +164,9 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                 30 seconds and run it again
   wake fingerprint              fingerprints (first 12 hex of sha256) of WAKE_* exported in this shell
   wake test                     send a test wake now and print the HTTP status
+                                mausbot: verify and enable the first sample in MausBot, then test again
+  wake check [--local-url URL]   Hermes: require unsigned local 401/403, then Worker test 2xx (delivery only)
+                                Defaults to the saved tunnel origin/path; --json prints both checks
   wake unset                    remove wake secrets (fall back to polling)
                                 handler prompts save autonomous, review-all or escalate mode and owner notices;
                                 see docs/receiving-messages.md for setup and the every 6h webhook fallback
@@ -159,7 +174,7 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
 Tunnel (local-only webhooks: OpenClaw gateway, Hermes, ...; needs Zero Trust/Access and a Cloudflare zone
 anywhere on the account: the A2A endpoint itself can be on workers.dev or a custom hostname)
   tunnel create [--tunnel-zone Z | --tunnel-hostname H] [--tunnel-origin URL] [--tunnel-path /p] [--show-token]
-                [--zero-trust-org TEAM]
+                [--zero-trust-org TEAM] [--preset hermes --hermes-route a2a-wake --hmac-secret-stdin]
                                 named Cloudflare Tunnel + proxied DNS + Access app that admits ONE service token;
                                 the Worker sends that token (CF-Access-Client-Id/Secret) on every wake.
                                 Wake hostname: wake-<word>-<word>-<4 hex>.<zone>, on the A2A endpoint hostname's zone, else the
@@ -171,8 +186,9 @@ anywhere on the account: the A2A endpoint itself can be on workers.dev or a cust
                                 The connector machine needs cloudflared installed
                                 (https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/).
                                 Defaults: openclaw-* -> http://127.0.0.1:18789 /hooks/wake|agent, hermes -> :8644
-                                (pass --tunnel-path /webhooks/<name>). Token -> <config dir>/tunnel-token (chmod 600).
+                                /webhooks/a2a-wake (override with --hermes-route NAME). Token -> <config dir>/tunnel-token (chmod 600).
                                 Worker secrets show up in about 15 to 40 seconds. Wait about 30 seconds and check again
+  tunnel zones [--json]         list available Cloudflare zones before selecting --tunnel-zone
   tunnel status                 tunnel/Access/Worker state + probes (bare request blocked? connector up?)
                                 A network error says DNS may still be propagating; retry in 30 seconds
   tunnel rm                     delete the DNS record, the tunnel, the Access app, and the service token
@@ -350,24 +366,30 @@ Feedback
                                 polling), and hosted or self-hosted. --connection overrides
                                 that detection. Remove tokens from the message and from --logs.
 
-Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
+Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | mausbot | generic
          Clients and how to load them:
          https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#clients
 Config: ${C.CONFIG_FILE}  (override dir with --config-dir DIR or A2A_CONFIG_DIR; env vars override file values)
 Update notice: at most a daily background check of the npm registry; off with A2A_NO_UPDATE_CHECK=1 (or DO_NOT_TRACK=1)`;
 
-const HELP_TUNNEL = `tunnel create|status|rm
+const HELP_TUNNEL = `tunnel create|zones|status|rm
 
 Self-hosted only. Hosted configs use hosted webhook settings or polling. Check status --json first.
 
   tunnel create [--tunnel-zone Z | --tunnel-hostname H] [--tunnel-origin URL] [--tunnel-path /p]
                 [--show-token] [--zero-trust-org TEAM] [--dir DIR | --worker-dir DIR]
+                [--preset hermes --hermes-route a2a-wake --hmac-secret-stdin]
+                                Hermes defaults to :8644/webhooks/a2a-wake. --hermes-route selects another route.
+                                --preset must match the deployed preset (configure with wake set --preset first).
+                                --hmac-secret-stdin reads the existing subscription secret from protected stdin,
+                                never prompts or saves it in config.env. See docs/hermes.md for the receiver recipe.
                                 Named Cloudflare Tunnel, proxied DNS, and an Access app that admits one service token.
                                 The tunnel, the Access app, and the service token are named "a2a-exposed wake <worker>".
                                 The DNS host is wake-<word>-<word>-<4 hex>.<zone> unless --tunnel-hostname is set.
                                 A finished tunnel creates nothing when you run it again. A partial tunnel stops and
                                 asks for tunnel rm. Prints the Access application name and ids, then how to undo it
                                 with tunnel rm. Worker secrets show up in about 15 to 40 seconds. Wait about 30 seconds.
+  tunnel zones [--json]         List active zones before choosing --tunnel-zone; no resource changes.
   tunnel status                 Tunnel, Access, and Worker state, plus two probes.
                                 A network error says DNS may still be propagating; retry in 30 seconds.
                                 Warns about Access only when the bare request returns an HTTP status other than 401 or 403.
@@ -400,9 +422,9 @@ const deployOpts = {
 	"workers-dev": B, "workers-dev-subdomain": S, "upstream-token-stdin": B, "no-upstream-token": B, "event-secret-stdin": B,
 };
 const SPEC = {
-	hosted: { name: S, json: B, agent: S, hostname: S, origin: S, path: S, preset: S, "control-url": S, "secret-file": S, "secret-env": S, "secret-from": S, "hermes-home": S, route: S, "token-file": S, "no-run": B },
+	hosted: { url: S, version: S, "upstream-token-file": S, "upstream-token-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S, name: S, json: B, agent: S, hostname: S, origin: S, path: S, preset: S, "control-url": S, "secret-file": S, "secret-env": S, "secret-from": S, "hermes-home": S, route: S, "token-file": S, "no-run": B },
 	init: { ...deployOpts, ...tunnelOpts, tunnel: B }, deploy: deployOpts,
-	wake: { ...deployOpts, json: B, url: S, "reference-file": S, "reference-env": S, clear: B, version: S, agent: S, "control-url": S, "key-header": S, "key-file": S, "key-env": S, "key-stdin": B, "hmac-secret-file": S, "hmac-secret-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S }, tunnel: tunnelOpts,
+	wake: { ...deployOpts, "local-url": S, json: B, url: S, "reference-file": S, "reference-env": S, clear: B, version: S, agent: S, "control-url": S, "key-header": S, "key-file": S, "key-env": S, "key-stdin": B, "hmac-secret-file": S, "hmac-secret-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S }, tunnel: { ...tunnelOpts, preset: S, "hermes-route": S, "hmac-secret-stdin": B, json: B },
 	inbox: { context: S, from: S, all: B, json: B },
 	reply: { text: S, stdin: B, state: { type: "string", default: "completed" }, artifact: B, "artifact-name": { type: "string", default: "response" }, force: B },
 	history: { from: S, n: { type: "string", short: "n", default: "50" }, json: B },
@@ -481,7 +503,7 @@ export async function main(argv) {
 				throw e;
 			}
 		case "tunnel": {
-			const sub = need(p[0], "tunnel create|status|rm");
+			const sub = need(p[0], "tunnel create|zones|status|rm");
 			if (p.length > 1) throw new CliError(`tunnel ${sub} takes no arguments (${p.slice(1).join(" ")}). Run \`${CLI} tunnel --help\`.`);
 			return tun.tunnel(sub, o);
 		}
@@ -526,6 +548,7 @@ export async function main(argv) {
 			throw new CliError(`unknown peer action ${sub} (announce|forward)`);
 		}
 		case "hosted": {
+			if (p[0] === "upstream" && p.length === 2) return hosted.output(() => hosted.upstream(p[1], o), o);
 			if (p.length === 1 && ["capabilities", "list", "create", "names", "capacity"].includes(p[0])) return hosted.output(() => hosted[p[0]](o), o);
 			if (p.length !== 2 || p[0] !== "link" || !["finish", "create"].includes(p[1])) return linkOutput(linkUsage, o);
 			return linkOutput(() => (p[1] === "create" ? createLink : finishLink)({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") }), o);

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"));
 }
 
@@ -281,9 +281,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 +296,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,19 +358,20 @@ 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\`)`);
 	} catch (e) {
 		console.error("==> rolling back what was created");
@@ -367,6 +380,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 +434,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 +447,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 +456,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 +580,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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.8.39",
+	"version": "0.8.41",
 	"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.
@@ -2408,6 +2409,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/version.ts

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

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/wake-retry.test.ts

@@ -127,3 +127,45 @@ test("unsigned OpenBot owner test/preview and inbound wake never contact the web
 	assert.equal(message.body.error, undefined, "stored inbox message succeeds without a wake");
 	assert.equal(calls, 0);
 });
+
+
+test("MausBot retries keep their key, later messages and verification tests get new keys", async (t) => {
+	const env: any = { DB: d1(new URL("../migrations/", import.meta.url)), PUBLIC_URL: BASE, OWNER_TOKEN: "owner-secret",
+		WAKE_PRESET: "mausbot", WAKE_WEBHOOK_URL: "https://hooks.example.com/hooks/wh_test", WAKE_WEBHOOK_KEY: "dummy-secret", WAKE_DEBOUNCE_SECONDS: "0", WAKE_BUSY_SECONDS: "0" };
+	const sent: any[] = [];
+	let answer = 429;
+	const original = globalThis.fetch;
+	globalThis.fetch = (async (_url: any, init: any) => { sent.push(init); return new Response("{}", { status: answer, headers: { "retry-after": "30" } }); }) as typeof fetch;
+	t.after(() => { globalThis.fetch = original; });
+	const call = async (method: string, path: string, body?: any, auth = "Bearer owner-secret") => {
+		const pending: Promise<unknown>[] = [];
+		const response = await worker.fetch(new Request(BASE + path, { method, headers: { authorization: auth, "content-type": "application/json" }, body: body ? JSON.stringify(body) : undefined }) as any,
+			env, { waitUntil: (p: Promise<unknown>) => pending.push(p), passThroughOnException() {} } as any);
+		await Promise.allSettled(pending);
+		return { status: response.status, body: await response.json() as any };
+	};
+	const preview = await call("GET", "/owner/wake/preview");
+	assert.equal(preview.status, 200);
+	assert.equal(preview.body.request.headers.authorization, "Bearer ••••");
+	assert.ok(!JSON.stringify(preview.body).includes(env.WAKE_WEBHOOK_KEY));
+	const peer = await call("POST", "/owner/peers", { label: "maus-test" });
+	const msg = (id: string, taskId?: string) => call("POST", "/", { jsonrpc: "2.0", id: 1, method: "message/send", params: { message: { kind: "message", role: "user", messageId: id, contextId: "ctx-maus", ...(taskId ? { taskId } : {}), parts: [{ kind: "text", text: "same text" }] } } }, `Bearer ${peer.body.token}`);
+	const first = await msg("m1");
+	assert.equal(sent.length, 1);
+	answer = 202;
+	// Advance only the saved retry deadline, without changing the global clock.
+	await env.DB.prepare("UPDATE wakes SET last_sent_ms = ? WHERE context_id = ?").bind(Date.now() - 1000, "ctx-maus").run();
+	await call("GET", "/health");
+	assert.equal(sent.length, 2);
+	assert.equal(sent[0].headers["idempotency-key"], sent[1].headers["idempotency-key"]);
+	await msg("m2", first.body.result.id);
+	assert.equal(sent.length, 3);
+	assert.notEqual(sent[2].headers["idempotency-key"], sent[1].headers["idempotency-key"]);
+	await call("POST", "/owner/wake/test");
+	await call("POST", "/owner/wake/test");
+	assert.notEqual(sent[3].headers["idempotency-key"], sent[4].headers["idempotency-key"]);
+	delete env.WAKE_WEBHOOK_KEY;
+	assert.equal((await call("GET", "/owner/wake/preview")).status, 400);
+	assert.equal((await call("POST", "/owner/wake/test")).body.status, null);
+	assert.equal(sent.length, 5, "no unsigned request leaves the Worker");
+});

package/worker/test/wake.test.ts

@@ -106,7 +106,7 @@ test("generic: invalid template throws", () => {
 
 test("every preset renders valid JSON", async () => {
 	for (const p of PRESETS) {
-		const r = (await renderWake({ preset: p, url: "https://x/y", key: "k", hmacSecret: "s" }, ev))!;
+		const r = (await renderWake({ preset: p, url: "https://x/hooks/wh_test", key: "k", hmacSecret: "s" }, ev))!;
 		JSON.parse(r.body);
 	}
 });
@@ -151,7 +151,7 @@ const ACCESS = { accessClientId: "abc123.access", accessClientSecret: "s3cr3t-va
 
 test("Access service-token headers are added for every preset, next to the preset's own auth", async () => {
 	for (const preset of PRESETS) {
-		const r = (await renderWake({ preset, url: "https://wake-x.example.com/hooks/wake", key: "k1", hmacSecret: "h1", ...ACCESS }, ev))!;
+		const r = (await renderWake({ preset, url: "https://wake-x.example.com/hooks/wh_test", key: "k1", hmacSecret: "h1", ...ACCESS }, ev))!;
 		assert.equal(r.headers["CF-Access-Client-Id"], "abc123.access", preset);
 		assert.equal(r.headers["CF-Access-Client-Secret"], "s3cr3t-value-0123456789", preset);
 		if (preset === "hermes") assert.ok(r.headers["X-Webhook-Signature-V2"], "hermes keeps its HMAC");
@@ -227,3 +227,36 @@ test("OpenBot assigns a fresh delivery ID to every rendered attempt", async () =
 	const second = (await renderWake(cfg, ev))!;
 	assert.notEqual(first.headers["x-openbot-delivery-id"], second.headers["x-openbot-delivery-id"]);
 });
+
+
+test("mausbot: Bearer JSON, bounded peer preview, stable delivery identity and masked credentials", async () => {
+	const cfg = { preset: "mausbot", url: "https://hooks.example.com/hooks/wh_example", key: "dummy-mausbot-secret" };
+	const event = { ...ev, preview: '雪 "quoted"\n'.repeat(100), deliveryId: "wake-1" };
+	const first = (await renderWake(cfg, event, { requestId: "attempt-1" }))!;
+	const retry = (await renderWake(cfg, event, { requestId: "attempt-2" }))!;
+	assert.equal(first.headers.authorization, "Bearer dummy-mausbot-secret");
+	assert.equal(first.headers["content-type"], "application/json");
+	assert.equal(first.headers["idempotency-key"], "t-2:wake-1");
+	assert.equal(retry.headers["idempotency-key"], first.headers["idempotency-key"]);
+	assert.deepEqual(JSON.parse(first.body), wakePayload(event, "npx -y a2a-exposed@latest"));
+	assert.equal(JSON.parse(first.body).preview.length, 300);
+	assert.equal(JSON.parse(first.body).deliveryId, undefined);
+	assert.equal(redact(first).headers.authorization, "Bearer ••••");
+	assert.ok(!JSON.stringify(redact(first)).includes(cfg.key));
+	const update = (await renderWake(cfg, { ...event, kind: "outbound_update", deliveryId: "wake-2" }))!;
+	assert.notEqual(update.headers["idempotency-key"], first.headers["idempotency-key"]);
+	assert.match(JSON.parse(update.body).hint, /history ctx-1 --from peer-a/);
+	const test1 = (await renderWake(cfg, { ...ev, kind: "test", taskId: "none" }))!;
+	const test2 = (await renderWake(cfg, { ...ev, kind: "test", taskId: "none" }))!;
+	assert.notEqual(test1.headers["idempotency-key"], test2.headers["idempotency-key"], "verification test must not suppress the enabled test");
+});
+
+test("mausbot: rejects unsafe URLs, capability credentials and missing Bearer auth without echoing input", async () => {
+	for (const url of ["http://example.com/hooks/wh_test", "https://user:secret@example.com/hooks/wh_test", "https://example.com/hooks/wh_test/capability-secret", "https://example.com/hooks/wh_test?secret=dummy", "https://example.com/hooks/wh_test#dummy", "not-a-url", "https://example.com/api"]) {
+		await assert.rejects(renderWake({ preset: "mausbot", url, key: "dummy" }, ev), error => error instanceof Error && /MausBot requires an HTTPS/.test(error.message) && !error.message.includes(url));
+	}
+	for (const key of [undefined, "", "   ", "line\nbreak"]) {
+		await assert.rejects(renderWake({ preset: "mausbot", url: "https://example.com/hooks/wh_test", key, hmacSecret: "cannot-replace-bearer" }, ev), /MausBot requires WAKE_WEBHOOK_KEY/);
+	}
+	assert.equal(await renderWake({ preset: "mausbot" }, ev), null);
+});