a2a-exposed 0.8.29 → 0.8.31

package/lib/account.mjs

@@ -38,6 +38,8 @@ async function readJson(response) {
 export async function deviceLogin({
 	controlUrl,
 	intent = "login",
+	scope = "",
+	machine = "",
 	fetchImpl = fetch,
 	sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 	write = (line) => console.error(line),
@@ -48,7 +50,8 @@ export async function deviceLogin({
 	const codeResponse = await fetchImpl(`${origin}/api/auth/device/code`, {
 		method: "POST",
 		headers: { "content-type": "application/json", accept: "application/json" },
-		body: JSON.stringify({ client_id: CLI_CLIENT_ID }),
+		redirect: "error", signal: AbortSignal.timeout(30_000),
+		body: JSON.stringify({ client_id: CLI_CLIENT_ID, ...(scope ? { scope, machine } : {}) }),
 	});
 	const started = await readJson(codeResponse);
 	if (!codeResponse.ok || !started.device_code || !started.user_code || !started.verification_uri_complete) {
@@ -57,7 +60,11 @@ export async function deviceLogin({
 			? `login is not turned on at ${origin}`
 			: `could not start sign-in at ${origin} (${reason})`);
 	}
+	let verification;
+	try { verification = new URL(started.verification_uri_complete); } catch { die("invalid sign-in approval URL"); }
+	if (verification.origin !== origin || verification.username || verification.password || !/^[A-Za-z0-9-]{4,32}$/.test(started.user_code)) die("invalid sign-in approval URL or comparison code");
 	const verb = intent === "signup" ? "Create an account and approve" : "Sign in and approve";
+	if (scope) write(`Hosted setup access\nMachine: ${machine}\nPermissions: ${scope.split(" ").join(", ")}`);
 	write(`${verb} this code:\n${started.user_code}\n${started.verification_uri_complete}`);
 	const interval = Math.max(1, Number(started.interval) || 5);
 	const deadline = Date.now() + Math.max(1, Number(started.expires_in) || 600) * 1000;
@@ -66,11 +73,18 @@ export async function deviceLogin({
 		await sleep(wait * 1000 * scale());
 		const tokenResponse = await fetchImpl(`${origin}/api/auth/device/token`, {
 			method: "POST",
+			redirect: "error", signal: AbortSignal.timeout(30_000),
 			headers: { "content-type": "application/json", accept: "application/json" },
 			body: JSON.stringify({ grant_type: DEVICE_GRANT, device_code: started.device_code, client_id: CLI_CLIENT_ID }),
 		});
 		const body = await readJson(tokenResponse);
 		if (tokenResponse.ok && typeof body.access_token === "string" && body.access_token) {
+			if (scope) {
+				if (!/^a2asg_[a-f0-9]{64}$/.test(body.access_token) || body.scope !== scope) die("invalid hosted setup grant response; start approval again");
+				save({ HOSTED_SETUP_URL: origin, HOSTED_SETUP_TOKEN: body.access_token, HOSTED_SETUP_SCOPES: scope, HOSTED_SETUP_MACHINE: machine });
+				write("Hosted setup approved. Credential saved privately.");
+				return { controlUrl: origin, email: "" };
+			}
 			save({ CONTROL_URL: origin, CONTROL_TOKEN: body.access_token });
 			const sessionResponse = await fetchImpl(`${origin}/api/auth/get-session`, {
 				headers: { accept: "application/json", authorization: `Bearer ${body.access_token}` },

package/lib/config.mjs

@@ -54,6 +54,12 @@ export function get(key, dflt = "") {
 	return f !== undefined && f !== "" ? f : dflt;
 }
 
+/** Config type, without network or Cloudflare calls. Partial self-hosted metadata stays self-hosted. */
+export function deploymentKind() {
+	if (get("A2A_WORKER_NAME") || get("A2A_D1_ID")) return "self-hosted";
+	return get("A2A_BASE_URL") && get("A2A_OWNER_TOKEN") ? "hosted" : "none";
+}
+
 /** Resolve a control credential with the origin from the same source.
  * A partial environment override must never borrow saved credentials.
  */

package/lib/hosted.mjs

@@ -0,0 +1,202 @@
+// Hosted setup credentials never leave their origin or appear in command output.
+import fs from "node:fs";
+import * as C from "./config.mjs";
+import { controlOrigin, deviceLogin } from "./account.mjs";
+import { CliError, upstreamUrlProblem } from "./a2a.mjs";
+
+export const SETUP_SCOPES = ["agents:create", "agents:owner-token", "wake:write", "wake:test"];
+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; };
+const printable = value => typeof value === "string" && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value);
+
+export function setupSession(env = process.env, saved = C.fileConfig()) {
+	const source = env.HOSTED_SETUP_URL || env.HOSTED_SETUP_TOKEN ? env : saved;
+	return { origin: controlOrigin(source.HOSTED_SETUP_URL), token: source.HOSTED_SETUP_TOKEN || "" };
+}
+
+function originFor(o = {}) {
+	const origin = controlOrigin(o["control-url"] || setupSession().origin || C.controlSession().origin || "https://a2a.exposed");
+	if (!origin) fail("control_url", "--control-url must be an HTTPS origin without a path or credentials.");
+	return origin;
+}
+
+async function request(origin, path, { token = "", method = "GET", body, fetchImpl = fetch } = {}) {
+	let response, data;
+	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) }),
+		});
+		data = await response.json();
+	} 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 (!data || typeof data !== "object" || Array.isArray(data)) fail("invalid_response", "The hosted service returned an invalid setup response.");
+	if (!response.ok) {
+		const known = ["taken", "limit", "invalid_name", "reserved_name", "invalid_grant", "insufficient_scope", "conflict", "unavailable", "not_found", "test", "signing", "unreadable", "preset", "url", "header", "access", "invalid_reference"];
+		const code = known.includes(data.error) ? data.error : `http_${response.status}`;
+		const next = code === "taken" || code === "reserved_name" ? "Choose another --name and run hosted list --json before creating."
+			: code === "limit" ? "The account is at its agent limit. Review hosted list --json and account plans."
+			: 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
+			: "Hosted setup refused the request. Run hosted capabilities --json and check the inputs; no automatic retry was made.";
+		fail(code, next);
+	}
+	return data;
+}
+
+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", "This service does not expose hosted setup capabilities yet.");
+	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)), secret_reference: data.wake.secret_reference === true, secure_link_create: data.wake.secure_link_create === true };
+}
+
+export async function login(o = {}) {
+	const origin = originFor(o), machine = o.machine || "";
+	if (!machine.trim() || machine.length > 80 || !printable(machine)) fail("machine", "Pass --machine NAME (1–80 printable characters). " + NEXT);
+	const scopes = [...new Set(String(o.scopes || "").split(/[ ,]+/).filter(Boolean))];
+	if (!scopes.length || scopes.some(s => !SETUP_SCOPES.includes(s))) fail("scope", "Pass --scopes with choices from hosted capabilities --json.");
+	const available = await capabilities({ "control-url": origin });
+	if (scopes.some(s => !available.scopes.includes(s))) fail("unsupported_scope", NEXT);
+	await deviceLogin({ controlUrl: origin, scope: scopes.join(" "), machine: machine.trim(), save: updates => C.saveConfig(updates) });
+	return { ok: true, code: "approved", next: "Run hosted list --json, then hosted create --name NAME --json.", control_url: origin };
+}
+
+function accountCredential(o) {
+	const session = setupSession(), origin = originFor(o);
+	if (!session.token || session.origin !== origin) fail("login_required", NEXT);
+	return { origin, token: session.token };
+}
+
+export async function list(o = {}) {
+	const { origin, token } = accountCredential(o);
+	const data = await request(origin, "/api/v1/tenants", { token });
+	if (!Array.isArray(data.tenants)) fail("invalid_response", "The service did not return an agent listing.");
+	return { ok: true, code: "agents", next: "This listing contains hosted agents only; Cloudflare-linked Workers remain in dashboard Your agents. Select an agent, or run hosted create --name NAME --json.", agents: data.tenants.map(row => ({ name: String(row.name || ""), status: String(row.status || ""), version: row.version })) };
+}
+
+export async function create(o = {}) {
+	const name = String(o.name || "").trim().toLowerCase();
+	if (!/^[a-z0-9][a-z0-9-]{2,30}[a-z0-9]$/.test(name)) fail("invalid_name", "Pass --name with 4–32 letters, numbers or hyphens, starting and ending with a letter or number. Run hosted list --json first.");
+	// Never replace an existing deployment or an environment-selected credential.
+	if (C.get("A2A_BASE_URL") || C.get("A2A_OWNER_TOKEN") || C.get("A2A_WORKER_NAME") || C.get("A2A_D1_ID")) fail("config_in_use", "Use --config-dir with a separate directory for the new agent; keep the existing deployment configuration.");
+	const { origin, token } = accountCredential(o);
+	const before = await list(o);
+	if (before.agents.some(row => row.name === name && row.status !== "deleted")) fail("taken", "That name already belongs to this account. Select it from hosted list --json or choose another --name.");
+	const data = await request(origin, "/api/v1/tenants", { token, method: "POST", body: { name } });
+	const base = data.base_url || data.public_url;
+	if (data.name !== name || !/^a2aot_[A-Za-z0-9_-]{43}$/.test(data.owner_token || "") || !controlOrigin(base)) fail("invalid_response", "Creation returned an invalid credential response. Check hosted list --json before retrying; the agent may already exist.");
+	try { C.saveConfig({ A2A_BASE_URL: base, A2A_OWNER_TOKEN: data.owner_token, HOSTED_AGENT_NAME: name, HOSTED_SETUP_URL: origin }); }
+	catch { fail("credential_save", "The agent was created, but its one-time credential could not be saved. Do not create it again. Use the agent's account page to recover access."); }
+	return { ok: true, code: "created", next: "Run wake set with an explicit URL and preset, reading credentials from protected files or named environment variables.", name, base_url: base };
+}
+
+function secret(o, name, envName) {
+	const file = o[`${name}-file`], env = o[`${name}-env`], stdin = name === "key" && o["key-stdin"];
+	if ([file, env, stdin].filter(Boolean).length > 1) fail("secret_source", `Choose one --${name}-file or --${name}-env${name === "key" ? " or --key-stdin" : ""}.`);
+	let value = "";
+	try {
+		if (file) {
+			const stat = fs.lstatSync(file);
+			if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) || stat.size > 4098) fail("secret_file", `--${name}-file needs a regular protected file (chmod 600), at most 4098 bytes.`);
+			value = fs.readFileSync(file, "utf8").replace(/\r?\n$/, "");
+		} else if (stdin) {
+			if (process.stdin.isTTY) fail("secret_stdin", "Pipe the key on stdin; terminal prompts are not supported.");
+			value = fs.readFileSync(0, "utf8").replace(/\r?\n$/, "");
+		} else value = process.env[env || envName] || "";
+	} catch (error) { if (error.result) throw error; fail("secret_file", `Could not read --${name}-file; check its path and permissions.`); }
+	if (!printable(value) || ((file || env || stdin) && !value)) fail("secret_input", `The ${name} credential must contain 1–4096 printable characters.`);
+	return value;
+}
+
+function wakeCredential(o, preferOwner = false) {
+	const origin = originFor(o), session = setupSession();
+	let name = o.agent || C.get("HOSTED_AGENT_NAME");
+	// Deployment halves come from one source, independently of setup selection.
+	const saved = C.fileConfig();
+	const source = process.env.A2A_BASE_URL || process.env.A2A_OWNER_TOKEN ? process.env : saved;
+	const owner = source.A2A_OWNER_TOKEN || "", base = source.A2A_BASE_URL || "";
+	if (!name && base) { try { name = new URL(base).hostname.split(".")[0]; } catch {} }
+	if (!/^[a-z0-9][a-z0-9-]{2,30}[a-z0-9]$/.test(name || "")) fail("agent", "Pass --agent NAME selected from hosted list --json.");
+	// An explicit agent must not borrow a different agent's owner token.
+	let ownerOrigin = "";
+	if (controlOrigin(base)) {
+		const parsed = new URL(base);
+		if (parsed.hostname.startsWith(`${name}.`)) ownerOrigin = controlOrigin(`${parsed.protocol}//${parsed.host.slice(name.length + 1)}`);
+	}
+	const ownerMatches = owner && base && ownerOrigin === origin && controlOrigin(base) && new URL(base).hostname.split(".")[0] === name;
+	const token = preferOwner && ownerMatches ? owner : session.origin === origin && session.token ? session.token : ownerMatches ? owner : "";
+	if (!token) fail("login_required", NEXT);
+	return { origin, token, name };
+}
+
+// A webhook path or query may contain its credential. Show only the public destination.
+function previewUrl(value) {
+ try { const url = new URL(value); return url.protocol === "https:" && !url.username && !url.password ? `${url.origin}${url.pathname === "/" ? "/" : "/…"}` : ""; }
+ catch { return ""; }
+}
+
+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 === "remove" || sub === "unset") fail("unsupported", "This hosted API does not support wake removal yet. Remove it in the agent's Wake settings; saved settings were not changed.");
+	if (sub === "prepare") {
+		if (!o["reference-file"]) fail("reference_file", "Pass a new --reference-file FILE. The reference is saved mode 600 and never printed.");
+		try { fs.lstatSync(o["reference-file"]); fail("reference_file", "Choose a new --reference-file path; existing files are never replaced."); }
+		catch (error) { if (error.result) throw error; if (error.code !== "ENOENT") fail("reference_file", "Cannot inspect --reference-file; check its path and permissions."); }
+	}
+	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 === "set" && (o["reference-file"] || o["reference-env"])) {
+		if (o.url || o.preset || o["key-file"] || o["key-env"] || o["key-stdin"] || o["hmac-secret-file"] || o["hmac-secret-env"]) fail("reference_inputs", "Use a reference without draft overrides; it saves exactly the uploaded settings.");
+		const reference = secret(o, "reference", "");
+		if (!/^a2awr_[a-f0-9]{64}$/.test(reference)) fail("invalid_reference", "Read a valid reference from a protected --reference-file or --reference-env.");
+		const result = await request(origin, path, { token, method: "PUT", body: { version: current.version, secretReference: reference } });
+		return { ok: result.ok === true && result.saved === true, code: result.saved === true ? "saved" : "failed", saved: result.saved === true, next: result.saved === true ? "Check the receiver for the test wake." : "The reference is spent. Check saved settings before preparing another draft." };
+	}
+	const url = o.url || process.env.WAKE_WEBHOOK_URL || current.url;
+	const preset = o.preset || current.preset || "generic";
+	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 });
+	if (!available.presets.includes(preset)) fail("preset", "Select --preset from hosted capabilities --json.");
+	const draft = { version: current.version, url, preset, keyHeader: o["key-header"] ?? current.keyHeader ?? "", key: secret(o, "key", "WAKE_WEBHOOK_KEY"), hmacSecret: secret(o, "hmac-secret", "WAKE_HMAC_SECRET"), accessClientId: secret(o, "access-client-id", "WAKE_ACCESS_CLIENT_ID"), accessClientSecret: secret(o, "access-client-secret", "WAKE_ACCESS_CLIENT_SECRET") };
+	if (Boolean(draft.accessClientId) !== Boolean(draft.accessClientSecret)) fail("access", "Supply both Access credentials through protected files or named environment variables.");
+	let body = draft;
+	if (sub === "prepare" || (sub === "set" && available.secret_reference && token.startsWith("a2asg_"))) {
+		if (!available.secret_reference) fail("unsupported", "This service does not support wake references. Use wake set or browser confirmation.");
+		if (sub === "prepare" && !o["reference-file"]) fail("reference_file", "Pass a new --reference-file FILE. The reference is saved mode 600 and never printed.");
+		const prepared = await request(origin, `${path}/reference`, { token, method: "POST", body: draft });
+		if (!/^a2awr_[a-f0-9]{64}$/.test(prepared.reference || "")) fail("invalid_response", "The service did not return a valid reference. No wake was saved.");
+		if (sub === "prepare") {
+			try { fs.writeFileSync(o["reference-file"], prepared.reference + "\n", { mode: 0o600, flag: "wx" }); }
+			catch { fail("reference_file", "Cannot create --reference-file. Choose a new path in a private directory; existing files are never replaced."); }
+			return { ok: true, code: "prepared", next: "Use the protected reference with wake set --reference-file FILE, or MCP set_wake secretReference and the same draft settings, within ten minutes. It is single-use even when a test fails." };
+		}
+		body = { version: current.version, secretReference: prepared.reference };
+	}
+	const result = await request(origin, sub === "test" ? `${path}/test` : path, { token, method: sub === "test" ? "POST" : "PUT", body });
+	// Do not print proofs, arbitrary service text, webhook URLs or unexpected fields.
+	const code = typeof result.code === "string" && /^(?:[1-5][0-9]{2}|access-40[13]|none|timeout|tls|private|dns|dns-missing|transport-delivery|transport-native|transport-socket|cloudflare-target-unsupported|connection|failed|unreadable|signing)$/.test(result.code) ? result.code : result.saved === true ? "saved" : "failed";
+	const ok = result.ok === true && (sub !== "set" || result.saved === true);
+	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." : code === "cloudflare-target-unsupported" ? "Use polling or a self-hosted Worker for this Cloudflare-proxied webhook." : "Saved settings were not changed. Check the receiver, credentials and draft, then test again." };
+}
+
+export async function output(run, o = {}) {
+	try {
+		const result = await run();
+		if (o.json) console.log(JSON.stringify(result));
+		else {
+			console.log(`${result.code}: ${result.next}`);
+			for (const [key, value] of Object.entries(result)) {
+				if (!["ok", "code", "next"].includes(key)) console.log(`${key}: ${JSON.stringify(value, null, 2)}`);
+			}
+		}
+		if (!result.ok) process.exitCode = 1;
+	} catch (error) {
+		const result = error.result || { ok: false, code: "unavailable", next: "Hosted setup did not finish. Check hosted list --json before retrying." };
+		console.log(o.json ? JSON.stringify(result) : `${result.code}: ${result.next}`);
+		process.exitCode = 1;
+	}
+}

