a2a-exposed 0.8.28 → 0.8.29

package/lib/link-finish.mjs

@@ -8,6 +8,7 @@ import { readSigningSecret, validateSecretSource, writeTokenFile, startConnector
 
 const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const ERRORS = {
+	expired_token: "The link request expired. Start a new one with hosted link create.",
 	unauthorized: "Run a2a-exposed login, then run finish again.",
 	invalid_request: "Check the agent name, hostname and link options before running the command again.",
 	link_exists: "The link request was refused; review the approval page before changing or removing an existing link.",
@@ -18,10 +19,45 @@ const ERRORS = {
 	provision_failed: "Check the approval page for the failing provisioning phase and cleanup state before running the command again.",
 	preset: "Select a valid wake preset with --preset <id>, then run finish again.",
 	signing_secret: "Check the local signing-secret source and receiver configuration before running the command again.",
-	unreadable: "Reconnect Cloudflare on the website, then run finish again.",
+	unreadable: "The secure link access key could not be read. Remove the secure link on the website, then run create again.",
+	slow_down: "Too many pending requests for this agent. Deny an earlier request on the website or wait for it to expire, then run finish again.",
+	access_denied: "The request was denied. Run finish again only if you still want to set up this link.",
+	link_not_ready: "The secure link is not ready. Finish creating it in Wake settings on the website, then run finish again.",
+	invalid_grant: "This grant is not valid. Run finish again and approve a new request.",
+	already_delivered: "Credentials were already delivered for this request. Run finish again for fresh approval if you did not receive them.",
+	connector_not_connected: "The connector is not connected. Start cloudflared with the saved token file, then run finish again for fresh approval.",
+	not_found: "That agent or request was not found. Check --agent on the website, then run finish again.",
+	cloudflare_unavailable: "Cloudflare could not be reached. Reconnect Cloudflare in Wake settings on the website, then run finish again.",
 	unavailable: "The service is temporarily unavailable; retry later with fresh approval.",
 };
-const APPROVAL_ERRORS = new Set(["access_denied", "expired_token", "link_not_ready", "invalid_grant", "already_delivered", "connector_not_connected", "not_found", "cloudflare_unavailable"]);
+
+// Fixed local guidance only: wake results must never expose server text.
+const WAKE_NEXT_STEPS = {
+	none: "Update the hosted Worker, then run finish again for fresh approval.",
+	"dns-missing": "Wait for DNS propagation, then run finish again for fresh approval.",
+	"access-401": "Check the signing secret and Access service-token pair, then run finish again for fresh approval.",
+	"access-403": "Check the signing secret and Access service-token pair, then run finish again for fresh approval.",
+	timeout: "Retry later by running finish again for fresh approval.",
+	"origin-429": "Retry later by running finish again for fresh approval.",
+	"origin-5xx": "Retry later by running finish again for fresh approval.",
+	"origin-NNN": "Check the receiver's HTTP response, then run finish again for fresh approval.",
+	tls: "Fix the receiver's TLS certificate, then run finish again for fresh approval.",
+	private: "Use a public HTTPS wake URL, then run finish again for fresh approval.",
+	dns: "Check the wake hostname's DNS records, then run finish again for fresh approval.",
+	connection: "Check that the receiver is reachable, then run finish again for fresh approval.",
+	unreadable: "Remove the secure link on the website, then run create again.",
+	failed: "Check the receiver configuration, then run finish again for fresh approval.",
+	unknown: "Update the CLI (npx a2a-exposed@latest) and send feedback.",
+};
+
+function wakeFailure(raw) {
+	const value = typeof raw === "string" ? raw : "";
+	const normalized = /^[1-5]\d{2}$/.test(value) ? `origin-${value}` : value;
+	const result = Object.hasOwn(WAKE_NEXT_STEPS, normalized) && !["origin-5xx", "origin-NNN"].includes(normalized)
+		? normalized : /^origin-\d{3}$/.test(normalized) ? normalized : "unknown";
+	const guidance = WAKE_NEXT_STEPS[result] ?? WAKE_NEXT_STEPS[/^origin-5\d{2}$/.test(result) ? "origin-5xx" : "origin-NNN"];
+	return { result, message: `wake test of the new secure link failed (${result}); saved wake settings were not changed. ${guidance}` };
+}
 
 // Only these public validation templates may cross the server-text boundary.
 // Never echo arbitrary bodies, fetch errors, child output, or credential-bearing fields.
@@ -34,23 +70,47 @@ const VALIDATION_MESSAGES = new Set([
 	"Use an http or https origin with no path or credentials.",
 	"Use a path beginning with /, with no query or fragment.",
 ]);
+const DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
 function validationDetail(body, hostname) {
 	if (typeof body?.message !== "string") return "";
 	if (VALIDATION_MESSAGES.has(body.message)) return body.message.replace(/ and try again\.$/, ".");
+	if (body.reason === "outside_zone" || body.error === "outside_zone") {
+		const prefix = "That hostname is not on a domain in your Cloudflare account. ";
+		if (body.message === prefix + "Add a domain to Cloudflare, then run create again.") return body.message;
+		const match = body.message.match(/^That hostname is not on a domain in your Cloudflare account\. Use a hostname under (.+)\.$/);
+		if (match && match[1].split(" or ").every((domain) => DOMAIN.test(domain))) return body.message;
+	}
 	const apex = `Use a hostname under ${hostname}, such as wake.${hostname}. The domain itself is not a secure link.`;
 	return hostname && body.message === apex ? apex : "";
 }
 
-function failure(status, body, { command, hostname }) {
-	const code = Object.hasOwn(ERRORS, body?.error) || APPROVAL_ERRORS.has(body?.error) ? body.error : `HTTP ${status}`;
-	const detail = ["invalid_request", "apex_hostname"].includes(code) ? validationDetail(body, hostname) : "";
-	const message = detail || (Object.hasOwn(ERRORS, code) ? ERRORS[code].replace(/run finish/g, `run ${command}`) : "check the link on the website and rerun the command for fresh approval");
+function provisionGuidance(body) {
+	if (body.phase === "cleanup") return "Remove the unfinished secure link on the website, then run create again.";
+	if (["hostname", "zone", "existing_dns", "existing_tunnel"].includes(body.phase))
+		return "Choose another hostname on a domain in your Cloudflare account, then run create again.";
+	if (body.status === 401 || body.status === 403)
+		return "Cloudflare refused access. Reconnect Cloudflare on the website, then run create again.";
+	if (body.status === 429 || (Number.isInteger(body.status) && body.status >= 500 && body.status <= 599))
+		return "Cloudflare was busy. Run create again in a few minutes.";
+	return ERRORS.provision_failed;
+}
+
+function failure(status, body, { command, hostname }, phase = "requests") {
+	const known = (value) => typeof value === "string" && Object.hasOwn(ERRORS, value);
+	const code = known(body?.reason) ? body.reason : known(body?.error) ? body.error : `HTTP ${status}`;
+	const detail = phase === "requests" && ["invalid_request", "apex_hostname", "outside_zone"].includes(code) ? validationDetail(body, hostname) : "";
+	let guidance = code === "provision_failed" ? provisionGuidance(body) : Object.hasOwn(ERRORS, code) ? ERRORS[code] : "check the link on the website and rerun the command for fresh approval";
+	if (code === "expired_token") guidance = ["grant", "connector"].includes(phase)
+		? `The approval grant expired. Run hosted link finish again for fresh approval; ${phase === "grant" ? "the saved connector token remains on disk and " : ""}wake settings were not saved.`
+		: `The link request expired. Start a new one with hosted link ${command}.`;
+	if (code === "invalid_request" && phase === "token") guidance = `The approval polling request was refused. Run hosted link ${command} again for fresh approval.`;
+	const message = detail || guidance.replace(/run finish/gi, (match) => `${match.startsWith("R") ? "Run" : "run"} ${command}`);
 	return new CliError(`link ${command} failed${hostname ? ` for ${hostname}` : ""} (${code}); ${message}`);
 }
 
-export function savedLinkSession(origin, session = C.controlSession()) {
+export function savedLinkSession(origin, session = C.controlSession(), command = "finish") {
 	if (controlOrigin(session.origin) !== origin || !session.token)
-		throw new CliError("sign in to this service first: run login --control-url <service-origin>, then rerun link setup; environment sessions require both CONTROL_URL and CONTROL_TOKEN");
+		throw new CliError(`sign in to this service first: run login --control-url <service-origin>, then rerun hosted link ${command}; environment sessions require both CONTROL_URL and CONTROL_TOKEN`);
 	return session.token;
 }
 
@@ -100,7 +160,7 @@ async function setupLink(o, {
 	if (o.preset !== undefined && (typeof o.preset !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(o.preset))) throw new CliError("--preset must be a wake preset id");
 	const origin = controlOrigin(o["control-url"]);
 	if (!origin) throw new CliError("--control-url must be an https origin with no path");
-	const session = sessionToken(origin);
+	const session = sessionToken(origin, undefined, context.command);
 	const request = async (endpoint, body, grant, timeout = 15000) => {
 		let response;
 		try {
@@ -134,10 +194,10 @@ async function setupLink(o, {
 		const token = await request("token", { request_id: setup.request_id, verifier });
 		if (token.response.status === 428 && token.body.error === "authorization_pending") continue;
 		if (token.response.status === 429 && token.body.error === "slow_down") { interval += 5; continue; }
-		if (!token.response.ok) throw failure(token.response.status, token.body, context);
+		if (!token.response.ok) throw failure(token.response.status, token.body, context, "token");
 		authorized = token.body; break;
 	}
-	if (!authorized) throw failure(410, { error: "expired_token" }, context);
+	if (!authorized) throw failure(410, { error: "expired_token" }, context, "token");
 	const { grant, link } = authorized;
 	if (typeof grant !== "string" || !/^[\x21-\x7e]+$/.test(grant) || grant.length > 4096 || link?.agent !== agent || typeof link.path !== "string" || !link.path.startsWith("/") || typeof link.preset !== "string" || typeof link.hostname !== "string" || typeof link.origin !== "string")
 		throw new CliError("invalid approved link response");
@@ -148,7 +208,7 @@ async function setupLink(o, {
 	// Resolve and validate the source before spending the one-time connector delivery.
 	const secret = readSecret(o, { ...link, preset });
 	const connector = await request("connector", {}, grant);
-	if (!connector.response.ok) throw failure(connector.response.status, connector.body, context);
+	if (!connector.response.ok) throw failure(connector.response.status, connector.body, context, "connector");
 	if (typeof connector.body.connector_token !== "string" || !connector.body.connector_token.trim() || /\s/.test(connector.body.connector_token)) throw new CliError("invalid connector response; run finish again for fresh approval");
 	const tokenFile = path.resolve(o["token-file"] || path.join(os.homedir(), ".a2a-exposed", "links", `${agent}.token`));
 	saveToken(tokenFile, connector.body.connector_token);
@@ -162,17 +222,19 @@ async function setupLink(o, {
 	for (let poll = 0; poll < 20 && now() < connectDeadline; poll++) {
 		const status = await request("status", undefined, grant, Math.min(15000, connectDeadline - now()));
 		if (now() >= connectDeadline) break;
-		if (!status.response.ok) throw failure(status.response.status, status.body, context);
+		if (!status.response.ok) throw failure(status.response.status, status.body, context, "grant");
 		if (status.body.connector === "connected" && Number.isInteger(status.body.connections) && status.body.connections > 0) { connected = true; break; }
 		await sleep(Math.min(3000, Math.max(0, connectDeadline - now())));
 	}
 	if (!connected) throw new CliError("connector did not report connected within 60 seconds; check cloudflared and run finish again for fresh approval");
 	const tested = await request("wake-test", { signing_secret: secret, preset }, grant);
-	if (!tested.response.ok) throw failure(tested.response.status, tested.body, context);
+	if (!tested.response.ok) throw failure(tested.response.status, tested.body, context, "grant");
 	if (tested.body.result !== "ok" || tested.body.saved !== true) {
-		const result = (["dns-missing", "access-401", "access-403", "timeout"].includes(tested.body.result) || /^origin-\d{3}$/.test(tested.body.result)) ? tested.body.result : "unknown";
-		throw new CliError(`wake test did not save settings (${result}); fix the receiver and run finish again for fresh approval`);
+		const { result, message } = wakeFailure(tested.body.result);
+		write(`wake_result=${result}`);
+		throw new CliError(message);
 	}
+	write("wake_result=ok");
 	write("Connector connected. Wake test passed and settings saved.");
 	return { saved: true, connectorStarted: true };
 }

package/lib/main.mjs

@@ -115,6 +115,8 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
   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
   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
 
 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)

package/package.json

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

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.28";
+export const VERSION = "0.8.29";