a2a-exposed 0.8.27 → 0.8.29

package/lib/config.mjs

@@ -54,6 +54,14 @@ export function get(key, dflt = "") {
 	return f !== undefined && f !== "" ? f : dflt;
 }
 
+/** Resolve a control credential with the origin from the same source.
+ * A partial environment override must never borrow saved credentials.
+ */
+export function controlSession(env = process.env, saved = fileConfig()) {
+	const source = env.CONTROL_URL || env.CONTROL_TOKEN ? env : saved;
+	return { origin: source.CONTROL_URL || "", token: source.CONTROL_TOKEN || "" };
+}
+
 function ensureDir() {
 	fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
 }

package/lib/deploy.mjs

@@ -124,6 +124,21 @@ function run(cmd, args, { cwd, env, capture = false, captureStderr = false, allo
 	return r;
 }
 
+/** Keep dependency installer output in a private local log. */
+export function installDependencies(dir, { configDir = C.CONFIG_DIR, env = process.env } = {}) {
+	fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+	const log = path.join(configDir, "npm-install.log");
+	const fd = fs.openSync(log, "w", 0o600);
+	fs.fchmodSync(fd, 0o600);
+	let result;
+	try {
+		result = spawnSync("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir, env, stdio: ["ignore", fd, fd] });
+	} finally {
+		fs.closeSync(fd);
+	}
+	if (result.error || result.status !== 0) die(`npm install failed; inspect the private log: ${log}`);
+}
+
 export function cfBin(dir) {
 	const local = path.join(dir, "node_modules", ".bin", "cf");
 	return fs.existsSync(local) ? local : "cf";
@@ -561,7 +576,7 @@ export async function init(o) {
 	step(`worker project -> ${dir}`);
 	syncTemplate(dir);
 	requireCfLogin(dir);
-	if (!o["skip-install"]) run("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir });
+	if (!o["skip-install"]) installDependencies(dir);
 	const env = cfEnv();
 
 	const dbName = C.get("A2A_D1_NAME") || C.get("A2A_WORKER_NAME");
@@ -588,6 +603,7 @@ export async function init(o) {
 	const base = deployedBase();
 	if (base) await verifyDeployedCard(base);
 	console.log(base);
+	await reportApprovalReadiness(base, ownerToken);
 	reportSwitch(switched);
 	proxyNote(secrets);
 	if (rotated) console.error(`owner token replaced. Update A2A_OWNER_TOKEN wherever this A2A endpoint is called, then run \`${CLI} peers sync\` so uploaded peers stay readable.`);
@@ -595,6 +611,21 @@ export async function init(o) {
 	printStar();
 }
 
+/** Read the deployed inbox, using its saved owner token rather than an environment override. */
+async function reportApprovalReadiness(base, ownerToken) {
+	try {
+		if (!base) throw new Error();
+		const { status, data } = await httpJson(`${base}/owner/pairing`, { headers: { authorization: `Bearer ${ownerToken}` }, timeout: 3000 });
+		if (status !== 200 || typeof data?.passwordSet !== "boolean" || !["human", "agent", "off"].includes(data.mode)) throw new Error();
+		if (data.mode === "off" || (Array.isArray(data.approvalMethods) && !data.approvalMethods.includes("password"))) return;
+		console.error(data.passwordSet ? "Approval password: set."
+			: `Approval password: not set. To approve pairing on /device with a password, run: ${CLI} pair set-password --web`);
+		if (!data.passwordSet) console.error("Send the one-time setup link privately to your human. They set the password themselves; never open the page or ask for the password.");
+	} catch {
+		console.error(`Approval password: could not check. Run: ${CLI} pair list --json`);
+	}
+}
+
 /** Proxy / expose mode reminder after a deploy (the upstream credentials are secrets: only their names are shown). */
 function proxyNote(secrets = {}) {
 	const up = C.get("A2A_UPSTREAM_URL");
@@ -685,7 +716,7 @@ export async function deploy(o) {
 	guardTunnelUrl();
 	step(`worker project -> ${dir}${cfProfile() ? ` (cf profile ${cfProfile()})` : ""}`);
 	syncTemplate(dir);
-	if (!o["skip-install"]) run("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir });
+	if (!o["skip-install"]) installDependencies(dir);
 	const env = cfEnv();
 	applyMigrations(dir, env);
 	const secrets = { ...deploySecretsFromEnv(), ...upstreamSecrets, ...await eventSecretFromStdin(o) };

package/lib/feedback.mjs

@@ -32,7 +32,7 @@ const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 /** The repository that will receive the issue. The prefilled form is ISSUE_REPO. A hosted post uses the name that URL returns. */
 export function publicIssueWarning(repo = ISSUE_REPO) {
 	const name = typeof repo === "string" && REPO_RE.test(repo) && repo.length <= 100 && !repo.includes("..") ? repo : ISSUE_REPO;
-	return `This report is filed as a public GitHub issue on ${name}. Do not include confidential information: secrets, tokens, owner or pairing tokens, private URLs or hostnames, message contents, or personal data.`;
+	return `Posting this report creates a public GitHub issue on ${name}. Do not include confidential information: secrets, tokens, owner or pairing tokens, private URLs or hostnames, message contents, or personal data.`;
 }
 
 export const PUBLIC_ISSUE_WARNING = publicIssueWarning(ISSUE_REPO);
@@ -316,6 +316,7 @@ export async function runFeedback(input) {
 		}),
 	});
 	if (!endpoint) return fallback();
+	await input.beforePost?.();
 	let response;
 	try {
 		response = await call(endpoint, {

package/lib/link-finish.mjs

@@ -3,33 +3,170 @@ import path from "node:path";
 import os from "node:os";
 import { CliError } from "./a2a.mjs";
 import { controlOrigin } from "./account.mjs";
+import * as C from "./config.mjs";
 import { readSigningSecret, validateSecretSource, writeTokenFile, startConnector, connectorCommand } from "./local-link.mjs";
 
 const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const ERRORS = new Set(["access_denied", "expired_token", "link_not_ready", "invalid_grant", "already_delivered", "connector_not_connected", "not_found", "cloudflare_unavailable"]);
+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.",
+	apex_hostname: "The domain itself cannot be a secure link. Choose a hostname below it, such as wake.example.com, then run create again.",
+	outside_zone: "The hostname is not on a domain in your Cloudflare account. Choose a hostname on your domain, then run create again.",
+	existing_dns: "The hostname already has a DNS record. Choose another hostname, then run create again.",
+	existing_tunnel: "The hostname is already routed through another tunnel. Choose another hostname, then run create again.",
+	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: "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.",
+};
 
-// Deliberately never echo server text, bodies, fetch errors, or child output.
-function failure(status, body) {
-	const code = ERRORS.has(body?.error) ? body.error : `HTTP ${status}`;
-	return new CliError(`link finish failed (${code}); check the link on the website and run finish again for fresh approval`);
+// 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.
+const VALIDATION_MESSAGES = new Set([
+	"Choose a wake preset.", "Choose a wake preset and try again.",
+	"Use a hostname on the selected domain.",
+	"Use a full hostname such as wake.example.com.",
+	"Remove the scheme (https://), port and path. Use a full hostname such as wake.example.com.",
+	"Enter the local origin URL, such as http://127.0.0.1:8644.",
+	"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 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(), 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 hosted link ${command}; environment sessions require both CONTROL_URL and CONTROL_TOKEN`);
+	return session.token;
+}
+
+const CREATE_FIELDS = ["hostname", "origin", "path", "preset"];
+
+function createPlan(o) {
+	for (const key of CREATE_FIELDS) {
+		if (typeof o[key] !== "string" || !o[key]) throw new CliError(`hosted link create requires --${key}`);
+	}
+	const hostname = o.hostname.trim().toLowerCase();
+	if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(hostname))
+		throw new CliError("--hostname must be a DNS hostname on your Cloudflare domain");
+	let origin;
+	try { origin = new URL(o.origin); } catch { throw new CliError("--origin must be an http or https origin"); }
+	if (!/^https?:$/.test(origin.protocol) || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash)
+		throw new CliError("--origin must be an http or https origin with no path or credentials");
+	if (!o.path.startsWith("/") || o.path.startsWith("//") || /[\s?#\\\x00-\x1f\x7f]/.test(o.path) || o.path.length > 1000)
+		throw new CliError("--path must begin with / and have no query, fragment or whitespace");
+	if (!/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw new CliError("--preset must be a wake preset id");
+	return { hostname, origin: origin.origin, path: o.path, preset: o.preset };
+}
+
+export function createLink(o, deps) {
+	const create = createPlan(o);
+	// Catch a wrong local route before asking the owner to create any resources.
+	validateSecretSource(o);
+	if (o["secret-from"] === "hermes" && (create.preset !== "hermes" || !/^\/webhooks\/[A-Za-z0-9_-]+$/.test(create.path) || (o.route && create.path !== `/webhooks/${o.route}`)))
+		throw new CliError("Hermes route does not match the create path and preset");
+	return setupLink(o, deps, create);
+}
+
+export function finishLink(o, deps) {
+	if (CREATE_FIELDS.filter((key) => key !== "preset").some((key) => o[key] !== undefined)) throw new CliError("creation options require hosted link create; finish only reuses an existing link");
+	return setupLink(o, deps);
 }
 
-export async function finishLink(o, {
+async function setupLink(o, {
 	fetchImpl = fetch, sleep = sleepDefault, now = Date.now,
 	write = (line) => console.error(line), saveToken = writeTokenFile,
 	readSecret = readSigningSecret, runConnector = startConnector,
-} = {}) {
+	sessionToken = savedLinkSession,
+} = {}, create) {
 	validateSecretSource(o);
+	const context = { command: create ? "create" : "finish", hostname: create?.hostname };
 	const agent = o.agent;
 	if (typeof agent !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$/.test(agent)) throw new CliError("--agent must be an agent name (letters, digits, underscores or hyphens)");
+	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, undefined, context.command);
 	const request = async (endpoint, body, grant, timeout = 15000) => {
 		let response;
 		try {
 			response = await fetchImpl(`${origin}/api/link-finish/${endpoint}`, {
 				method: body === undefined ? "GET" : "POST", redirect: "error",
-				headers: { accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }), ...(grant ? { authorization: `Grant ${grant}` } : {}) },
+				headers: { accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }), ...(endpoint === "requests" ? { authorization: `Bearer ${session}` } : grant ? { authorization: `Grant ${grant}` } : {}) },
 				...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(timeout),
 			});
 			const text = await response.text();
@@ -37,12 +174,12 @@ export async function finishLink(o, {
 			const parsed = JSON.parse(text);
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
 			return { response, body: parsed };
-		} catch { throw new CliError("link finish request failed; check the connection and run finish again for fresh approval"); }
+		} catch { throw new CliError(`link ${context.command} request failed; check the connection and run ${context.command} again for fresh approval`); }
 	};
 	const verifier = crypto.randomBytes(32).toString("base64url");
 	const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
-	const started = await request("requests", { agent, challenge });
-	if (started.response.status !== 201) throw failure(started.response.status, started.body);
+	const started = await request("requests", { agent, challenge, ...(create ? { create } : {}) });
+	if (started.response.status !== 201) throw failure(started.response.status, started.body, context);
 	const setup = started.body;
 	let approval;
 	try { approval = new URL(setup.approve_url); } catch { throw new CliError("invalid approval response"); }
@@ -57,17 +194,21 @@ export async function finishLink(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);
+		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" });
+	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" || !link.preset || typeof link.hostname !== "string" || typeof link.origin !== "string")
+	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");
+	if (create && CREATE_FIELDS.some((key) => link[key] !== create[key]))
+		throw new CliError("approved link differs from the requested creation plan; no connector or signing secret was transferred");
+	const preset = o.preset ?? link.preset;
+	if (!/^[a-z][a-z0-9-]{0,63}$/.test(preset)) throw new CliError("approved link has no valid preset; rerun finish with --preset <id> before requesting fresh approval");
 	// Resolve and validate the source before spending the one-time connector delivery.
-	const secret = readSecret(o, link);
+	const secret = readSecret(o, { ...link, preset });
 	const connector = await request("connector", {}, grant);
-	if (!connector.response.ok) throw failure(connector.response.status, connector.body);
+	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);
@@ -81,17 +222,19 @@ export async function finishLink(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);
+		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: link.preset }, grant);
-	if (!tested.response.ok) throw failure(tested.response.status, tested.body);
+	const tested = await request("wake-test", { signing_secret: secret, preset }, grant);
+	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", "origin-4xx/5xx", "timeout"].includes(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

@@ -12,7 +12,7 @@ import * as account from "./account.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
 import * as un from "./uninstall.mjs";
-import { finishLink } from "./link-finish.mjs";
+import { finishLink, createLink } from "./link-finish.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
@@ -23,19 +23,12 @@ Usage: npx -y a2a-exposed@latest <command> [options]
        --version, -v                 print the version
        --help, -h                    print this help
 
-  hosted link finish --agent NAME --control-url https://control.example
-       (--secret-file FILE | --secret-env VAR | --secret-from hermes)
-       [--hermes-home DIR] [--route NAME] [--token-file FILE] [--no-run]
-                                Human approves the printed URL/code. Saves the connector token privately,
-                                starts cloudflared, waits up to 60 seconds, then tests and saves the wake.
-                                --control-url defaults to saved CONTROL_URL. No secrets in arguments/output.
-                                --no-run saves the token and prints the connector command; wake is not saved.
-                                Recovery: rerun with fresh approval; the ready link is reused.
+Setup options: --skip-install skips dependency installation when dependencies already exist.
 
 Setup (needs Node 22.18+, e.g. \`mise exec node@22 -- npx -y a2a-exposed@latest ...\`, and a Cloudflare login:
 npx cf auth login --no-browser; on a VPS where it fails with HTTP 403 before showing a code, export
 CLOUDFLARE_API_TOKEN instead: setup skill, Troubleshooting. a2a.exposed hosts the A2A endpoint and is open to everyone
-(https://a2a.exposed/pricing). When to use it, and the sentence to say:
+(https://a2a.exposed/pricing). When to use it:
 https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#hosted-inbox)
   init [--hostname <host> | --workers-dev [--workers-dev-subdomain NAME]]
        [--agent-name N] [--agent-description D] [--agent-skills JSON]
@@ -51,6 +44,7 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                 --workers-dev  move an existing custom-domain deployment to workers.dev (and
                                                --hostname H moves it back); the old URL answers 301/410
                                 --workers-dev-subdomain  create the account's workers.dev subdomain if missing
+                                               Uses system script on macOS/Linux, including under automation.
                                 --cf-profile   cf auth profile for a separate Cloudflare login
                                                (npx cf auth create NAME --no-browser); saved, used by every cf call.
                                                When whoami lists no accounts, init reads cf accounts list
@@ -60,6 +54,8 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                                the owner token via \`pair approve\`, or the approval password
                                                on the /device page; agent: the agent runs \`pair approve\` after
                                                the human says yes; off: no pairing endpoints, \`token issue\` only)
+                                init reports readiness when password approval is enabled; when missing, use
+                                               \`pair set-password --web\` for the human-owned setup page.
                                 --pbkdf2-iterations  approval-password hashing cost, 50000-100000 (default 100000,
                                                the Workers maximum; lower only if /device hits error 1102)
                                 --workers-logs on|off  persisted Cloudflare Workers Logs (query strings redacted)
@@ -119,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)
@@ -281,7 +279,7 @@ Owner
   the MCP consent page when the issuer, client id, client secret, and allowlist are all set.
 
 Feedback
-  feedback "message" [--kind bug|idea|other] [--contact x]
+  feedback "message" [--json] [--kind bug|idea|other] [--contact x]
             [--steps S] [--expected S] [--actual S] [--logs S] [--agent A]
             [--environment local|cloud VM|CI|cloud agent sandbox|other]
             [--connection webhook|proxy|polling] [--yes]
@@ -293,9 +291,9 @@ Feedback
                                 confidential information: secrets, tokens, owner or pairing
                                 tokens, private URLs or hostnames, message contents, or
                                 personal data. Prints that warning and asks before sending,
-                                unless --yes is set. Off a terminal, --yes is required.
+                                unless --yes is set. Off a terminal, posting requires --yes.
                                 Posts when this A2A endpoint names a feedback URL.
-                                Otherwise prints a link to the bug
+                                Otherwise prints Not filed and a link to the bug
                                 report form and does not open a browser. The CLI adds its
                                 version, the A2A endpoint Worker version when the A2A endpoint reports it,
                                 the OS, the Node version, the connection (webhook, proxy, or
@@ -303,7 +301,7 @@ Feedback
                                 that detection. Remove tokens from the message and from --logs.
 
 Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
-         Which clients are tested end to end is in the client table:
+         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)`;
@@ -349,7 +347,7 @@ const deployOpts = {
 	"workers-dev": B, "workers-dev-subdomain": S, "upstream-token-stdin": B, "no-upstream-token": B, "event-secret-stdin": B,
 };
 const SPEC = {
-	hosted: { agent: 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: { 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, tunnel: tunnelOpts,
 	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 },
@@ -363,10 +361,11 @@ const SPEC = {
 	export: { sql: B },
 	upstream: { json: B },
 	connect: { alias: S, name: S, json: B, "no-wait": B, replace: B, force: B, "card-url": S },
+	// Internal hosted-service integration commands. Keep out of public help until the production flow is available.
 	signup: { "control-url": S, json: B },
 	login: { "control-url": S, json: B },
 	pair: { json: B, web: B, ttl: S, issuer: S, "client-id": S, subjects: S, methods: S, "secret-stdin": B },
-	feedback: { kind: S, contact: S, steps: S, expected: S, actual: S, logs: S, agent: S, environment: S, connection: S, yes: B },
+	feedback: { kind: S, contact: S, steps: S, expected: S, actual: S, logs: S, agent: S, environment: S, connection: S, yes: B, json: B },
 	uninstall: { yes: B, "dry-run": B, dir: S, "worker-dir": S },
 };
 const STATES = ["completed", "input-required", "failed", "rejected", "working"];
@@ -410,7 +409,7 @@ export async function main(argv) {
 		if (e && e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
 			const flag = (String(e.message).match(/'([^']+)'/) || [])[1] || "that flag";
 			if (flag === "-y") throw new CliError("unknown flag -y. To skip a prompt, pass --yes.");
-			throw new CliError(`unknown flag ${flag}. Run \`${CLI} ${name} --help\` for this command's flags.`);
+			throw new CliError(`unknown flag ${flag}. Run \`${CLI} --help\` and see the ${name} section.`);
 		}
 		if (e && String(e.code || "").startsWith("ERR_PARSE_ARGS")) throw new CliError(String(e.message));
 		throw e;
@@ -472,8 +471,8 @@ export async function main(argv) {
 			throw new CliError(`unknown peer action ${sub} (announce|forward)`);
 		}
 		case "hosted": {
-			if (p.length !== 2 || p[0] !== "link" || p[1] !== "finish") throw new CliError("usage: hosted link finish --agent NAME (--secret-file FILE | --secret-env VAR | --secret-from hermes)");
-			return finishLink({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") });
+			if (p.length !== 2 || p[0] !== "link" || !["finish", "create"].includes(p[1])) throw new CliError("usage: hosted link create --agent NAME --hostname HOST --origin URL --path PATH --preset ID (--secret-file FILE | --secret-env VAR | --secret-from hermes); or hosted link finish --agent NAME (--secret-file FILE | --secret-env VAR | --secret-from hermes)");
+			return (p[1] === "create" ? createLink : finishLink)({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") });
 		}
 		case "signup":
 		case "login": {
@@ -495,21 +494,22 @@ export async function main(argv) {
 		case "outbound": return cmd.outbound(need(p[0], "outbound <taskId>"));
 		case "feedback": {
 			const message = p.join(" ").trim();
-			need(message, `feedback "message" [--kind bug|idea|other] [--steps S] [--expected S] [--actual S] [--logs S] [--agent A] [--environment E] [--connection webhook|proxy|polling]`);
+			need(message, `feedback "message" [--json] [--kind bug|idea|other] [--steps S] [--expected S] [--actual S] [--logs S] [--agent A] [--environment E] [--connection webhook|proxy|polling]`);
 			const kind = o.kind || "other";
 			if (!fb.KINDS.includes(kind)) throw new CliError("--kind must be bug, idea, or other");
 			if (o.connection && !fb.CONNECTIONS.includes(o.connection)) throw new CliError("--connection must be webhook, proxy, or polling");
 			if (kind === "bug" && !String(o.steps || "").trim()) throw new CliError("a bug report needs reproduction steps (--steps)");
 			const repo = await fb.feedbackPublicRepo({ baseUrl: C.get("A2A_BASE_URL"), ownerToken: C.get("A2A_OWNER_TOKEN") });
-			await fb.confirmPublicIssue(Boolean(o.yes), undefined, undefined, repo);
 			const result = await fb.runFeedback({
+				beforePost: () => fb.confirmPublicIssue(Boolean(o.yes), undefined, undefined, repo),
 				message, kind, contact: o.contact || "", version: VERSION,
 				steps: o.steps || "", expected: o.expected || "", actual: o.actual || "", logs: o.logs || "",
 				agent: o.agent || "", environment: o.environment || "",
 				connection: o.connection || "",
 				baseUrl: C.get("A2A_BASE_URL"), ownerToken: C.get("A2A_OWNER_TOKEN"),
 			});
-			console.log(result.url);
+			if (!result.filed) console.error("Not filed: this A2A endpoint has no feedback inbox. Open this link to file it on GitHub:");
+			console.log(o.json ? JSON.stringify(result.filed ? { filed: true, issue: result.url } : result) : result.url);
 			return;
 		}
 		default: throw new CliError(`unknown command ${name} (see --help)`);

package/lib/script.mjs

@@ -0,0 +1,56 @@
+// Node's "pipe" stdin is a socket on macOS. BSD script refuses its ioctl
+// error, so relay stdin through a real shell pipe before allocating the PTY.
+import { spawn } from "node:child_process";
+
+export function spawnScript(args, options = {}) {
+	if (process.platform !== "darwin") return forwardShutdown(spawn("script", args, { ...options, detached: true, stdio: ["pipe", "pipe", "pipe"] }));
+	// All command arguments remain positional, never interpolated into shell code.
+	// fd 3 reports script completion so cat cannot keep the wrapper alive waiting
+	// for input. The terminal job cannot write that channel or inherit it.
+	const relay = '/bin/cat | { "$@" 3>&-; result=$?; printf "%s\\n" "$result" >&3; exit "$result"; }';
+	const child = spawn("/bin/sh", ["-c", relay, "a2a-script", "/usr/bin/script", ...args], {
+		...options, detached: true, stdio: ["pipe", "pipe", "pipe", "pipe"],
+	});
+	child.stdio[3].once("data", () => child.stdin.end());
+	child.stdio[3].resume();
+	child.stdin.on("error", () => {}); // script can exit just before an answer.
+	return forwardShutdown(child);
+}
+
+export function stopScript(child, signal = "SIGTERM") {
+	if (!child.pid) return false;
+	try {
+		// Stop the relay and script together. Closing the PTY master also hangs
+		// up the terminal job rather than leaving it waiting for an answer.
+		process.kill(-child.pid, signal);
+		return true;
+	} catch (error) {
+		if (error.code === "ESRCH") return false;
+		throw error;
+	}
+}
+
+// Detached PTYs do not receive the CLI's terminal signals. Forward shutdown
+// before allowing the parent's usual signal behavior, and release all hooks
+// on spawn failure or completion so repeated commands do not retain children.
+function forwardShutdown(child) {
+	const handlers = new Map();
+	const cleanup = () => {
+		for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+		process.removeListener("exit", onExit);
+	};
+	const onExit = () => stopScript(child);
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+		const handler = () => {
+			stopScript(child, signal);
+			cleanup();
+			if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+		};
+		handlers.set(signal, handler);
+		process.on(signal, handler);
+	}
+	process.on("exit", onExit);
+	child.once("error", cleanup);
+	child.once("close", cleanup);
+	return child;
+}

package/lib/workersdev.mjs

@@ -1,6 +1,6 @@
 // workers.dev support: URL helpers, cf output parsing, and registering the account's workers.dev subdomain
 // through cf's own interactive prompt (cf has no non-interactive command for it).
-import { spawn } from "node:child_process";
+import { spawnScript, stopScript } from "./script.mjs";
 import { CliError, die } from "./a2a.mjs";
 
 /** A valid DNS label: worker names and workers.dev subdomains must be one. */
@@ -65,12 +65,18 @@ export function deployWithRegistration(cfBin, args, name, { cwd, env, idleMs = 1
 	const penv = { ...env, TERM: env?.TERM || "xterm-256color", COLUMNS: "160", LINES: "50" };
 	delete penv.CI; // cf only prompts when interactive
 	return new Promise((resolve, reject) => {
-		const ch = spawn("script", sargs, { cwd, env: penv, stdio: ["pipe", "pipe", "pipe"] });
+		const ch = spawnScript(sargs, { cwd, env: penv });
 		// cf's prompts, in order; each is answered once, and only from output that arrived after the previous
 		// answer (prompt libraries re-render answered questions, which must not be answered twice)
 		const steps = REGISTRATION_STEPS(name);
-		let out = "", pending = "", stage = 0, failure = "";
-		const stop = (why) => { failure ||= why; ch.kill("SIGTERM"); };
+		let out = "", pending = "", stage = 0, failure = "", escalation;
+		const stop = (why) => {
+			if (failure) return;
+			failure = why;
+			stopScript(ch);
+			escalation = setTimeout(() => stopScript(ch, "SIGKILL"), 1000);
+			escalation.unref();
+		};
 		const arm = () => setTimeout(() => stop("cf stopped responding (unexpected prompt?)"), idleMs);
 		let idle = arm();
 		const onData = (d) => {
@@ -86,9 +92,10 @@ export function deployWithRegistration(cfBin, args, name, { cwd, env, idleMs = 1
 		};
 		ch.stdout.on("data", onData);
 		ch.stderr.on("data", onData);
-		ch.on("error", (e) => { clearTimeout(idle); reject(e); });
+		ch.on("error", (e) => { clearTimeout(idle); clearTimeout(escalation); reject(e); });
 		ch.on("close", (code) => {
 			clearTimeout(idle);
+			clearTimeout(escalation);
 			ch.stdin.destroy();
 			if (failure) return reject(new CliError(failure));
 			resolve({ status: code ?? 1, out });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.8.27",
+	"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/index.ts

@@ -2445,7 +2445,7 @@ async function deviceAuthorization(req: Request, ctx: TenantContext, ectx: Execu
 		if (!(await wakeBudgetOk(ctx))) return log("wake_skipped", { reason: "hourly cap", kind: "pairing_request" });
 		const identityFingerprint = identity ? await A.fingerprint(identity) : null;
 		await sendWake(ctx, ectx, { contextId: "pairing", taskId: "none", taskIds: [], from: clientName || clientId || "unknown agent", preview: "",
-			kind: "pairing_request", pairing: { userCode: shown, verificationUriComplete: complete, approval: mode, clientName, clientId, agentCardUrl: cardUrl,
+			kind: "pairing_request", pairing: { passwordSet: !!(await approvalPassword(ctx)), passwordEnabled: O.approvalPolicy(ctx.gates.approvalOidc).password, userCode: shown, verificationUriComplete: complete, approval: mode, clientName, clientId, agentCardUrl: cardUrl,
 				...(cardUrl && P.cardIsPrivate(cardUrl) ? { agentCardPrivate: true } : {}),
 				...(identityFingerprint ? { identityFingerprint } : {}), expiresIn: P.EXPIRES_S,
 				...(manage ? { manageUrl: manage } : {}),

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

package/worker/src/wake.ts

@@ -23,6 +23,8 @@ export type PairingInfo = {
 	agentCardUrl: string;
 	agentCardPrivate?: boolean; // the claimed card is on a private network (Tailnet, LAN): informational, not reachable
 	expiresIn: number;
+	passwordSet?: boolean; // readiness only; never the password or its hash
+	passwordEnabled?: boolean; // effective approval policy, including incomplete-OIDC fallback
 	/** Dashboard page for this agent. Present only when MANAGE_URL is an https URL. */
 	manageUrl?: string;
 	replacesLabel?: string; // re-pairing: the requester proved it holds this active token; approval replaces it
@@ -78,16 +80,18 @@ export function wakePayload(ev: WakeEvent, cli: string): Record<string, unknown>
 	};
 }
 
-/** What the woken agent must do with a pairing request: ask its human, never approve on its own. */
+/** What the woken agent must do with a pairing request: ask its owner, never approve on its own. */
 export function pairingInstructions(p: PairingInfo, cli: string): string {
+	const readiness = p.passwordSet === false && p.passwordEnabled !== false
+		? ` Approval password: not set. To approve pairing on /device with a password, run: ${cli} pair set-password --web. Send the one-time setup link privately to your human; they set the password themselves. Never open the page or ask for the password.` : "";
 	const dash = p.manageUrl ? ` The dashboard page for this request is ${p.manageUrl}.` : "";
 	return p.approval === "human"
 		? `Ask your human; never approve on your own. Show them the code ${p.userCode} and give them this link: ${p.verificationUriComplete} . ` +
 			`They approve there with their approval password, or with \`${cli} pair approve ${p.userCode}\` (the owner token), after checking the code with the other agent's owner. Deny with \`${cli} pair deny ${p.userCode}\`. Details: \`${cli} pair list\`.` +
-			dash
+			dash + readiness
 		: `Ask your human; never approve on your own. Show them the code ${p.userCode}, who is asking, and the link ${p.verificationUriComplete} . ` +
 			`Only if they say yes, run \`${cli} pair approve ${p.userCode}\`; if they say no (or don't answer), \`${cli} pair deny ${p.userCode}\`.` +
-			dash;
+			dash + readiness;
 }
 
 function hintFor(ev: WakeEvent, cli: string): string {

package/worker/test/pairing.test.ts

@@ -272,6 +272,8 @@ test("human approval: pending, slow_down, page approve with the password, single
 	assert.equal(w.pairing.agentCardUrl, "https://barry.example.org/.well-known/agent-card.json");
 	assert.equal("manageUrl" in w.pairing, false);
 	assert.match(w.pairing.instructions, /never approve on your own[\s\S]*give them this link/);
+	assert.equal(w.pairing.passwordSet, false);
+	assert.match(w.pairing.instructions, /Approval password: not set[\s\S]*pair set-password --web/);
 
 	let p = await s.poll(d.device_code);
 	assert.deepEqual([p.status, p.data.error, p.data.error_description], [400, "authorization_pending", "waiting for the agent owner to approve"]);
@@ -971,3 +973,38 @@ test("approval page shows the visitor's clock, and an https MANAGE_URL is on the
 	await bad.start(undefined, "203.0.113.82");
 	assert.equal("manageUrl" in bad.wakes[0].body.pairing, false);
 });
+
+test("pairing wake omits setup guidance once a password exists", async (t) => {
+	const s = setup(); t.after(s.restore);
+	await s.owner("PUT", "/owner/pairing/password", await passwordRecord());
+	assert.equal((await s.start()).status, 200);
+	const pairing = s.wakes[0].body.pairing;
+	assert.equal(pairing.passwordSet, true);
+	assert.doesNotMatch(pairing.instructions, /pair set-password|Approval password: not set/);
+	assert.doesNotMatch(JSON.stringify(s.wakes), /pbkdf2|correct horse|salt|hash/);
+});
+
+test("pairing readiness reaches text wakes without requester text on the trusted preset", async () => {
+	const ev: WakeEvent = { contextId: "pairing", taskId: "none", taskIds: [], from: "Untrusted", preview: "", kind: "pairing_request", publicUrl: BASE,
+		pairing: { userCode: "WDJB-2345", verificationUriComplete: `${BASE}/device?user_code=WDJB-2345`, approval: "human", clientName: "Untrusted", clientId: "untrusted", agentCardUrl: "", expiresIn: 3600, passwordSet: false } };
+	for (const preset of ["claude-code", "openclaw-wake", "openclaw-agent"]) {
+		const request = (await renderWake({ preset, url: "https://hook.example.net/wake", cliCommand: "a2a" }, ev))!;
+		const body = JSON.parse(request.body);
+		assert.match(body.text || body.message, /Approval password: not set[\s\S]*a2a pair set-password --web/);
+		if (preset === "openclaw-wake") assert.doesNotMatch(body.text, /Untrusted/);
+	}
+});
+
+for (const [name, config, enabled] of [
+	["OIDC only", { APPROVAL_METHODS: "oidc", APPROVAL_OIDC_ISSUER: "https://idp.example", APPROVAL_OIDC_CLIENT_ID: "client-1", APPROVAL_OIDC_CLIENT_SECRET: "dummy-secret", APPROVAL_OIDC_ALLOWED_SUBJECTS: "owner-1" }, false],
+	["incomplete OIDC fallback", { APPROVAL_METHODS: "oidc", APPROVAL_OIDC_ISSUER: "https://idp.example", APPROVAL_OIDC_CLIENT_ID: "client-1" }, true],
+	["password and OIDC", { APPROVAL_METHODS: "password,oidc", APPROVAL_OIDC_ISSUER: "https://idp.example", APPROVAL_OIDC_CLIENT_ID: "client-1", APPROVAL_OIDC_CLIENT_SECRET: "dummy-secret", APPROVAL_OIDC_ALLOWED_SUBJECTS: "owner-1" }, true],
+] as const) test(`pairing wake readiness respects ${name}`, async (t) => {
+	const s = setup(config); t.after(s.restore);
+	assert.equal((await s.start()).status, 200);
+	const pairing = s.wakes[0].body.pairing;
+	assert.equal(pairing.passwordSet, false);
+	assert.equal(pairing.passwordEnabled, enabled);
+	if (enabled) assert.match(pairing.instructions, /Approval password: not set[\s\S]*pair set-password --web/);
+	else assert.doesNotMatch(pairing.instructions, /Approval password: not set|pair set-password --web/);
+});