a2a-exposed 0.8.32 → 0.8.34

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 } });
@@ -146,14 +194,20 @@ export async function status(o = {}) {
 
 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" && (o["reference-file"] || o["reference-env"])) {
+	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", ""); }
@@ -167,6 +221,22 @@ export async function wake(sub, o = {}) {
 	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 (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." };
@@ -212,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/link-finish.mjs

@@ -1,11 +1,71 @@
 import crypto from "node:crypto";
 import path from "node:path";
 import os from "node:os";
+import { domainToASCII } from "node:url";
+import { isIP } from "node:net";
 import { CliError } from "./a2a.mjs";
 import { controlOrigin } from "./account.mjs";
 import * as C from "./config.mjs";
 import { readSigningSecret, validateSecretSource, writeTokenFile, startConnector, connectorCommand } from "./local-link.mjs";
 
+// Keep JSON diagnostics local: never serialize arbitrary service fields or errors.
+function resultShape(ok, code, next, details = {}) {
+	return { ok, code, reason: null, field: null, phase: null, status: null, hostname: null, next, ...details };
+}
+function linkError(code, next, details = {}) {
+	const error = new CliError(next);
+	error.result = resultShape(false, code, next, details);
+	return error;
+}
+const presetNext = "Pass --preset ID selected from hosted capabilities --json before requesting approval.";
+
+export function normalizeHostname(value) {
+	const invalid = (reason, next) => { throw linkError("invalid_hostname", next, { field: "hostname", reason, phase: "validation" }); };
+	if (typeof value !== "string" || !value.trim()) invalid("required", "Pass --hostname with a full DNS hostname on your Cloudflare domain.");
+	let hostname = value.trim();
+	if (/[\s\\\x00-\x1f\x7f]/.test(hostname)) invalid("characters", "--hostname must not contain whitespace, control characters or backslashes.");
+	if (hostname.includes("://")) {
+		if (!/^https:\/\//i.test(hostname)) invalid("scheme", "--hostname accepts a DNS hostname or an HTTPS URL.");
+		// Inspect authority before URL normalization can remove a default port or path.
+		const authority = hostname.slice(8).split(/[/?#]/, 1)[0];
+		if (authority.includes("@")) invalid("credentials", "--hostname must not contain URL credentials.");
+		if (authority.includes(":")) invalid("port", "--hostname must not contain a port.");
+		if (/[?#]/.test(hostname)) invalid("query_fragment", "--hostname must not contain a query or fragment.");
+		const suffix = hostname.slice(8 + authority.length);
+		if (suffix && suffix !== "/") invalid("path", "--hostname HTTPS URLs must have no path beyond /.");
+		hostname = authority;
+	} else {
+		if (hostname.includes("@")) invalid("credentials", "--hostname must not contain URL credentials.");
+		if (hostname.includes(":")) invalid("port", "--hostname must not contain a scheme or port; use an HTTPS URL or a DNS hostname.");
+		if (/[/?#]/.test(hostname)) invalid("path", "--hostname must not contain a path, query or fragment.");
+	}
+	// IDNA also normalizes Unicode dot separators. Remove exactly one root dot.
+	hostname = domainToASCII(hostname).toLowerCase().replace(/\.$/, "");
+	if (isIP(hostname) || /^\d+(?:\.\d+)*$/.test(hostname)) invalid("ip_address", "--hostname must be a DNS hostname, not an IP address.");
+	if (!hostname || hostname.length > 253 || !hostname.split(".").every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
+		invalid("dns_labels", "--hostname needs DNS labels of 1–63 letters, digits or hyphens, with no empty labels or leading/trailing hyphens (253 characters maximum).");
+	if (!hostname.includes(".") || !/^(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/.test(hostname.split(".").at(-1)))
+		invalid("domain", "--hostname must be a full DNS hostname with a valid domain suffix.");
+	return hostname;
+}
+
+export function linkUsage() {
+	throw linkError("usage", "Use hosted link create --agent NAME --hostname HOST --origin URL --path PATH --preset ID [--json], or hosted link finish --agent NAME --preset ID [--json]; choose exactly one protected --secret-file FILE, --secret-env VAR, or --secret-from hermes. List choices with hosted list --json and hosted capabilities --json.", { phase: "validation" });
+}
+
+export async function linkOutput(run, o = {}) {
+	try {
+		const result = await run();
+		if (o.json) console.log(JSON.stringify(resultShape(true, result.saved ? "saved" : "connector_saved",
+			result.saved ? "The connector connected; the wake test passed and settings were saved." : "Start cloudflared with the saved token file, then run hosted link finish with --preset ID for fresh approval.",
+			{ phase: result.saved ? "wake-test" : "connector", hostname: result.hostname, ...result })));
+	} catch (error) {
+		if (!o.json) throw error;
+		console.log(JSON.stringify(error.result || resultShape(false, "local_failure", "Hosted link setup did not finish. Check the local secret source, token-file permissions and cloudflared, then request fresh approval.")));
+		process.exitCode = 1;
+	}
+}
+
 const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const ERRORS = {
 	expired_token: "The link request expired. Start a new one with hosted link create.",
@@ -70,7 +130,7 @@ const VALIDATION_MESSAGES = new Set([
 	"Use an http or https origin with no path or credentials.",
 	"Use a path beginning with /, with no query or fragment.",
 ]);
-const DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/;
 function validationDetail(body, hostname) {
 	if (typeof body?.message !== "string") return "";
 	if (VALIDATION_MESSAGES.has(body.message)) return body.message.replace(/ and try again\.$/, ".");
@@ -105,12 +165,17 @@ function failure(status, body, { command, hostname }, phase = "requests") {
 		: `The link request expired. Start a new one with hosted link ${command}.`;
 	if (code === "invalid_request" && phase === "token") guidance = `The approval polling request was refused. Run hosted link ${command} again for fresh approval.`;
 	const message = detail || guidance.replace(/run finish/gi, (match) => `${match.startsWith("R") ? "Run" : "run"} ${command}`);
-	return new CliError(`link ${command} failed${hostname ? ` for ${hostname}` : ""} (${code}); ${message}`);
+	const reason = ["hostname_format", "origin_format", "path_format", "hostname_invalid", "preset_invalid", "origin_invalid", "path_invalid", "apex_hostname", "outside_zone", "existing_dns", "existing_tunnel"].includes(body?.reason) ? body.reason : known(body?.reason) ? body.reason : null;
+	const field = ["hostname", "origin", "path", "preset"].includes(body?.field) ? body.field : null;
+	const provisionPhase = ["cleanup", "hostname", "zone", "existing_dns", "existing_tunnel"].includes(body?.phase) ? body.phase : null;
+	return linkError(code.startsWith("HTTP ") ? `http_${status}` : code,
+		`link ${command} failed${hostname ? ` for ${hostname}` : ""} (${code}); ${message}`,
+		{ reason, field, phase: code === "provision_failed" && provisionPhase ? provisionPhase : phase, status: code === "provision_failed" && Number.isInteger(body?.status) && body.status >= 100 && body.status <= 599 ? body.status : status, hostname: hostname || null });
 }
 
 export function savedLinkSession(origin, session = C.controlSession(), command = "finish") {
 	if (controlOrigin(session.origin) !== origin || !session.token)
-		throw new CliError(`sign in to this service first: run login --control-url <service-origin>, then rerun hosted link ${command}; environment sessions require both CONTROL_URL and CONTROL_TOKEN`);
+		throw linkError("login_required", `sign in to this service first: run login --control-url <service-origin>, then rerun hosted link ${command}; environment sessions require both CONTROL_URL and CONTROL_TOKEN`, { phase: "validation" });
 	return session.token;
 }
 
@@ -118,18 +183,16 @@ const CREATE_FIELDS = ["hostname", "origin", "path", "preset"];
 
 function createPlan(o) {
 	for (const key of CREATE_FIELDS) {
-		if (typeof o[key] !== "string" || !o[key]) throw new CliError(`hosted link create requires --${key}`);
+		if (typeof o[key] !== "string" || !o[key]) throw linkError("required", `hosted link create requires --${key}${key === "preset" ? "; " + presetNext : ""}`, { field: key, reason: "required", phase: "validation" });
 	}
-	const hostname = o.hostname.trim().toLowerCase();
-	if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(hostname))
-		throw new CliError("--hostname must be a DNS hostname on your Cloudflare domain");
+	const hostname = normalizeHostname(o.hostname);
 	let origin;
-	try { origin = new URL(o.origin); } catch { throw new CliError("--origin must be an http or https origin"); }
+	try { origin = new URL(o.origin); } catch { throw linkError("invalid_origin", "--origin must be an http or https origin", { field: "origin", phase: "validation" }); }
 	if (!/^https?:$/.test(origin.protocol) || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash)
-		throw new CliError("--origin must be an http or https origin with no path or credentials");
+		throw linkError("invalid_origin", "--origin must be an http or https origin with no path or credentials", { field: "origin", phase: "validation" });
 	if (!o.path.startsWith("/") || o.path.startsWith("//") || /[\s?#\\\x00-\x1f\x7f]/.test(o.path) || o.path.length > 1000)
-		throw new CliError("--path must begin with / and have no query, fragment or whitespace");
-	if (!/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw new CliError("--preset must be a wake preset id");
+		throw linkError("invalid_path", "--path must begin with / and have no query, fragment or whitespace", { field: "path", phase: "validation" });
+	if (!/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw linkError("preset", presetNext, { field: "preset", reason: o.preset === undefined || o.preset === "" ? "required" : "preset_invalid", phase: "validation" });
 	return { hostname, origin: origin.origin, path: o.path, preset: o.preset };
 }
 
@@ -138,12 +201,12 @@ export function createLink(o, deps) {
 	// Catch a wrong local route before asking the owner to create any resources.
 	validateSecretSource(o);
 	if (o["secret-from"] === "hermes" && (create.preset !== "hermes" || !/^\/webhooks\/[A-Za-z0-9_-]+$/.test(create.path) || (o.route && create.path !== `/webhooks/${o.route}`)))
-		throw new CliError("Hermes route does not match the create path and preset");
+		throw linkError("route_mismatch", "Hermes route does not match the create path and preset", { field: "path", phase: "validation" });
 	return setupLink(o, deps, create);
 }
 
 export function finishLink(o, deps) {
-	if (CREATE_FIELDS.filter((key) => key !== "preset").some((key) => o[key] !== undefined)) throw new CliError("creation options require hosted link create; finish only reuses an existing link");
+	if (CREATE_FIELDS.filter((key) => key !== "preset").some((key) => o[key] !== undefined)) throw linkError("usage", "creation options require hosted link create; finish only reuses an existing link", { phase: "validation" });
 	return setupLink(o, deps);
 }
 
@@ -156,10 +219,10 @@ async function setupLink(o, {
 	validateSecretSource(o);
 	const context = { command: create ? "create" : "finish", hostname: create?.hostname };
 	const agent = o.agent;
-	if (typeof agent !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$/.test(agent)) throw new CliError("--agent must be an agent name (letters, digits, underscores or hyphens)");
-	if (o.preset !== undefined && (typeof o.preset !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(o.preset))) throw new CliError("--preset must be a wake preset id");
+	if (typeof agent !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$/.test(agent)) throw linkError("agent", "--agent must be an agent name (letters, digits, underscores or hyphens); select it with hosted list --json", { field: "agent", phase: "validation" });
+	if (typeof o.preset !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw linkError("preset", presetNext, { field: "preset", reason: o.preset === undefined || o.preset === "" ? "required" : "preset_invalid", phase: "validation" });
 	const origin = controlOrigin(o["control-url"]);
-	if (!origin) throw new CliError("--control-url must be an https origin with no path");
+	if (!origin) throw linkError("control_url", "--control-url must be an https origin with no path", { field: "control-url", phase: "validation" });
 	const session = sessionToken(origin, undefined, context.command);
 	const request = async (endpoint, body, grant, timeout = 15000) => {
 		let response;
@@ -174,7 +237,7 @@ async function setupLink(o, {
 			const parsed = JSON.parse(text);
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
 			return { response, body: parsed };
-		} catch { throw new CliError(`link ${context.command} request failed; check the connection and run ${context.command} again for fresh approval`); }
+		} catch { throw linkError("unavailable", `link ${context.command} request failed; check the connection and run ${context.command} again for fresh approval`, { phase: endpoint, hostname: context.hostname || null }); }
 	};
 	const verifier = crypto.randomBytes(32).toString("base64url");
 	const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
@@ -182,9 +245,9 @@ async function setupLink(o, {
 	if (started.response.status !== 201) throw failure(started.response.status, started.body, context);
 	const setup = started.body;
 	let approval;
-	try { approval = new URL(setup.approve_url); } catch { throw new CliError("invalid approval response"); }
+	try { approval = new URL(setup.approve_url); } catch { throw linkError("invalid_response", "invalid approval response", { phase: "requests" }); }
 	if (approval.origin !== origin || approval.username || approval.password || typeof setup.request_id !== "string" || !setup.request_id || typeof setup.user_code !== "string" || !/^[A-Za-z0-9-]{4,32}$/.test(setup.user_code))
-		throw new CliError("invalid approval response");
+		throw linkError("invalid_response", "invalid approval response", { phase: "requests" });
 	write(`${setup.approve_url}\n${setup.user_code}`);
 	const deadline = now() + Math.min(600, Math.max(1, Number(setup.expires_in) || 600)) * 1000;
 	let interval = Math.min(60, Math.max(5, Number(setup.interval) || 5)), authorized;
@@ -200,21 +263,22 @@ async function setupLink(o, {
 	if (!authorized) throw failure(410, { error: "expired_token" }, context, "token");
 	const { grant, link } = authorized;
 	if (typeof grant !== "string" || !/^[\x21-\x7e]+$/.test(grant) || grant.length > 4096 || link?.agent !== agent || typeof link.path !== "string" || !link.path.startsWith("/") || typeof link.preset !== "string" || typeof link.hostname !== "string" || typeof link.origin !== "string")
-		throw new CliError("invalid approved link response");
+		throw linkError("invalid_response", "invalid approved link response", { phase: "token" });
 	if (create && CREATE_FIELDS.some((key) => link[key] !== create[key]))
-		throw new CliError("approved link differs from the requested creation plan; no connector or signing secret was transferred");
-	const preset = o.preset ?? link.preset;
-	if (!/^[a-z][a-z0-9-]{0,63}$/.test(preset)) throw new CliError("approved link has no valid preset; rerun finish with --preset <id> before requesting fresh approval");
+		throw linkError("plan_mismatch", "approved link differs from the requested creation plan; no connector or signing secret was transferred", { phase: "token", hostname: context.hostname || null });
+	const hostname = normalizeHostname(link.hostname);
+	context.hostname = hostname;
+	const preset = o.preset;
 	// Resolve and validate the source before spending the one-time connector delivery.
 	const secret = readSecret(o, { ...link, preset });
 	const connector = await request("connector", {}, grant);
 	if (!connector.response.ok) throw failure(connector.response.status, connector.body, context, "connector");
-	if (typeof connector.body.connector_token !== "string" || !connector.body.connector_token.trim() || /\s/.test(connector.body.connector_token)) throw new CliError("invalid connector response; run finish again for fresh approval");
+	if (typeof connector.body.connector_token !== "string" || !connector.body.connector_token.trim() || /\s/.test(connector.body.connector_token)) throw linkError("invalid_response", "invalid connector response; run finish again for fresh approval", { phase: "connector" });
 	const tokenFile = path.resolve(o["token-file"] || path.join(os.homedir(), ".a2a-exposed", "links", `${agent}.token`));
 	saveToken(tokenFile, connector.body.connector_token);
 	if (o["no-run"]) {
 		write(connectorCommand(tokenFile));
-		return { saved: false, connectorStarted: false };
+		return { saved: false, connectorStarted: false, hostname };
 	}
 	await runConnector(tokenFile);
 	let connected = false;
@@ -226,21 +290,21 @@ async function setupLink(o, {
 		if (status.body.connector === "connected" && Number.isInteger(status.body.connections) && status.body.connections > 0) { connected = true; break; }
 		await sleep(Math.min(3000, Math.max(0, connectDeadline - now())));
 	}
-	if (!connected) throw new CliError("connector did not report connected within 60 seconds; check cloudflared and run finish again for fresh approval");
+	if (!connected) throw linkError("connector_timeout", "connector did not report connected within 60 seconds; check cloudflared and run finish again for fresh approval", { phase: "status", hostname });
 	const tested = await request("wake-test", { signing_secret: secret, preset }, grant);
 	// 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.");
+		throw linkError("not_saved", "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.", { phase: "wake-test", status: tested.response.status, hostname });
 	}
 	if (tested.body.result !== "ok") {
 		const { result, message } = wakeFailure(tested.body.result);
 		write(`wake_result=${result}`);
-		throw new CliError(message);
+		throw linkError("wake_failed", message, { reason: result, phase: "wake-test", status: tested.response.status, hostname });
 	}
 	write("wake_result=ok");
 	write("Connector connected. Wake test passed and settings saved.");
-	return { saved: true, connectorStarted: true };
+	return { saved: true, connectorStarted: true, hostname };
 }

package/lib/main.mjs

@@ -13,7 +13,7 @@ import * as hosted from "./hosted.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
 import * as un from "./uninstall.mjs";
-import { finishLink, createLink } from "./link-finish.mjs";
+import { finishLink, createLink, linkOutput, linkUsage } from "./link-finish.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
@@ -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:
@@ -223,7 +232,8 @@ Inbox (owner side)
                                            history and continue with send. Then pending pairing
                                            requests (tell your human; the dashboard URL when MANAGE_URL is set;
                                            --json: rows on stdout, requests on stderr). Follows every page; past
-                                           10000 pages it errors instead of a short list
+                                           10000 pages it errors instead of a short list. Reading marks returned replies
+                                           seen and clears matching pending wakes; task state is unchanged
   show <taskId>                            full task JSON
   working <taskId>                         mark task working
   reply <taskId> (--text T | --stdin) [--state completed|input-required|rejected|failed|working]
@@ -379,7 +389,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 },
@@ -437,6 +447,7 @@ export async function main(argv) {
 	try {
 		parsed = parseArgs({ args: rest, options: SPEC[name] || {}, allowPositionals: true, strict: true });
 	} catch (e) {
+		if (name === "hosted" && rest.includes("link") && rest.some(value => ["create", "finish"].includes(value)) && rest.includes("--json")) return linkOutput(linkUsage, { json: true });
 		if (e && e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
 			const flag = (String(e.message).match(/'([^']+)'/) || [])[1] || "that flag";
 			if (flag === "-y") throw new CliError("unknown flag -y. To skip a prompt, pass --yes.");
@@ -502,9 +513,9 @@ 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") });
+			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])) return linkOutput(linkUsage, o);
+			return linkOutput(() => (p[1] === "create" ? createLink : finishLink)({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") }), o);
 		}
 		case "signup":
 		case "login": {

package/package.json

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

package/worker/src/index.ts

@@ -602,12 +602,12 @@ const agentCard = (ctx: TenantContext): Promise<Json> => (proxyMode(ctx) ? facad
 
 /** The same agent as an A2A 0.3 AgentCard (served at the legacy /.well-known/agent.json for 0.2/0.3 clients): top-level
  *  url + preferredTransport + protocolVersion, OpenAPI-style securitySchemes and `security`. 0.3 has no device-code
- *  flow, so the pairing scheme only points to the RFC 8414 metadata (oauth2MetadataUrl) and is not a requirement. */
+ *  flow, so only bearer authentication is advertised; pairing discovery stays on the 1.0 card. */
 function agentCard03(ctx: TenantContext, c: Json): Json {
 	const base = ctx.PUBLIC_URL.replace(/\/$/, "");
-	const schemes: Json = { bearer: { type: "http", scheme: "bearer", description: c.securitySchemes.bearer.httpAuthSecurityScheme.description } };
-	if (pairingOn(ctx)) schemes.pairing = { type: "oauth2", description: c.securitySchemes.pairing.oauth2SecurityScheme.description,
-		flows: {}, oauth2MetadataUrl: oauthUrls(ctx).metadata };
+	const schemes: Json = { bearer: { type: "http", scheme: "bearer", description: pairingOn(ctx)
+		? `Per-peer bearer token: from device-flow pairing described at ${base}/.well-known/agent-card.json (A2A 1.0), or issued by the agent's operator`
+		: c.securitySchemes.bearer.httpAuthSecurityScheme.description } };
 	const card: Json = {
 		protocolVersion: "0.3.0", name: c.name, description: c.description, url: base + "/", preferredTransport: "JSONRPC",
 		additionalInterfaces: [{ url: base + "/", transport: "JSONRPC" }], version: c.version,
@@ -2663,7 +2663,7 @@ async function devicePage(req: Request, ctx: TenantContext, ectx: ExecutionConte
 			model.askCode = true;
 			model.codeValue = raw || "";
 			if (raw && !notice) {
-				let text = "That is not a valid code (it looks like WDJB-4827).";
+				let text = "Enter four consonants, a hyphen, and four digits.";
 				if (code && !r) { lookupStatus = 404; text = PAIRING_NOT_FOUND; }
 				else if (r && r.status !== "pending") text = `That request was already ${r.status === "denied" ? "denied" : "approved"}.`;
 				else if (code && r) { lookupStatus = 404; text = PAIRING_EXPIRED; }
@@ -2683,6 +2683,11 @@ async function devicePage(req: Request, ctx: TenantContext, ectx: ExecutionConte
 		await show(form.user_code || null, { kind: "error", text: "This form expired or came from another site. Reload the page and try again." });
 		return send(403);
 	}
+	// Code entry is a lookup only; approval and denial remain separate CSRF-protected submissions.
+	if (form.decision === "lookup") {
+		await show(form.user_code || null);
+		return send(lookupStatus);
+	}
 	const code = P.normUserCode(form.user_code);
 	if (!code) { await show(form.user_code || null); return send(400); }
 	// Deny needs no password: it grants nothing, and the worst a holder of the code can do is cancel a pending request

package/worker/src/mcp.ts

@@ -319,8 +319,8 @@ const str = (description: string, extra: Schema = {}): Schema => ({ type: "strin
 const ro = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
 
 export const TOOLS: { name: string; title: string; description: string; inputSchema: Schema; outputSchema?: Schema; annotations: Schema }[] = [
-	{ name: "inbox", title: "Inbox", annotations: ro,
-		description: `Open tasks other agents sent to this A2A endpoint (state submitted or working), oldest first, one page at a time, plus a reply to a message you sent (kind "outbound") until this inbox lists it, plus pending pairing requests. When the result says more tasks are waiting, call inbox again with the cursor before you stop. Handle each inbound task, then answer it with reply. A reply to a message you sent: read it with history, and continue that conversation with send. ${RULES}`,
+	{ name: "inbox", title: "Inbox", annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+		description: `Open tasks other agents sent to this A2A endpoint (state submitted or working), oldest first, one page at a time, plus a reply to a message you sent (kind "outbound") until this inbox lists it, plus pending pairing requests. Reading this page marks returned replies seen and clears matching pending wakes; task state is unchanged. When the result says more tasks are waiting, call inbox again with the cursor before you stop. Handle each inbound task, then answer it with reply. A reply to a message you sent: read it with history, and continue that conversation with send. ${RULES}`,
 		inputSchema: { type: "object", properties: {
 			contextId: str("Only this conversation"),
 			from: str("Only this peer (the wake's from). The same context id can be a different peer's conversation"),

package/worker/src/pairing.ts

@@ -224,7 +224,8 @@ export type PageModel = {
 };
 
 export function devicePage(m: PageModel, nonce: string): string {
-	const notice = m.notice ? `<p class="n ${m.notice.kind}">${esc(m.notice.text)}</p>` : "";
+	const errorAttrs = m.notice?.kind === "error" ? ` aria-invalid="true" aria-describedby="device-error"` : "";
+	const notice = m.notice ? `<p${errorAttrs ? ` id="device-error" role="alert"` : ""} class="n ${m.notice.kind}">${esc(m.notice.text)}</p>` : "";
 	if (m.settled) {
 		const title = m.settled === "approved" ? "Approved" : "Denied";
 		return pageShell(title, nonce, `${notice}<p>You can close this page.</p>`);
@@ -253,14 +254,14 @@ export function devicePage(m: PageModel, nonce: string): string {
 	const passwordOn = m.passwordEnabled !== false;
 	const form = r && passwordOn && m.passwordSet ? `<form method="post" action="/device">
 <input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="user_code" value="${esc(formatUserCode(r.userCode))}">
-<label for="pw">Approval password (needed to approve; deny works without it)</label><input id="pw" name="password" type="password" autocomplete="current-password" required maxlength="1024" autofocus>
+<label for="pw">Approval password (needed to approve; deny works without it)</label><input id="pw" name="password" type="password"${errorAttrs} autocomplete="current-password" required maxlength="1024" autofocus>
 <div class="b"><button name="decision" value="approve" type="submit">Approve</button><button name="decision" value="deny" type="submit" class="d" formnovalidate>Deny</button></div>
 </form>` : r && passwordOn && !m.passwordSet ? noPassword + denyOnly : r ? denyOnly : "";
 	const oidcForm = m.oidc && r ? `<form method="post" action="/device">
 <input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="user_code" value="${esc(formatUserCode(r.userCode))}">
 <div class="b"><button name="decision" value="oidc" type="submit">Approve with ${esc(m.oidc.label)}</button></div>
 </form>` : "";
-	const ask = m.askCode ? `<p class="w">The connecting agent prints this code when it runs <code>${esc(`${m.cli} connect <url>`)}</code>. It looks like WDJB-4827.</p><form method="get" action="/device"><label for="uc">Code</label><input id="uc" name="user_code" value="${esc(m.codeValue || "")}" placeholder="WDJB-4827" autocomplete="off" autocapitalize="characters" required maxlength="16" autofocus><div class="b"><button type="submit">Continue</button></div></form>` : "";
+	const ask = m.askCode ? `<p class="w">The connecting agent prints this code when it runs <code>${esc(`${m.cli} connect <url>`)}</code>. Use four consonants, a hyphen, and four digits.</p><form method="post" action="/device"><input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="decision" value="lookup"><label for="uc">Code</label><input id="uc" name="user_code" value="${esc(m.codeValue || "")}" placeholder="XXXX-0000"${errorAttrs} spellcheck="false" autocomplete="off" autocapitalize="characters" required maxlength="16" autofocus><div class="b"><button type="submit">Continue</button></div></form>` : "";
 	return pageShell(`Connect an agent to ${m.agentName}`, nonce, `${notice}${details}${form}${oidcForm}${ask}`);
 }
 

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

package/worker/test/facade.test.ts

@@ -195,6 +195,8 @@ test("proxy mode: the served cards are the upstream's, rewritten to the public U
 	const c03 = (await s.call("GET", "/.well-known/agent.json")).data;
 	assert.equal(c03.url, BASE + "/");
 	assert.equal(c03.name, "Jean");
+	assert.deepEqual(Object.keys(c03.securitySchemes), ["bearer"], "0.3 façade omits unsupported pairing flow");
+	assert.deepEqual(c03.security, [{ bearer: [] }]);
 	assert.deepEqual(F.cardLeaks(c03, BASE, [TAILNET]), []);
 	// the card fetch carried the façade's upstream credentials (Access service token + bearer)
 	const cf = s.calls.find((c) => c.url.endsWith("/card-a.json"));

package/worker/test/mcp.test.ts

@@ -851,6 +851,11 @@ test("parseHttpResponse: status, headers, content-length and chunked bodies; mal
 });
 
 test("inbox tool clears wakes only for the page it returns, and a later call can fetch the rest", async (t) => {
+	const inbox = M.TOOLS.find(tool => tool.name === "inbox")!;
+	assert.equal(inbox.annotations.readOnlyHint, false, "inbox acknowledges reads");
+	assert.equal(inbox.annotations.destructiveHint, false, "acknowledgement preserves tasks");
+	assert.match(inbox.description, /marks returned replies seen and clears matching pending wakes/);
+	assert.equal(M.TOOLS.find(tool => tool.name === "history")!.annotations.readOnlyHint, true);
 	const s = setup({ WAKE_DEBOUNCE_SECONDS: "3600" });
 	t.after(s.restore);
 	const a = await s.connect();

package/worker/test/pairing.test.ts

@@ -65,6 +65,66 @@ function setup(over: Record<string, string> = {}) {
 	return { env, DB, wakes, call, owner, start, poll, decidePage, restore: () => { globalThis.fetch = origFetch; } };
 }
 
+test("device code entry posts a CSRF-protected lookup without making a pairing decision", async (t) => {
+	const s = setup(); t.after(s.restore);
+	const d = (await s.start()).data;
+	const entry = await s.call("GET", "/device");
+	assert.match(entry.text, /<form method="post" action="\/device">/);
+	assert.doesNotMatch(entry.text, /method="get"|placeholder="WDJB-4827"|aria-invalid/);
+	assert.match(entry.text, /placeholder="XXXX-0000"/);
+	assert.match(entry.text, /spellcheck="false" autocomplete="off" autocapitalize="characters"/);
+	assert.match(entry.text, /name="decision" value="lookup"/);
+	const cookie = entry.headers.get("set-cookie")!.split(";")[0];
+	const csrf = /name="csrf" value="([^"]+)"/.exec(entry.text)![1];
+	const lookup = (code: string, overrides = {}) => s.call("POST", "/device", {
+		form: { csrf, decision: "lookup", user_code: code }, cookie, headers: { origin: BASE }, ...overrides,
+	});
+	const page = await lookup(d.user_code.toLowerCase());
+	assert.equal(page.status, 200, page.text);
+	assert.equal(page.headers.get("location"), null, "no redirect puts the code in a URL");
+	assert.match(page.text, /Barry Bot/);
+	assert.match(page.text, /name="decision" value="deny"/);
+	assert.doesNotMatch(page.text, /aria-invalid/);
+	assert.equal((await s.poll(d.device_code)).data.error, "authorization_pending");
+	assert.equal(s.DB.db.prepare("SELECT status FROM device_requests").get()!.status, "pending");
+	assert.equal((await lookup(d.user_code, { cookie: "" })).status, 403);
+	assert.equal((await lookup(d.user_code, { headers: { origin: "https://evil.example" } })).status, 403);
+	assert.equal((await lookup(d.user_code, { form: { decision: "lookup", user_code: d.user_code } })).status, 403);
+	const invalid = await lookup("<bad>");
+	assert.equal(invalid.status, 200);
+	assert.match(invalid.text, /value="&lt;bad&gt;"/);
+	assert.match(invalid.text, /<input id="uc"[^>]*aria-invalid="true" aria-describedby="device-error"/);
+	assert.match(invalid.text, /<p id="device-error" role="alert"[^>]*>Enter four consonants/);
+	assert.equal((await lookup("BCDF-2345")).status, 404);
+	advance(3601);
+	const expired = await lookup(d.user_code);
+	assert.equal(expired.status, 404);
+	assert.match(expired.text, /aria-describedby="device-error"/);
+	assert.match(expired.text, /expired/i);
+});
+
+test("POST code lookups keep the existing IP limit", async (t) => {
+	const s = setup(); t.after(s.restore);
+	const g = await s.call("GET", "/device");
+	const cookie = g.headers.get("set-cookie")!.split(";")[0];
+	const csrf = /name="csrf" value="([^"]+)"/.exec(g.text)![1];
+	const lookup = () => s.call("POST", "/device", { form: { csrf, decision: "lookup", user_code: "BCDF-2345" }, cookie, headers: { origin: BASE } });
+	for (let i = 0; i < P.LIMITS.lookupsPerIp; i++) assert.equal((await lookup()).status, 404);
+	const limited = await lookup();
+	assert.match(limited.text, /Too many code lookups/);
+	assert.match(limited.text, /<input id="uc"[^>]*aria-invalid="true" aria-describedby="device-error"/);
+});
+
+test("wrong approval passwords identify the password input and error text", async (t) => {
+	const s = setup(); t.after(s.restore);
+	assert.equal((await s.owner("PUT", "/owner/pairing/password", await passwordRecord())).status, 200);
+	const d = (await s.start()).data;
+	const page = await s.decidePage(d.user_code, "wrong password", "approve");
+	assert.equal(page.status, 403);
+	assert.match(page.text, /<input id="pw"[^>]*aria-invalid="true" aria-describedby="device-error"/);
+	assert.match(page.text, /<p id="device-error" role="alert"[^>]*>Wrong password/);
+});
+
 test("HEAD answers like GET with an empty body, and a self-hosted card stays cached for 5 minutes", async (t) => {
 	const s = setup();
 	t.after(s.restore);
@@ -208,8 +268,8 @@ test("/.well-known/agent.json serves an A2A 0.3 card (url, preferredTransport, p
 	assert.deepEqual([old.name, old.version], ["Test Inbox", "1.0.0"]);
 	assert.deepEqual(old.capabilities, { streaming: false, pushNotifications: true, stateTransitionHistory: false });
 	assert.deepEqual(old.securitySchemes.bearer, { type: "http", scheme: "bearer", description: old.securitySchemes.bearer.description });
-	assert.equal(old.securitySchemes.pairing.type, "oauth2");
-	assert.equal(old.securitySchemes.pairing.oauth2MetadataUrl, `${BASE}/.well-known/oauth-authorization-server`);
+	assert.deepEqual(Object.keys(old.securitySchemes), ["bearer"], "0.3 has no device-code OAuth flow");
+	assert.match(old.securitySchemes.bearer.description, /device-flow pairing described at https:\/\/agent\.example\.com\/\.well-known\/agent-card\.json/);
 	assert.deepEqual(old.security, [{ bearer: [] }]);
 	assert.deepEqual(old.skills, [{ id: "s1", name: "S1", description: "d", tags: [] }], "0.3 requires tags");
 	assert.equal(old.supportedInterfaces, undefined, "no 1.0-only fields");
@@ -903,7 +963,7 @@ test("device page copy: code hint, expiry, token scope, settled result, A2A endp
 	const base = { agentName: "this A2A endpoint", mode: "human" as const, cli: "a2a", csrf: "c".repeat(24), passwordSet: true };
 	const bare = P.devicePage({ ...base, askCode: true }, "n");
 	assert.match(bare, /The connecting agent prints this code when it runs <code>a2a connect &lt;url&gt;<\/code>/);
-	assert.match(bare, /It looks like WDJB-4827/);
+	assert.match(bare, /four consonants, a hyphen, and four digits/);
 	assert.match(bare, /<title>Connect an agent to this A2A endpoint<\/title>/);
 	const req = { userCode: "WDJB4827", clientName: "Barry", clientId: "barry", agentCardUrl: "http://127.0.0.1/card", ip: "192.0.2.1", country: "", createdMs: now, expiresMs: now + 20_000 };
 	const page = P.devicePage({ ...base, request: req }, "n");
@@ -934,7 +994,7 @@ test("device page copy: code hint, expiry, token scope, settled result, A2A endp
 	const s = setup(); t.after(s.restore);
 	const empty = await s.call("GET", "/device");
 	assert.match(empty.text, /prints this code when it runs/);
-	assert.match(empty.text, /WDJB-4827/);
+	assert.match(empty.text, /placeholder="XXXX-0000"/);
 	const named = setup({ AGENT_NAME: "" }); t.after(named.restore);
 	const title = await named.call("GET", "/device");
 	assert.match(title.text, /Connect an agent to this A2A endpoint/);