package/lib/layers.mjs

@@ -61,15 +61,16 @@ function workerDnsLayer(f) {
 }
 
 function workerLayer(f) {
+	const fix = f.deployment === "hosted" ? "check the hosted service and saved A2A_BASE_URL; run status again" : `${CLI} deploy`;
 	if (!f.baseUrl) return layer("Worker", "SKIP", "not checked (no base URL)");
 	const https = /^https:/i.test(f.baseUrl);
 	const card = f.card || { ok: false, error: "not checked" };
 	if (https && card.error && TLS_RE.test(card.error))
 		return layer("Worker", "FAIL", `Likely mismatched: TLS certificate for ${f.host}. ${card.error}`, `check the certificate for ${f.host} in Cloudflare (SSL/TLS)`);
 	if (!card.ok)
-		return layer("Worker", "FAIL", `Likely missing: deployed Worker. Agent card: ${card.error || "unreachable"}`, `${CLI} deploy`);
+		return layer("Worker", "FAIL", `Likely missing: deployed Worker. Agent card: ${card.error || "unreachable"}`, fix);
 	if (card.urlProblem)
-		return layer("Worker", "FAIL", `Likely mismatched: agent card URL. ${card.urlProblem}`, `${CLI} deploy`);
+		return layer("Worker", "FAIL", `Likely mismatched: agent card URL. ${card.urlProblem}`, fix);
 	const tls = https ? "TLS ok" : "TLS skipped (not https)";
 	const named = card.name ? ` ("${card.name}")` : "";
 	const cardBit = `${tls}; agent card HTTP ${card.httpStatus || 200}${named}`;
@@ -80,7 +81,7 @@ function workerLayer(f) {
 			: h.httpStatus < 200 || h.httpStatus >= 300
 				? `/health HTTP ${h.httpStatus}`
 				: `/health HTTP ${h.httpStatus} did not report ok`;
-		return layer("Worker", "FAIL", `Likely missing: Worker /health. ${cardBit}; ${problem}`, `${CLI} deploy`);
+		return layer("Worker", "FAIL", `Likely missing: Worker /health. ${cardBit}; ${problem}`, fix);
 	}
 	return layer("Worker", "PASS", `${cardBit}; /health HTTP ${h.httpStatus || 200}`);
 }
