a2a-exposed 0.8.30 → 0.8.32

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,218 @@
+// 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 status(o = {}) {
+	if (!/^[a-z0-9][a-z0-9-]{2,30}[a-z0-9]$/.test(o.agent || "")) fail("agent", "Pass --agent NAME selected from hosted list --json.");
+	const preview = await wake("preview", o);
+	return { ...preview, code: "status", agent: o.agent, next: preview.configured
+		? "Wake settings are configured. Run wake test --agent NAME with explicit draft inputs to check delivery."
+		: "No webhook is configured. Select a preset from hosted capabilities --json, then prepare a wake draft, or use polling." };
+}
+
+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."); }
+	}
+	let reference;
+	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 next = "Run wake prepare --agent NAME with the draft inputs and a new --reference-file FILE, then use that protected reference with wake set. Existing files are never replaced.";
+		try { reference = secret(o, "reference", ""); }
+		catch (error) {
+			if (error.result?.code === "secret_input") fail("invalid_reference", next);
+			throw error;
+		}
+		if (!/^a2awr_[a-f0-9]{64}$/.test(reference)) fail("invalid_reference", next);
+	}
+	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 (reference) {
+		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/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,10 @@ Remove
                                 --dir and --worker-dir are the Worker project directory (default <config dir>/worker)
 
 Status
+  status --agent NAME [--control-url URL] [--json]
+                                read selected hosted agent wake configuration; select NAME with hosted list --json.
+                                Uses setup approval or that agent's matching owner credential; no delivery test.
+  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 +335,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 +356,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 +377,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 },
@@ -357,13 +388,13 @@ const SPEC = {
 	peer: { to: S, all: B, reissue: B, hours: S, off: B, json: B },
 	send: { to: S, text: S, context: S, task: S, push: B, proto: S },
 	poll: { to: S, proto: S },
-	status: { json: B },
+	status: { json: B, agent: S, "control-url": S },
 	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 },
+	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 },
@@ -434,13 +465,13 @@ export async function main(argv) {
 			if (p.length) throw new CliError(`uninstall takes no arguments (${p.join(" ")}). Run \`${CLI} uninstall --help\`.`);
 			return un.uninstall(o);
 		case "deploy": return dep.deploy(o);
-		case "status": return st.status(o);
+		case "status": return o.agent !== undefined || o["control-url"] !== undefined ? hosted.output(() => hosted.status(o), o) : st.status(o);
 		case "upstream": {
 			const sub = need(p[0], "upstream verify [--json]");
 			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 +502,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.30",
+	"version": "0.8.32",
 	"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.30";
+export const VERSION = "0.8.32";