a2a-exposed 0.8.31 → 0.8.33

package/lib/hosted.mjs

@@ -4,11 +4,23 @@ 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"];
+export const SETUP_SCOPES = ["agents:read", "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);
 
+function retryAfter(response, data) {
+	const header = response.headers.get("retry-after");
+	let seconds;
+	if (header && /^\d+$/.test(header)) seconds = Number(header);
+	else if (header && /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(header)) {
+		const date = Date.parse(header);
+		if (Number.isFinite(date)) seconds = Math.max(0, Math.ceil((date - Date.now()) / 1000));
+	}
+	if (Number.isSafeInteger(seconds) && seconds >= 0) return seconds;
+	return Number.isSafeInteger(data.retry_after) && data.retry_after >= 0 ? data.retry_after : undefined;
+}
+
 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 || "" };
@@ -32,10 +44,21 @@ async function request(origin, path, { token = "", method = "GET", body, fetchIm
 	} 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"];
+		if (response.status === 429 && data.error === "too_many_references") {
+			const seconds = retryAfter(response, data);
+			const next = seconds === undefined
+				? "Wait for an unused reference to expire before running wake prepare again; no automatic retry was made."
+				: `Wait ${seconds} seconds before running wake prepare again with a new --reference-file; no automatic retry was made.`;
+			// Retain the capacity message, but never reflect arbitrary service text or credentials.
+			const message = typeof data.message === "string" && /^This setup grant has \d{1,10} unused references\. Wait \d{1,10} seconds before uploading another draft\.$/.test(data.message) ? data.message : undefined;
+			const error = new CliError(next);
+			error.result = { ok: false, code: "too_many_references", next, ...(message ? { message } : {}), ...(seconds === undefined ? {} : { retry_after: seconds }) };
+			throw error;
+		}
+		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", "body"];
 		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."
+		const next = code === "taken" || code === "reserved_name" ? "Choose another --name using hosted names --name NAME --json before creating."
+			: code === "limit" ? "The account is at its agent limit. Read hosted capacity --json and review account plans."
 			: code === "conflict" ? "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
@@ -48,7 +71,7 @@ async function request(origin, path, { token = "", method = "GET", body, fetchIm
 export async function capabilities(o = {}) {
 	const data = await request(originFor(o), "/api/v1/setup/capabilities");
 	if (!Array.isArray(data.scopes) || !Array.isArray(data.wake?.presets)) fail("unsupported", "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 };
+	return { ok: true, code: "capabilities", next: "Select explicit scopes and a wake preset from this listing.", scopes: data.scopes.filter(s => SETUP_SCOPES.includes(s)), presets: data.wake.presets.filter(s => /^[a-z-]+$/.test(s)), preflight: data.preflight === true, secret_reference: data.wake.secret_reference === true, wake_removal: data.wake.removal === true, secure_link_create: data.wake.secure_link_create === true };
 }
 
 export async function login(o = {}) {
@@ -75,12 +98,37 @@ export async function list(o = {}) {
 	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 names(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 one explicit --name of 4–32 letters, numbers or hyphens, starting and ending with a letter or number. Use hosted names --name NAME --json before approving setup.");
+ const origin = originFor(o);
+ if (!(await capabilities(o)).preflight) fail("unsupported", "This service does not expose name preflight. Use hosted capabilities --json or the website.");
+ const data = await request(origin, `/api/v1/setup/name?name=${encodeURIComponent(name)}`);
+ if (data.name !== name || typeof data.available !== "boolean" || !["available", "invalid_name", "reserved_name", "taken"].includes(data.reason) || data.available !== (data.reason === "available")) fail("invalid_response", "The service did not return a valid name availability result. No creation was attempted.");
+ return { ok: true, code: "name_availability", name, available: data.available, reason: data.reason, next: data.available ? "This name is available now, without a reservation. Run hosted capacity --json before hosted create --name NAME --json." : "Choose another --name and repeat hosted names --name NAME --json before requesting creation access." };
+}
+
+export async function capacity(o = {}) {
+ const { origin, token } = accountCredential(o);
+ if (!(await capabilities(o)).preflight) fail("unsupported", "This service does not expose capacity preflight. Use hosted capabilities --json or the website.");
+ const data = await request(origin, "/api/v1/setup/capacity", { token });
+ const count = value => Number.isSafeInteger(value) && value >= 0;
+ if (!(data.limit === null || count(data.limit)) || !count(data.used) || !(data.remaining === null || count(data.remaining)) || data.remaining !== (data.limit === null ? null : Math.max(0, data.limit - data.used)) || data.can_create !== (data.remaining === null || data.remaining > 0)) fail("invalid_response", "The service did not return valid account capacity. No creation was attempted.");
+ return { ok: true, code: "capacity", limit: data.limit, used: data.used, remaining: data.remaining, can_create: data.can_create, next: data.can_create ? "This is a read-only snapshot. Check hosted names --name NAME --json, then explicitly approve creation scopes if needed and run hosted create --name NAME --json." : "The account has no creation room. Review its agents and plan before another creation attempt." };
+}
+
 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 service = await capabilities(o);
+ if (service.preflight) {
+  const available = await names(o);
+  if (!available.available) fail(available.reason, "Choose a name with hosted names --name NAME --json before creating.");
+  if (!(await capacity(o)).can_create) fail("limit", "The account is at its agent limit. Read hosted capacity --json and review its agents or plan.");
+ }
 	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 } });
@@ -136,22 +184,60 @@ function previewUrl(value) {
  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.");
+	const removing = sub === "remove" || sub === "unset";
+ const preparingRemoval = sub === "prepare" && o.clear === true;
+ if (o.clear && !preparingRemoval) fail("usage", "Use wake prepare --clear for an MCP removal reference, or wake remove --version N. Run wake preview --json to list the current version.");
+ if (removing || preparingRemoval) {
+  if (o.url || o.preset || Object.keys(o).some(key => /^(?:key|hmac-secret|access-client)/.test(key))) fail("removal_inputs", "Omit draft settings and secrets when removing a wake. Run wake preview --json first.");
+  if (!/^(0|[1-9][0-9]*)$/.test(String(o.version ?? "")) || !Number.isSafeInteger(Number(o.version))) fail("version", "Pass --version N selected from wake preview --agent NAME --json. Removal never selects a version automatically.");
+ }
 	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" || removing) && (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 (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.");
+ if (removing || preparingRemoval) {
+  const version = Number(o.version);
+  if (version !== current.version) fail("conflict", "Wake settings changed. Run wake preview --agent NAME --json, review them, then repeat removal with its explicit --version.");
+  const available = await capabilities({ "control-url": origin });
+  if (!available.wake_removal || (preparingRemoval && !available.secret_reference)) fail("unsupported", "This service does not support this removal operation. Use the agent's Wake settings on the website.");
+  if (preparingRemoval) {
+   const prepared = await request(origin, `${path}/reference`, { token, method: "POST", body: { version, clear: true } });
+   if (!/^a2awr_[a-f0-9]{64}$/.test(prepared.reference || "")) fail("invalid_response", "The service did not return a valid removal reference. No wake was removed.");
+   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", version, next: "Within ten minutes, use MCP set_wake with clear: true and secretReference, or wake remove --version N --reference-file FILE. The reference is single-use and never printed." };
+  }
+  const result = await request(origin, path, { token, method: "DELETE", body: { version, ...(reference ? { secretReference: reference } : {}) } });
+  const ok = result.ok === true && (result.removed === true || result.already_removed === true);
+  return { ok, code: ok ? result.already_removed === true ? "already_removed" : "removed" : "failed", removed: result.removed === true, already_removed: result.already_removed === true, version: result.version, next: ok ? "Use polling to read messages." : "Read wake preview --json before retrying removal with an explicit --version." };
+ }
+	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." };
 	}
@@ -196,7 +282,7 @@ export async function output(run, o = {}) {
 		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}`);
+		console.log(o.json ? JSON.stringify(result) : `${result.code}: ${result.next}${result.message ? `\nmessage: ${result.message}` : ""}`);
 		process.exitCode = 1;
 	}
 }

package/lib/main.mjs

@@ -31,7 +31,10 @@ Hosted setup:
   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 names --name NAME --json
+                                check one name anonymously before device approval; never lists other agents
+  hosted capacity --json      read account room with agents:read (or agents:create); reserves nothing
+  hosted list --json           list hosted agents with agents:read or agents:create before choosing an agent
   hosted create --name NAME --json
                                 create and save the owner credential in this config directory;
                                 use a separate --config-dir for each agent
@@ -45,7 +48,13 @@ Hosted setup:
   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.
+  Hosted reference capacity failures report too_many_references and a retry wait; never auto-retry.
+  wake remove --agent NAME --version N --json
+                                read wake preview --json first; remove only the version explicitly selected
+                                wake unset is an alias; credentials remain in protected storage
+  wake prepare --agent NAME --clear --version N --reference-file FILE --json
+                                prepare a removal reference for MCP set_wake clear: true, secretReference;
+                                without that reference MCP keeps browser confirmation
   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:
@@ -178,6 +187,9 @@ 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):
@@ -376,7 +388,7 @@ const deployOpts = {
 const SPEC = {
 	hosted: { name: S, json: B, agent: S, hostname: S, origin: S, path: S, preset: S, "control-url": S, "secret-file": S, "secret-env": S, "secret-from": S, "hermes-home": S, route: S, "token-file": S, "no-run": B },
 	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,
+	wake: { ...deployOpts, json: B, url: S, "reference-file": S, "reference-env": S, clear: B, version: S, agent: S, "control-url": S, "key-header": S, "key-file": S, "key-env": S, "key-stdin": B, "hmac-secret-file": S, "hmac-secret-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S }, tunnel: tunnelOpts,
 	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 },
@@ -385,7 +397,7 @@ 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 },
@@ -462,7 +474,7 @@ 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);
@@ -499,7 +511,7 @@ 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 === 1 && ["capabilities", "list", "create", "names", "capacity"].includes(p[0])) return hosted.output(() => hosted[p[0]](o), o);
 			if (p.length !== 2 || p[0] !== "link" || !["finish", "create"].includes(p[1])) 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") });
 		}

package/package.json

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