@@ -91,6 +92,7 @@ function ownerLayer(f) {
 	if (f.ownerApi && f.ownerApi.ok) return layer("Owner API", "PASS", "owner token accepted");
 	const err = (f.ownerApi && f.ownerApi.error) || "not checked";
 	if (err === "not checked") return layer("Owner API", "SKIP", "not checked");
+	if (f.deployment === "hosted") return layer("Owner API", "FAIL", `hosted owner credential check failed: ${err}`, "check hosted agent access with its owner");
 	if (/HTTP 401/.test(err)) return layer("Owner API", "FAIL", "Likely mismatched: owner token", `${CLI} init --rotate-owner-token`);
 	return layer("Owner API", "FAIL", `Likely missing: deployed Worker. ${err}`, `${CLI} deploy`);
 }

package/lib/link-finish.mjs

@@ -228,8 +228,14 @@ async function setupLink(o, {
 	}
 	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, "grant");
-	if (tested.body.result !== "ok" || tested.body.saved !== true) {
+	// These 409 codes come from saveWakeSettings after a successful wake test.
+	const saveRejected = tested.response.status === 409 && ["url", "preset", "header", "key", "unavailable", "unreadable", "conflict", "failed"].includes(tested.body.error);
+	if (!tested.response.ok && !saveRejected) throw failure(tested.response.status, tested.body, context, "grant");
+	if (saveRejected || (tested.body.result === "ok" && tested.body.saved !== true)) {
+		write("wake_result=not-saved");
+		throw new CliError("The test wake was delivered, but the settings were not saved. Save them in Wake settings on the website, then test again. The saved connector token remains on disk.");
+	}
+	if (tested.body.result !== "ok") {
 		const { result, message } = wakeFailure(tested.body.result);
 		write(`wake_result=${result}`);
 		throw new CliError(message);

package/lib/main.mjs

@@ -9,6 +9,7 @@ import * as st from "./status.mjs";
 import * as pair from "./pair.mjs";
 import * as address from "./address.mjs";
 import * as account from "./account.mjs";
+import * as hosted from "./hosted.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
 import * as un from "./uninstall.mjs";
@@ -25,6 +26,28 @@ Usage: npx -y a2a-exposed@latest <command> [options]
 
 Setup options: --skip-install skips dependency installation when dependencies already exist.
 
+Hosted setup:
+  hosted capabilities --json   list setup scopes, wake presets and service capabilities
+  login --machine NAME --scopes SCOPES [--control-url URL] --json
+                                approve the explicit scopes using the printed website link once;
+                                save the scoped grant locally (mode 600), never print it
+  hosted list --json           list hosted agents before choosing --name or --agent
+  hosted create --name NAME --json
+                                create and save the owner credential in this config directory;
+                                use a separate --config-dir for each agent
+  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,
+                                --access-client-id-file, --access-client-id-env and --access-client-secret-file, --access-client-secret-env
+  wake prepare --agent NAME --url URL --preset P --reference-file FILE --json
+                                when the service lists secret_reference, upload the draft and save a
+                                ten-minute single-use reference in a new protected file; never print it
+  wake set --agent NAME --reference-file FILE --json
+                                test and save exactly that reference's draft; --reference-env VAR also works
+                                MCP set_wake accepts secretReference on services listing that capability
+  Hosted wake removal uses the agent's Wake settings on the website.
+  Listings and previews show result fields; --json provides structured output.
+
 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
@@ -155,6 +178,7 @@ Remove
                                 --dir and --worker-dir are the Worker project directory (default <config dir>/worker)
 
 Status
+  Hosted-only configs report deployment: hosted and hosted recovery guidance.
   status [--json]               deployment, Worker version, base URL, agent card check (fetched by the CLI), wake
                                 mode (webhook / tunnel / none = polling), tunnel state, proxy mode (--upstream):
                                 upstream card, Access credential and upstream bearer configured (separately), the
@@ -308,6 +332,8 @@ Update notice: at most a daily background check of the npm registry; off with A2
 
 const HELP_TUNNEL = `tunnel create|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]
                                 Named Cloudflare Tunnel, proxied DNS, and an Access app that admits one service token.
@@ -327,6 +353,7 @@ const HELP_TUNNEL = `tunnel create|status|rm
 
 const HELP_UNINSTALL = `uninstall [--yes] [--dry-run] [--dir DIR | --worker-dir DIR]
 
+Self-hosted only. Hosted agents are deleted through hosted settings and confirmation.
 Remove the Worker, the wake tunnel when the config has one, and the D1 database.
 Prints the plan first: Worker name, D1 name and id, account, and the wake hostname
 when a tunnel is saved. Removal is permanent and takes the messages and paired peers with it.
@@ -347,8 +374,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: { 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,
+	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 },
+	init: { ...deployOpts, ...tunnelOpts, tunnel: B }, deploy: deployOpts,
+	wake: { ...deployOpts, json: B, url: S, "reference-file": S, "reference-env": 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,
 	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 },
@@ -363,7 +391,7 @@ const SPEC = {
 	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 },
+	login: { "control-url": S, json: B, machine: S, scopes: S },
 	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, json: B },
 	uninstall: { yes: B, "dry-run": B, dir: S, "worker-dir": S },
@@ -440,7 +468,7 @@ export async function main(argv) {
 			if (sub === "verify" || sub === "check") return st.upstreamVerify(o);
 			throw new CliError(`unknown upstream action ${sub} (verify)`);
 		}
-		case "wake": return dep.wake(p[0], o);
+		case "wake": return C.deploymentKind() === "hosted" || o.agent ? hosted.output(() => hosted.wake(p[0], o), o) : dep.wake(p[0], o);
 		case "url": {
 			const u = cmd.baseUrl();
 			if (!u) throw new CliError(`no base URL configured in ${C.CONFIG_FILE}: run \`${CLI} init\` (or pass --config-dir / A2A_CONFIG_DIR for another deployment)`);
@@ -471,11 +499,13 @@ export async function main(argv) {
 			throw new CliError(`unknown peer action ${sub} (announce|forward)`);
 		}
 		case "hosted": {
+			if (p.length === 1 && ["capabilities", "list", "create"].includes(p[0])) return hosted.output(() => hosted[p[0]](o), o);
 			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": {
+			if (o.machine || o.scopes) return hosted.output(() => hosted.login(o), o);
 			const result = await account.deviceLogin({ controlUrl: o["control-url"] || C.get("CONTROL_URL"), intent: name });
 			if (o.json) console.log(JSON.stringify({ control_url: result.controlUrl, email: result.email }));
 			return;

package/lib/status.mjs

@@ -275,7 +275,7 @@ export function secretsPropagating(tunnel, now = Date.now()) {
 export function nextStep(s) {
 	const n = nextStepCore(s);
 	const version = s.cliVersion || D.VERSION;
-	if (s.workerVersion && s.latestVersion && newer(s.latestVersion, s.workerVersion) && !newer(s.workerVersion, version))
+	if (s.deployment !== "hosted" && s.workerVersion && s.latestVersion && newer(s.latestVersion, s.workerVersion) && !newer(s.workerVersion, version))
 		n.also.push(`a2a-exposed ${s.latestVersion} is available: run npx -y a2a-exposed@latest deploy`);
 	const sh = (s.peerTokenShadowed || []).map((k) => `${k} is set in the environment and overrides the different peer token saved in ${s.configFile} (e.g. a stale value from before \`connect\` stored a new one): send/poll use the environment value. Unset ${k} where it is set to use the saved token`);
 	const addr = s.addresses;
@@ -289,6 +289,16 @@ export function nextStep(s) {
 function nextStepCore(s) {
 	const fail = (text) => ({ ok: false, text, also: [] });
 	const done = (text, also = []) => ({ ok: true, text, also });
+	if (s.deployment === "hosted") {
+		if (!s.card.ok) return fail(`the hosted agent card is not reachable (${s.card.error}). Run \`${CLI} status\` again; if it still fails, check the hosted service and the saved A2A_BASE_URL.`);
+		if (s.card.urlProblem) return fail(`the hosted agent card has a different endpoint: ${s.card.urlProblem}. Check the address with the hosted service.`);
+		if (!s.health?.ok) return fail("the hosted health check failed. Check the hosted service and run status again.");
+		if (!s.ownerApi.ok) return fail("the hosted owner API refused or could not check the saved credential. Check the hosted agent access with its owner.");
+		if (!s.wake) return done("the hosted endpoint is reachable and its owner credential is accepted. Wake preview is unavailable; check wake delivery through the hosted service.");
+		return done(s.wake?.configured
+			? "none: the hosted endpoint is reachable and its owner credential is accepted. Check wake delivery through the hosted service."
+			: "the hosted endpoint is reachable. Configure a public HTTPS webhook through the hosted service, or use polling. Cloudflare Tunnel delivery may be unavailable; do not provision a self-hosted tunnel for this address.");
+	}
 	if (!s.deployed) return fail(`nothing is deployed from ${path.dirname(s.configFile)}. Run \`${CLI} init\` (see the quick start). Another deployment? Set A2A_CONFIG_DIR.`);
 	if (s.baseUrlEnv)
 		return fail(`A2A_BASE_URL is exported as ${s.baseUrlEnv}, but ${s.configFile} has ${s.baseUrlSaved || "(none)"}: CLI commands (and push URLs sent to peers) use the exported value. Unset A2A_BASE_URL (the A2A endpoint URL is always the deployment's own)`);
@@ -392,7 +402,7 @@ function hostOf(url) {
 function layerFacts(s, extra) {
 	const t = s.tunnel;
 	return {
-		deployed: s.deployed, baseUrl: s.baseUrl || "", host: extra.host || "", platform: process.platform,
+		deployed: s.deployed, deployment: s.deployment, baseUrl: s.baseUrl || "", host: extra.host || "", platform: process.platform,
 		workerDns: extra.workerDns, card: s.card, health: s.health, hasOwnerToken: s.hasOwnerToken, ownerApi: s.ownerApi,
 		wakeHost: extra.wakeHost || "", wakeDns: extra.wakeDns, bare: extra.bare, authed: extra.authed,
 		serviceToken: extra.serviceToken, localServiceToken: extra.localServiceToken, pairing: s.pairing,
@@ -445,6 +455,7 @@ function finishLayers(s, extra) {
 export async function collect(net = {}) {
 	const s = {
 		configFile: C.CONFIG_FILE,
+		deployment: C.deploymentKind(),
 		deployed: !!(C.get("A2A_D1_ID") && C.get("A2A_WORKER_NAME")),
 		worker: C.get("A2A_WORKER_NAME"), d1: C.get("A2A_D1_NAME"), account: C.get("CLOUDFLARE_ACCOUNT_ID"), cfProfile: C.get("CF_PROFILE"),
 		baseUrl: baseUrl(), urlKind: C.get("A2A_HOSTNAME") ? "custom domain" : "workers.dev", cron: C.get("A2A_ENABLE_CRON") === "1",
@@ -455,6 +466,7 @@ export async function collect(net = {}) {
 		peerTokenShadowed: shadowedPeerTokens(), addresses: null,
 		mcp: "unknown", health: null, workerVersion: null, cliVersion: D.VERSION, latestVersion: readCache(cacheFile())?.latest || null,
 	};
+	if (s.deployment === "hosted") { s.deployed = true; s.urlKind = "hosted"; }
 	const envBase = (process.env.A2A_BASE_URL || "").replace(/\/$/, "");
 	if (envBase && envBase !== s.baseUrlSaved) s.baseUrlEnv = envBase;
 	if (!s.deployed || !s.baseUrl) return finishLayers(s, { host: "", workerDns: { kind: "skip" }, wakeHost: "", wakeDns: { kind: "skip" }, bare: null, authed: null });
@@ -470,7 +482,13 @@ export async function collect(net = {}) {
 				s.ownerApi = { ok: true };
 				s.wake = { preset: p.preset, configured: !!p.configured, hasKey: !!p.hasKey, hasHmacSecret: !!p.hasHmacSecret,
 					hasAccessServiceToken: !!p.hasAccessServiceToken, urlFingerprint: p.fingerprints?.url || null };
-			} catch (e) { s.ownerApi = { ok: false, error: e.message }; }
+			} catch (e) {
+				s.ownerApi = { ok: false, error: e.message };
+				if (s.deployment === "hosted" && /HTTP (404|405)\b/.test(e.message)) {
+					try { await owner("GET", "/owner/summary"); s.ownerApi = { ok: true }; }
+					catch (summaryError) { s.ownerApi = { ok: false, error: summaryError.message }; }
+				}
+			}
 			if (s.ownerApi.ok) {
 				try {
 					const pr = await owner("GET", "/owner/pairing");
@@ -496,6 +514,7 @@ export async function collect(net = {}) {
 				} catch { /* probe failed: leave mcp unknown so status omits the add line */ }
 			}
 		}
+		if (s.deployment === "hosted") return;
 		const dir = D.workerDir({});
 		const haveCf = fs.existsSync(dir);
 		const tunnelHost = C.get("A2A_TUNNEL_HOSTNAME");
@@ -577,7 +596,7 @@ export async function status(o) {
 	else {
 		const rows = [
 			["config", s.configFile],
-			["deployment", s.deployed ? `Worker ${s.worker}, D1 ${s.d1 || s.worker}${s.account ? `, account ${s.account}` : ""}${s.cfProfile ? `, cf profile ${s.cfProfile}` : ""}${s.cron ? ", cron flush on" : ""}` : "none"],
+			["deployment", s.deployment === "hosted" ? "hosted" : s.deployed ? `Worker ${s.worker}, D1 ${s.d1 || s.worker}${s.account ? `, account ${s.account}` : ""}${s.cfProfile ? `, cf profile ${s.cfProfile}` : ""}${s.cron ? ", cron flush on" : ""}` : "none"],
 			["base URL", s.baseUrl ? `${s.baseUrl} (${s.baseUrlEnv ? `from the exported A2A_BASE_URL; ${s.configFile} has ${s.baseUrlSaved || "none"}` : s.urlKind})` : "(not saved)"],
 		];
 		if (s.deployed && s.baseUrl) {

package/lib/tunnel.mjs

@@ -254,7 +254,12 @@ export function cfWorkDir(preferred) {
 	return base;
 }
 
+function refuseHosted() {
+	if (C.deploymentKind() === "hosted") die("this is a hosted config. tunnel provisions a self-hosted Worker only. Configure a public HTTPS webhook through the hosted service, or use polling if Cloudflare Tunnel delivery is unavailable. Check `status --json` first.");
+}
+
 function needDeployment(o) {
+	refuseHosted();
 	if (!C.get("A2A_D1_ID") || !C.get("A2A_WORKER_NAME")) die(`nothing is deployed from ${C.CONFIG_DIR}. Another deployment? Set A2A_CONFIG_DIR.`);
 	const dir = D.workerDir(o);
 	if (!fs.existsSync(dir)) die(`worker project not found at ${dir}; run \`${CLI} deploy\` once`);
@@ -263,6 +268,7 @@ function needDeployment(o) {
 
 /** `cf` cwd for `tunnel rm` / `uninstall`. A missing Worker project uses a temp directory with a writable cache. */
 function cfDirForRemove(o, { allowMissingProject = false } = {}) {
+	refuseHosted();
 	if (!C.get("A2A_D1_ID") || !C.get("A2A_WORKER_NAME")) die(`nothing is deployed from ${C.CONFIG_DIR}. Another deployment? Set A2A_CONFIG_DIR.`);
 	const dir = D.workerDir(o);
 	if (!fs.existsSync(dir) && !allowMissingProject) die(`worker project not found at ${dir}; run \`${CLI} deploy\` once`);
@@ -475,6 +481,7 @@ export function bareProbeNote(withoutToken) {
 }
 
 export async function remove(o, { quiet = false, allowMissingProject = false, skipSecrets = false, secretNames = undefined, rerun = "" } = {}) {
+	refuseHosted();
 	if (!TUNNEL_KEYS.some((k) => C.get(k))) {
 		if (!quiet) console.error("nothing to remove");
 		return;

package/lib/uninstall.mjs

@@ -78,6 +78,7 @@ function removalError(err, { removed, left, workerGone, workerStill }) {
 
 /** One line per removal. A missing Worker or D1 counts as already gone. The config directory stays. */
 export async function uninstall(o) {
+	if (C.deploymentKind() === "hosted") throw new CliError("this is a hosted config. uninstall removes self-hosted infrastructure only. To delete this hosted agent, use the hosted service agent settings and its deletion confirmation. The local config is unchanged.");
 	if (!deploymentSaved())
 		throw new CliError(`nothing is deployed from ${C.CONFIG_DIR}. Another deployment? Set A2A_CONFIG_DIR.`);
 	console.error(uninstallPlan());

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.8.29",
+	"version": "0.8.31",
 	"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.29";
+export const VERSION = "0.8.31";