a2a-exposed 0.8.6 → 0.8.7

package/README.md

@@ -1,6 +1,6 @@
 # a2a-exposed (CLI)
 
-Command-line companion for [a2a-exposed](https://github.com/telegraphic-dev/a2a-exposed). It gives any AI agent a public A2A endpoint: a Cloudflare Worker inbox plus a wake webhook.
+Command-line companion for [a2a-exposed](https://github.com/telegraphic-dev/a2a-exposed). It gives any AI agent a public A2A endpoint: a Cloudflare Worker plus a wake webhook.
 
 ```bash
 npx -y a2a-exposed@latest --help      # no install needed; @latest always runs the newest release
@@ -9,9 +9,9 @@ npx -y a2a-exposed@latest --help      # no install needed; @latest always runs t
 Optional speed-up on your own machine: `npm i -g a2a-exposed@latest`, then `a2a-exposed <command>` (re-run the install to upgrade; the CLI prints a notice when a newer version is out). Agent sandboxes often block global installs as untrusted code, so docs, skills and wake hints always use the npx form. The agent skills (`npx -y skills add telegraphic-dev/a2a-exposed`, into the current project) document the workflows; they do not install this CLI.
 
 - Node 22.18+ and zero dependencies. `init` installs Cloudflare's `cf` CLI into the Worker folder and uses that; you only need a one-time login (`npx cf auth login --no-browser`). No domain? Omit `--hostname` and `init` deploys to `https://<worker>.<account-subdomain>.workers.dev` (`--workers-dev-subdomain <name>` registers the account subdomain if missing).
-- **Setup:** `init`, `deploy`, `wake set|unset|test|preview|fingerprint`, `tunnel create|status|rm` (secure Cloudflare Tunnel + Access for local-only webhooks; needs any zone on the account, the inbox can be on workers.dev), `status` (read-only setup check with a next step), `url`, `config`. Use `--cli-command` to set the command shown in wake hints (default `npx -y a2a-exposed@latest`; e.g. a `node <checkout>/cli/bin/a2a-exposed.mjs` path for development).
-- **Inbox:** `inbox`, `show`, `working`, `reply`, `history`, `contexts`
-- **Pairing (OAuth 2.0 device flow, RFC 8628):** `connect <url>` (ask another inbox for a token; its owner approves), `pair set-password|list|approve|deny` (approve agents that connect to you; human approval by default)
+- **Setup:** `init`, `deploy`, `wake set|unset|test|preview|fingerprint`, `tunnel create|status|rm` (secure Cloudflare Tunnel + Access for local-only webhooks; needs any zone on the account, the A2A endpoint can be on workers.dev), `status` (read-only setup check with a next step), `url`, `config`. Use `--cli-command` to set the command shown in wake hints (default `npx -y a2a-exposed@latest`; e.g. a `node <checkout>/cli/bin/a2a-exposed.mjs` path for development).
+- **A2A endpoint:** `inbox`, `show`, `working`, `reply`, `history`, `contexts`
+- **Pairing (OAuth 2.0 device flow, RFC 8628):** `connect <url>` (ask another A2A endpoint for a token; its owner approves), `pair set-password|list|approve|deny` (approve agents that connect to you; human approval by default)
 - **Peer tokens:** `token issue|list|revoke|rotate` (manual fallback; `list` also shows tokens created by pairing)
 - **Outbound:** `peers add|list|rm`, `send`, `poll`, `outbound`
 - **Config:** `~/.config/a2a-exposed/config.env` (chmod 600; override the directory with `A2A_CONFIG_DIR`). Environment variables override file values; a peer token (`PEER_<ALIAS>_TOKEN`) that differs between the two prints a warning on stderr.

package/lib/deploy.mjs

@@ -15,7 +15,7 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."
 /** Each Claude Code routine fire is a new cloud session: a 2xx only means a session started. */
 export const CLAUDE_CODE_NOTE = [
 	"note (claude-code): each fire starts a NEW cloud session, which sees only what the routine provides.",
-	"  Simplest: add this inbox as a connector at claude.ai/settings/connectors (URL: <your Worker URL>/mcp, approve with",
+	"  Simplest: add this A2A endpoint as a connector at claude.ai/settings/connectors (URL: <your Worker URL>/mcp, approve with",
 	"  your approval password) and keep it enabled on the routine; the session then uses its tools, no CLI or token needed.",
 	"  Without the connector (CLI fallback), check that",
 	"  - the repo with the committed skills (.claude/skills/) is a routine source and the skills are on its default branch,",
@@ -257,7 +257,7 @@ function reportSwitch(sw) {
 	console.error(`\nnote: the public URL moved${sw.from ? ` from ${sw.from}` : ""} to ${to || "workers.dev"}.`);
 	if (sw.fromHost) {
 		console.error(`  ${sw.fromHost} no longer serves this agent: its agent card redirects (301) to the new one and every other request gets 410 Gone.`);
-		console.error(`  Cloudflare keeps the old custom domain attached to the Worker; to detach it completely, remove ${sw.fromHost} under Workers & Pages -> ${workerName()} -> Settings -> Domains & Routes.`);
+		console.error(`  Cloudflare keeps the old custom domain attached to the Worker; to detach it completely, remove ${sw.fromHost} from that Worker's custom domains and routes in the dashboard.`);
 	} else console.error("  The workers.dev URL is switched off by this deploy.");
 	console.error(`  Peers must update their URL for this agent: ${card} (A2A_BASE_URL in ${C.CONFIG_FILE} is updated).`);
 	if (C.get("A2A_TUNNEL_ID")) console.error("  The wake tunnel is unaffected (it has its own hostname and zone).");
@@ -471,7 +471,7 @@ export async function init(o) {
 	console.log(base);
 	reportSwitch(switched);
 	proxyNote(secrets);
-	if (rotated) console.error(`owner token replaced. Update A2A_OWNER_TOKEN wherever this inbox is called, then run \`${CLI} peers sync\` so uploaded peers stay readable.`);
+	if (rotated) console.error(`owner token replaced. Update A2A_OWNER_TOKEN wherever this A2A endpoint is called, then run \`${CLI} peers sync\` so uploaded peers stay readable.`);
 	console.error(`config saved to ${C.CONFIG_FILE} (chmod 600). Next: ${CLI} status (shows the next setup step)`);
 	printStar();
 }

package/lib/feedback.mjs

@@ -233,7 +233,7 @@ export async function feedbackPublicRepo(input) {
 	}
 	const body = named && named.ok ? await readJson(named) : null;
 	const repo = namedRepo(body?.repo);
-	if (!repo) throw new CliError("the inbox did not name the public repository; feedback was not sent");
+	if (!repo) throw new CliError("the A2A endpoint did not name the public repository; feedback was not sent");
 	return repo;
 }
 

package/lib/main.mjs

@@ -14,7 +14,7 @@ import * as un from "./uninstall.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
-const HELP = `a2a-exposed ${VERSION} - public A2A endpoint for any AI agent (Cloudflare Worker inbox + wake webhook)
+const HELP = `a2a-exposed ${VERSION} - public A2A endpoint for any AI agent (Cloudflare Worker + wake webhook)
 
 Usage: npx -y a2a-exposed@latest <command> [options]
        (optional speed-up: npm i -g a2a-exposed, then a2a-exposed <command>)
@@ -23,7 +23,7 @@ Usage: npx -y a2a-exposed@latest <command> [options]
 
 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 inbox and is open to everyone
+CLOUDFLARE_API_TOKEN instead: setup skill, Troubleshooting. a2a.exposed hosts the A2A endpoint and is open to everyone
 (https://a2a.exposed/pricing). When to use it, and the sentence to say:
 https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#hosted-inbox)
   init [--hostname <host> | --workers-dev [--workers-dev-subdomain NAME]]
@@ -55,14 +55,14 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                                When GET /owner/mcp reports enabled and the agent card is reachable,
                                                \`status\` prints \`claude mcp add --transport http a2a-exposed <url>/mcp\`
                                 --rotate-owner-token  on init, replace the owner token; other settings come from config.env.
-                                               Then update A2A_OWNER_TOKEN wherever this inbox is called, and run \`peers sync\`
+                                               Then update A2A_OWNER_TOKEN wherever this A2A endpoint is called, and run \`peers sync\`
                                 --upstream URL  proxy / expose mode: a public façade for an agent that already
                                                speaks A2A (JSON-RPC) on a private network. URL is its endpoint on
                                                a Cloudflare Tunnel hostname behind Access (never a Tailnet/LAN
                                                address). The card is the upstream's, rewritten to this public
                                                URL; paired peers' calls are forwarded with env UPSTREAM_TOKEN and
                                                UPSTREAM_ACCESS_CLIENT_ID / _SECRET (never argv). --upstream none
-                                               switches back to the inbox
+                                               switches back to the A2A endpoint
                                 --upstream-card-url  the upstream's card (default <upstream origin>/.well-known/
                                                agent-card.json); must be on the --upstream origin (it is
                                                fetched with the upstream credentials)
@@ -94,33 +94,41 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
   wake unset                    remove wake secrets (fall back to polling)
 
 Tunnel (local-only webhooks: OpenClaw gateway, Hermes, ...; needs Zero Trust/Access and a Cloudflare zone
-anywhere on the account: the inbox itself can be on workers.dev or a custom hostname)
+anywhere on the account: the A2A endpoint itself can be on workers.dev or a custom hostname)
   tunnel create [--tunnel-zone Z | --tunnel-hostname H] [--tunnel-origin URL] [--tunnel-path /p] [--show-token]
                 [--zero-trust-org TEAM]
                                 named Cloudflare Tunnel + proxied DNS + Access app that admits ONE service token;
                                 the Worker sends that token (CF-Access-Client-Id/Secret) on every wake.
-                                Wake hostname: wake-<random>.<zone>, on the inbox hostname's zone, else the account's
-                                only zone; with several zones pass --tunnel-zone. Safe to re-run (no duplicates).
+                                Wake hostname: wake-<word>-<word>-<4 hex>.<zone>, on the A2A endpoint hostname's zone, else the
+                                account's only zone; with several zones pass --tunnel-zone. A finished tunnel
+                                creates nothing when you run it again. A partial tunnel stops and asks for tunnel rm.
                                 The tunnel, the Access app, and the service token are named "a2a-exposed wake <worker>".
-                                The DNS host is wake-<words>-<hex>.<zone> unless --tunnel-hostname is set.
+                                The DNS host is wake-<word>-<word>-<4 hex>.<zone> unless --tunnel-hostname is set.
                                 Export WAKE_WEBHOOK_KEY (hermes: WAKE_HMAC_SECRET) so tunnel create uploads it.
                                 The connector machine needs cloudflared installed
                                 (https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/).
                                 Defaults: openclaw-* -> http://127.0.0.1:18789 /hooks/wake|agent, hermes -> :8644
                                 (pass --tunnel-path /webhooks/<name>). Token -> <config dir>/tunnel-token (chmod 600).
-                                Worker secrets show up in about 15 to 40 seconds
+                                Worker secrets show up in about 15 to 40 seconds. Wait about 30 seconds and check again
   tunnel status                 tunnel/Access/Worker state + probes (bare request blocked? connector up?)
+                                A network error says DNS may still be propagating; retry in 30 seconds
   tunnel rm                     delete the DNS record, the tunnel, the Access app, and the service token
                                 (each printed by name), plus Worker secrets WAKE_ACCESS_CLIENT_ID,
                                 WAKE_ACCESS_CLIENT_SECRET, WAKE_WEBHOOK_KEY, and WAKE_HMAC_SECRET. The wake URL
-                                goes too when it is this tunnel's. Prints one line per object removed
-  uninstall [--yes]             remove the wake tunnel (when the config has one), the Worker, and the D1 database.
-                                One line per step, including when that object is already gone. Asks first;
-                                off a terminal, pass --yes. The config directory stays (owner token and peer
-                                tokens): remove that directory to delete them. cf runs from the Worker project
-                                when it has node_modules, otherwise from a directory with .cloudflare/cache
+                                goes too when it is this tunnel's. Prints one line per object removed.
+                                With nothing saved, prints "nothing to remove"
   init ... --tunnel             init, then tunnel create (also with --workers-dev)
 
+Remove
+  uninstall [--yes] [--dry-run] [--dir DIR | --worker-dir DIR]
+                                remove the Worker, the wake tunnel (when the config has one), and the D1 database.
+                                Prints the plan first (Worker, D1, account, and the wake hostname when a tunnel
+                                is saved). Removal is permanent and takes the messages and paired peers with it.
+                                --dry-run prints the plan and changes nothing. Asks first; off a terminal, pass --yes.
+                                An empty config exits 1. The config directory stays: the owner token and WAKE_* values
+                                stay, and a later init reuses the owner token. Remove that directory to delete them.
+                                --dir and --worker-dir are the Worker project directory (default <config dir>/worker)
+
 Status
   status [--json]               deployment, base URL, agent card check (fetched by the CLI: no curl needed), wake
                                 mode (webhook / tunnel / none = polling), tunnel state, proxy mode (--upstream):
@@ -131,8 +139,11 @@ Status
                                 \`claude mcp add --transport http a2a-exposed <base URL>/mcp\`.
                                 A failed probe, an unreachable card, or a Worker that reports MCP off leaves that line out.
                                 Read-only; run it after an interruption and continue from "next step". Exit 1 = broken.
-                                Right after tunnel create, for about 15 to 40 seconds, while the connector
-                                reports 0 connections, status prints a wait-about-30-seconds line and exits 0
+                                For about a minute after tunnel create, while the connector reports 0 connections,
+                                status prints "waiting for the connector to connect" and exits 0. After that,
+                                0 connections is broken. A tunnel status of inactive is "never connected".
+                                Worker secrets from tunnel create, wake set, and wake unset show up in about
+                                15 to 40 seconds. Wait about 30 seconds and check again
   upstream verify [--json]      proxy mode: check the façade's whole path, layer by layer: façade peer auth
                                 (unauthenticated call -> 401), then the Worker calls the upstream with its stored
                                 secrets (never sent to the CLI) using a JSON-RPC method that doesn't exist (no task
@@ -150,14 +161,14 @@ Inbox (owner side)
         [--artifact] [--artifact-name N] [--force]
   history <contextId> [-n 50] [--json]     conversation log
   contexts                                 recent conversations
-  export [--sql]                       JSON dump of this inbox on stdout (peer-token hashes and
+  export [--sql]                       JSON dump of this A2A endpoint on stdout (peer-token hashes and
                                        encrypted peer tokens are in the dump; the owner token stays
                                        a Worker secret). --sql prints the same tables as SQL
 
 Pairing (OAuth 2.0 device flow, RFC 8628: agents connect without pasting tokens into chat)
   connect <base-or-card-url> [--alias A] [--name N] [--card-url URL] [--replace] [--no-wait] [--json]
-                          ask another inbox for a token: prints a code + link for your human (the code lasts
-                          10 minutes; they confirm the code with that inbox's owner), waits for approval, stores
+                          ask another A2A endpoint for a token: prints a code + link for your human (the code lasts
+                          10 minutes; they confirm the code with that A2A endpoint's owner), waits for approval, stores
                           the token as outbound peer A
                           (never printed). --no-wait: print the code and exit; run the same command again to
                           check (same code). An expired code exits 1 (nothing new is requested silently).
@@ -169,7 +180,7 @@ Pairing (OAuth 2.0 device flow, RFC 8628: agents connect without pasting tokens
                           The name sent is the card named in the request (--card-url, otherwise this
                           deployment's). --name overrides it. If that card can't be read, the name is the
                           configured agent name, the worker name, or the public host's first label. The
-                          other inbox labels the token from that name and adds -2, -3, … when it is taken
+                          other A2A endpoint labels the token from that name and adds -2, -3, … when it is taken
   pair set-password --web [--ttl MIN] [--json]
                           one-time link (default 15 min, --ttl 1 to 60, single use) where your human sets or
                           changes the approval password on a web page. Send it to them privately; never open
@@ -207,7 +218,7 @@ Outbound (agents you call)
   outbound <taskId>       stored state of a task you sent (incl. pushed updates)
 
 Owner
-  One inbox. The owner token from init authenticates inbox, reply, export, and the other owner
+  One A2A endpoint. The owner token from init authenticates inbox, reply, export, and the other owner
   commands. GET / in a browser shows the agent card. /device approves or denies a pairing request.
   pair set-password sets the approval password. pair set-oidc adds OpenID Connect on /device and
   the MCP consent page when the issuer, client id, client secret, and allowlist are all set.
@@ -219,25 +230,61 @@ Feedback
             [--connection webhook|proxy|polling] [--yes]
                                 report a bug or an idea. A bug needs --steps.
                                 The report is a public GitHub issue. The warning names
-                                the repository before it sends. A hosted inbox names
+                                the repository before it sends. A hosted A2A endpoint names
                                 that repository. Otherwise the link opens
                                 the form on telegraphic-dev/a2a-exposed. Do not include
                                 confidential information: secrets, tokens, owner or pairing
                                 tokens, private URLs or hostnames, message contents, or
                                 personal data. Prints that warning and asks before sending,
                                 unless --yes is set. Off a terminal, --yes is required.
-                                Posts when this inbox names a feedback URL.
+                                Posts when this A2A endpoint names a feedback URL.
                                 Otherwise prints a link to the bug
                                 report form and does not open a browser. The CLI adds its
-                                version, the inbox Worker version when the inbox reports it,
+                                version, the A2A endpoint Worker version when the A2A endpoint reports it,
                                 the OS, the Node version, the connection (webhook, proxy, or
                                 polling), and hosted or self-hosted. --connection overrides
                                 that detection. Remove tokens from the message and from --logs.
 
 Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | generic
+         Which clients are tested end to end is in the client table:
+         https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#clients
 Config: ${C.CONFIG_FILE}  (override dir with --config-dir DIR or A2A_CONFIG_DIR; env vars override file values)
 Update notice: at most a daily background check of the npm registry; off with A2A_NO_UPDATE_CHECK=1 (or DO_NOT_TRACK=1)`;
 
+const HELP_TUNNEL = `tunnel create|status|rm
+
+  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.
+                                The tunnel, the Access app, and the service token are named "a2a-exposed wake <worker>".
+                                The DNS host is wake-<word>-<word>-<4 hex>.<zone> unless --tunnel-hostname is set.
+                                A finished tunnel creates nothing when you run it again. A partial tunnel stops and
+                                asks for tunnel rm. Prints the Access application name and ids, then how to undo it
+                                with tunnel rm. Worker secrets show up in about 15 to 40 seconds. Wait about 30 seconds.
+  tunnel status                 Tunnel, Access, and Worker state, plus two probes.
+                                A network error says DNS may still be propagating; retry in 30 seconds.
+                                Warns about Access only when the bare request returns an HTTP status other than 401 or 403.
+  tunnel rm                     Delete the DNS record, the tunnel, the Access app, and the service token, plus the
+                                Worker secrets this tunnel uploaded. A missing Worker (Cloudflare 10007) is already gone.
+                                With nothing saved, prints "nothing to remove".
+
+--dir and --worker-dir are the Worker project directory (default <config dir>/worker).`;
+
+const HELP_UNINSTALL = `uninstall [--yes] [--dry-run] [--dir DIR | --worker-dir DIR]
+
+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.
+
+  --yes        skip the prompt (required off a terminal)
+  --dry-run    print the plan and change nothing
+  --dir        Worker project directory (same as --worker-dir)
+  --worker-dir Worker project directory (default <config dir>/worker)
+
+An empty config exits 1: nothing is deployed from that directory. Set A2A_CONFIG_DIR for another deployment.
+The config directory stays. The owner token and WAKE_* values stay in config.env. A later init reuses the owner token.
+Takes no other arguments.`;
+
 const S = { type: "string" }, B = { type: "boolean" };
 const tunnelOpts = { "tunnel-hostname": S, "tunnel-zone": S, "tunnel-origin": S, "tunnel-path": S, "show-token": B, "zero-trust-org": S, dir: S, "worker-dir": S };
 const deployOpts = {
@@ -261,7 +308,7 @@ const SPEC = {
 	login: { "control-url": S, json: B },
 	pair: { json: B, web: B, ttl: S, issuer: S, "client-id": S, subjects: S, methods: S, "secret-stdin": B },
 	feedback: { kind: S, contact: S, steps: S, expected: S, actual: S, logs: S, agent: S, environment: S, connection: S, yes: B },
-	uninstall: { yes: B, dir: S, "worker-dir": S },
+	uninstall: { yes: B, "dry-run": B, dir: S, "worker-dir": S },
 };
 const STATES = ["completed", "input-required", "failed", "rejected", "working"];
 
@@ -274,18 +321,40 @@ export async function main(argv) {
 	const [name, ...rest] = argv;
 	if (!name || name === "help" || name === "--help" || name === "-h") return console.log(HELP);
 	if (name === "--version" || name === "-v") return console.log(VERSION);
-	if (rest.includes("--help") || rest.includes("-h")) return console.log(HELP);
+	if (rest.includes("--help") || rest.includes("-h")) {
+		if (name === "uninstall") return console.log(HELP_UNINSTALL);
+		if (name === "tunnel") return console.log(HELP_TUNNEL);
+		return console.log(HELP);
+	}
 	if (name === "pair" && rest[0] === "set-oidc" && rest.some((a) => /^--(secret|client-secret)(=|$)/.test(a)))
 		throw new CliError("export APPROVAL_OIDC_CLIENT_SECRET or pass --secret-stdin. --secret-stdin checks the line and discards it. Deploy uploads only the environment variable");
 	if (name === "pair" && rest[0] === "set-password") {
 		// only --web [--ttl M] [--json]: the password itself never comes from argv, stdin or the environment
 		const extra = rest.slice(1);
+		const ttlAt = extra.findIndex((a) => a === "--ttl" || a.startsWith("--ttl="));
+		if (ttlAt >= 0) {
+			const raw = extra[ttlAt].startsWith("--ttl=") ? extra[ttlAt].slice("--ttl=".length) : extra[ttlAt + 1];
+			if (raw === undefined || String(raw).startsWith("--") || !/^\d+$/.test(String(raw)))
+				throw new CliError("--ttl is the link lifetime in minutes, 1 to 60 (default 15)");
+		}
 		const ok = extra.includes("--web") && extra.every((a, i) => ["--web", "--json", "--ttl"].includes(a) || /^--ttl=\d+$/.test(a) || (extra[i - 1] === "--ttl" && /^\d+$/.test(a)));
 		if (extra.length && !ok)
 			throw new CliError("`pair set-password` takes no password argument: it reads the password from the terminal, without echo (never from argv, stdin or the environment). For a one-time web link instead: `pair set-password --web [--ttl MIN] [--json]`");
 	}
 	upd.check(VERSION);
-	const { values: o, positionals: p } = parseArgs({ args: rest, options: SPEC[name] || {}, allowPositionals: true, strict: true });
+	let parsed;
+	try {
+		parsed = parseArgs({ args: rest, options: SPEC[name] || {}, allowPositionals: true, strict: true });
+	} catch (e) {
+		if (e && e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+			const flag = (String(e.message).match(/'([^']+)'/) || [])[1] || "that flag";
+			if (flag === "-y") throw new CliError("unknown flag -y. To skip a prompt, pass --yes.");
+			throw new CliError(`unknown flag ${flag}. Run \`${CLI} ${name} --help\` for this command's flags.`);
+		}
+		if (e && String(e.code || "").startsWith("ERR_PARSE_ARGS")) throw new CliError(String(e.message));
+		throw e;
+	}
+	const { values: o, positionals: p } = parsed;
 	if (o["worker-dir"] !== undefined) o.dir = o["worker-dir"];
 	switch (name) {
 		case "init":
@@ -293,11 +362,17 @@ export async function main(argv) {
 			await dep.init(o);
 			if (!o.tunnel) return;
 			try { return await tun.create(o); } catch (e) {
-				if (e instanceof CliError) e.message += `\n(the inbox is deployed and works; fix the above, then run \`${CLI} tunnel create\`, or check \`${CLI} status\`)`;
+				if (e instanceof CliError) e.message += `\n(the A2A endpoint is deployed and works; fix the above, then run \`${CLI} tunnel create\`, or check \`${CLI} status\`)`;
 				throw e;
 			}
-		case "tunnel": return tun.tunnel(need(p[0], "tunnel create|status|rm"), o);
-		case "uninstall": return un.uninstall(o);
+		case "tunnel": {
+			const sub = need(p[0], "tunnel create|status|rm");
+			if (p.length > 1) throw new CliError(`tunnel ${sub} takes no arguments (${p.slice(1).join(" ")}). Run \`${CLI} tunnel --help\`.`);
+			return tun.tunnel(sub, o);
+		}
+		case "uninstall":
+			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 "upstream": {
@@ -314,7 +389,8 @@ export async function main(argv) {
 		case "config": {
 			const f = C.fileConfig();
 			console.log(`# ${C.CONFIG_FILE}`);
-			for (const [k, v] of Object.entries(f)) console.log(`${k}=${/TOKEN|KEY|SECRET/.test(k) ? "(set)" : v}`);
+			const showValue = (k) => k === "A2A_TUNNEL_TOKEN_FILE" || k === "A2A_TUNNEL_SECRETS_AT";
+			for (const [k, v] of Object.entries(f)) console.log(`${k}=${/TOKEN|KEY|SECRET/.test(k) && !showValue(k) ? "(set)" : v}`);
 			return;
 		}
 		case "inbox": return cmd.inbox(o);

package/lib/pair.mjs

@@ -11,7 +11,7 @@ import { baseUrl, peerToken, warnPeerTokenEnv } from "./commands.mjs";
 export const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 export const PBKDF2_ITERATIONS = 100000; // default (the Workers runtime's maximum); the Worker advertises its own setting
 export const MIN_PASSWORD_LENGTH = 12;
-const MIGRATION_HINT = `(if this inbox was deployed before device-flow pairing existed, run \`${CLI} deploy\` first: it applies the new D1 migration)`;
+const MIGRATION_HINT = `(if this A2A endpoint was deployed before device-flow pairing existed, run \`${CLI} deploy\` first: it applies the new D1 migration)`;
 
 /** Owner API call that returns { status, data } instead of dying, so errors can be explained. */
 async function ownerCall(method, p, body) {
@@ -70,7 +70,7 @@ async function passwordLink(o) {
 	}
 	const r = await ownerCall("POST", "/owner/pairing/password-link", ttlSeconds ? { ttlSeconds } : {});
 	if (r.status === 404)
-		die(`this inbox's Worker predates \`pair set-password --web\`: run \`${CLI} deploy\` first, or let your human run \`${CLI} pair set-password\` in a terminal`);
+		die(`this A2A endpoint's Worker predates \`pair set-password --web\`: run \`${CLI} deploy\` first, or let your human run \`${CLI} pair set-password\` in a terminal`);
 	if (r.status !== 200) die(`could not create a setup link: ${ownerError(r)}`);
 	const d = r.data, mins = Math.round(d.expiresIn / 60);
 	const tell = `Send this link to your human, privately (it lets whoever opens it ${d.passwordSet ? "change" : "set"} the approval password). They open it and type the password themselves. Never open the link, fill in the page, or ask for the password yourself. Creating a new link invalidates this one.`;
@@ -258,7 +258,7 @@ export function cardUrlToSend(flag, own, quiet = false) {
 	if (flag) {
 		let u;
 		try { u = new URL(flag); } catch { die(`--card-url must be a URL (your agent card, e.g. https://agent.example.com/.well-known/agent-card.json)`); }
-		if (u.protocol !== "https:" || u.username || u.password) { note(`note: --card-url ${u.origin} is not a plain https URL, so it is left out of the pairing request (inboxes accept only public https cards). Peers can't call an agent there: to be reachable, expose it through a public façade (setup skill: "Already have A2A on a Tailnet or LAN") and pass the façade's card`); return ""; }
+		if (u.protocol !== "https:" || u.username || u.password) { note(`note: --card-url ${u.origin} is not a plain https URL, so it is left out of the pairing request (A2A endpoints accept only public https cards). Peers can't call an agent there: to be reachable, expose it through a public façade (setup skill: "Already have A2A on a Tailnet or LAN") and pass the façade's card`); return ""; }
 		if (u.href.length > 300) { note("note: --card-url is longer than 300 characters, so it is left out of the pairing request"); return ""; }
 		if (isPrivateHost(u.hostname)) note(`note: ${u.hostname} is on a private network: the peer's owner sees the card as informational ("not publicly reachable"). Expose your agent through a public façade for others to reach it (setup skill: "Already have A2A on a Tailnet or LAN").`);
 		return u.href;
@@ -360,7 +360,7 @@ A different agent at the same URL? Pass another --alias.`);
 			const why = r.data.error_description || r.data.error || `HTTP ${r.status}`;
 			const privateCard = !!sentCard && (() => { try { return isPrivateHost(new URL(sentCard).hostname); } catch { return false; } })();
 			die(r.status === 429 ? `${peerName} is not accepting more pairing requests right now: ${why}` : r.status === 404 ? `${peerName} has device-flow pairing disabled (${why}); ask its owner for a token`
-				: `pairing request to ${peerName} failed: ${why}${privateCard && r.status === 400 ? `. The card URL sent (${new URL(sentCard).host}) is not publicly reachable, and inboxes may accept only public https cards: retry with --card-url set to a public card, or expose your agent through a public façade first (setup skill: "Already have A2A on a Tailnet or LAN")` : ""}`);
+				: `pairing request to ${peerName} failed: ${why}${privateCard && r.status === 400 ? `. The card URL sent (${new URL(sentCard).host}) is not publicly reachable, and A2A endpoints may accept only public https cards: retry with --card-url set to a public card, or expose your agent through a public façade first (setup skill: "Already have A2A on a Tailnet or LAN")` : ""}`);
 		}
 		st = { base, alias, device: ep.device, token: ep.token, deviceCode: r.data.device_code, userCode: r.data.user_code,
 			verificationUri: r.data.verification_uri || "", verificationUriComplete: r.data.verification_uri_complete || r.data.verification_uri || "",

package/lib/status.mjs

@@ -2,6 +2,7 @@
 // calls only), so an agent that was interrupted can resume from the printed next step. The CLI fetches the agent card
 // itself, so agents need no curl (some agent sandboxes flag *.dev URLs in shell commands).
 import fs from "node:fs";
+import path from "node:path";
 import * as C from "./config.mjs";
 import { CLI, cardUrlProblem, cfErrorCode, describeHttp, die, fingerprint, httpJson } from "./a2a.mjs";
 import { baseUrl, owner, ownerTry } from "./commands.mjs";
@@ -29,7 +30,7 @@ export async function checkCard(base) {
 export function wakeLine(s) {
 	if (!s.wake) return "unknown (owner API not reachable)";
 	const w = s.wake;
-	if (!w.configured) return "none: no WAKE_WEBHOOK_URL on the Worker, so the agent is expected to poll the inbox";
+	if (!w.configured) return "none: no WAKE_WEBHOOK_URL on the Worker, so the agent is expected to poll the A2A endpoint";
 	const auth = [w.hasKey && "bearer/API key", w.hasHmacSecret && "HMAC signature", w.hasAccessServiceToken && "Access service token"].filter(Boolean);
 	return `webhook (preset ${w.preset}${s.tunnel ? ", through the tunnel" : ""}); auth: ${auth.join(" + ") || "none"}; URL fingerprint ${w.urlFingerprint || "-"}`;
 }
@@ -80,6 +81,24 @@ export function shadowedPeerTokens() {
 /** How long after `tunnel create` uploads secrets `status` treats a missing Worker preview as propagation. */
 export const SECRET_PROPAGATION_MS = 60_000;
 
+/** How long after `tunnel create` a connector with 0 connections is still "connecting", not broken. */
+export const CONNECTOR_WAIT_MS = 60_000;
+
+/** Cloudflare tunnel status `inactive` means the connector has never connected. */
+export function tunnelStateLabel(state) {
+	if (state === "inactive") return "never connected";
+	return state || "?";
+}
+
+/** True for about a minute after `tunnel create` while the connector reports 0 connections. */
+export function connectorConnecting(tunnel, now = Date.now()) {
+	if (!tunnel || tunnel.connections !== 0) return false;
+	const at = Number(tunnel.secretsAt);
+	if (!Number.isFinite(at) || at <= 0) return false;
+	const age = now - at;
+	return age >= 0 && age < CONNECTOR_WAIT_MS;
+}
+
 /** True while the tunnel's Worker secrets were uploaded recently and may still be invisible to `wake preview`. */
 export function secretsPropagating(tunnel, now = Date.now()) {
 	const at = Number(tunnel && tunnel.secretsAt);
@@ -99,13 +118,13 @@ export function nextStep(s) {
 function nextStepCore(s) {
 	const fail = (text) => ({ ok: false, text, also: [] });
 	const done = (text, also = []) => ({ ok: true, text, also });
-	if (!s.deployed) return fail(`nothing is deployed from ${s.configFile}: run \`${CLI} init ...\` (setup skill, section 2). Another bot's deployment? Set A2A_CONFIG_DIR.`);
+	if (!s.deployed) return fail(`nothing is deployed from ${path.dirname(s.configFile)}. 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 inbox URL is always the deployment's own)`);
+		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)`);
 	if (!s.baseUrl || !s.hasOwnerToken)
 		return fail(`the deployment is incomplete (no ${!s.baseUrl ? "base URL" : "owner token"} saved): re-run \`${CLI} init\` with the same flags (safe: it reuses the D1 database and the owner token)`);
 	if (!s.card.ok && s.card.cfError === 1042)
-		return fail(`the Worker is still propagating (Cloudflare error 1042, normal for up to ~30 s after a first deploy): run \`${CLI} status\` again in 30 seconds. Still 1042 after a few minutes? Run \`${CLI} deploy\``);
+		return fail(`the Worker is still propagating (Cloudflare error 1042, normal for up to 30 seconds after a first deploy): run \`${CLI} status\` again in 30 seconds. Still 1042 after a few minutes? Run \`${CLI} deploy\``);
 	if (!s.card.ok)
 		return fail(`the agent card is not reachable (${s.card.error}). A new workers.dev subdomain or custom domain can take a few minutes: run \`${CLI} status\` again. Still failing? Run \`${CLI} deploy\``);
 	if (s.card.urlProblem)
@@ -157,11 +176,13 @@ function nextStepCore(s) {
 	const now = typeof s.now === "number" ? s.now : Date.now();
 	if (t && !(s.wake.hasAccessServiceToken && t.workerUrlMatches)) {
 		if (secretsPropagating(t, now) && (t.connections === 0 || t.connections == null))
-			return done(`Worker wake secrets are still propagating (about 15 to 40 seconds after tunnel create). Wait about 30 seconds and run \`${CLI} status\` again.`);
+			return done(`Worker wake secrets are still propagating (about 15 to 40 seconds after tunnel create). Wait about 30 seconds. Start \`cloudflared tunnel run --token-file ${t.tokenFile}\` on the agent's machine now, then run \`${CLI} status\` again.`);
 		return fail(`the Worker does not have the tunnel's wake secrets: ${needsAgentSecret ? `export ${agentSecret} and ` : ""}run \`${CLI} tunnel create\` again (it re-uploads them; nothing new is created)`);
 	}
+	if (t && connectorConnecting(t, now))
+		return done(`waiting for the connector to connect. Start \`cloudflared tunnel run --token-file ${t.tokenFile}\` on the agent's machine now, then run \`${CLI} status\` again.`);
 	if (t && t.connections === 0)
-		return fail(`the tunnel has no running connector: on the agent's machine run \`cloudflared tunnel run --token-file ${t.tokenFile}\` (outbound port 7844 must be open), then \`${CLI} wake test\``);
+		return fail(`the tunnel has ${t.state === "inactive" ? "never connected" : "no running connector"}: on the agent's machine run \`cloudflared tunnel run --token-file ${t.tokenFile}\` (outbound port 7844 must be open), then \`${CLI} wake test\``);
 	if (s.wake.configured && needsAgentSecret)
 		return fail(`the Worker sends no webhook auth, so the ${s.wake.preset} webhook will reject wakes: export ${agentSecret} (${s.wake.preset === "hermes" ? "the route secret" : "the hooks token"}), then run \`${CLI} ${t ? "tunnel create" : "wake set"}\``);
 	// not broken, but peers can't pair until the human sets the approval password
@@ -172,7 +193,7 @@ function nextStepCore(s) {
 		also.push(`${s.pairing.pending} pending pairing request(s): \`${CLI} pair list\`, then tell your human (never approve on your own)`);
 	const done2 = (text, extra = []) => done(text, [...extra, ...also]);
 	if (!s.wake.configured) {
-		const poll = "the agent must check the inbox on a schedule (setup skill: polling; Hermes and OpenClaw have copy-paste commands there)";
+		const poll = "the agent must check the A2A endpoint on a schedule (Hermes and OpenClaw have copy-paste commands in the setup references)";
 		if (s.wake.preset && !LOCAL_PRESETS.includes(s.wake.preset) && s.wake.preset !== "generic")
 			return done2(`no wake webhook: export WAKE_WEBHOOK_URL and WAKE_WEBHOOK_KEY, then run \`${CLI} wake set --preset ${s.wake.preset}\`; or ${poll}`);
 		const z = s.zones;
@@ -280,7 +301,7 @@ export function mcpAddCommand(s) {
 
 /** `upstream verify`: the façade's whole path, layer by layer; exit 1 unless the upstream app answered. */
 export async function upstreamVerify(o) {
-	if (!C.get("A2A_UPSTREAM_URL")) die(`not a façade: ${C.CONFIG_FILE} has no A2A_UPSTREAM_URL (proxy mode: \`${CLI} deploy --upstream <tunnel URL>\`). For an inbox, check wakes with \`${CLI} wake test\``);
+	if (!C.get("A2A_UPSTREAM_URL")) die(`not a façade: ${C.CONFIG_FILE} has no A2A_UPSTREAM_URL (proxy mode: \`${CLI} deploy --upstream <tunnel URL>\`). For an A2A endpoint, check wakes with \`${CLI} wake test\``);
 	const base = baseUrl();
 	if (!base || !C.get("A2A_OWNER_TOKEN")) die(`A2A_BASE_URL / A2A_OWNER_TOKEN missing (run \`${CLI} init\` or edit ${C.CONFIG_FILE})`);
 	const r = await upstreamCheck(base);
@@ -299,7 +320,11 @@ export async function status(o) {
 	const s = await collect();
 	const next = nextStep(s);
 	const mcpAdd = mcpAddCommand(s);
-	if (o.json) console.log(JSON.stringify({ ...s, mcpAdd, nextStep: next.text, also: next.also, ok: next.ok }, null, 2));
+	if (o.json) {
+		const out = { ...s, mcpAdd, nextStep: next.text, also: next.also, ok: next.ok };
+		if (out.tunnel && out.tunnel.state != null) out.tunnel = { ...out.tunnel, state: tunnelStateLabel(out.tunnel.state) };
+		console.log(JSON.stringify(out, null, 2));
+	}
 	else {
 		const rows = [
 			["config", s.configFile],
@@ -328,7 +353,7 @@ export async function status(o) {
 			rows.push(["wake", wakeLine(s)]);
 			const t = s.tunnel;
 			rows.push(["tunnel", !t ? "none" : `${t.wakeUrl} -> ${t.origin || "?"}; ${!t.complete ? "INCOMPLETE" : t.tokenFileOk ? "set up" : "set up, but the connector token file is MISSING"}` +
-				(t.connections != null ? `; ${t.state || "?"}, ${t.connections} connector connection(s)` : t.error ? `; state unknown (${t.error})` : "")]);
+				(t.connections != null ? `; ${tunnelStateLabel(t.state)}, ${t.connections} connector connection(s)` : t.error ? `; state unknown (${t.error})` : "")]);
 			if (s.zones) rows.push(["zones", s.zones.length ? s.zones.join(", ") : "none on this account"]);
 			const pg = s.pairing;
 			if (pg) rows.push(["pairing", pg.mode === "off" ? "off (token issue only)"