a2a-exposed 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telegraphic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# a2a-exposed (CLI)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```bash
+npm i -g a2a-exposed          # or one-off: npx -y a2a-exposed@latest --help
+a2a-exposed --help
+```
+
+The agent skills (`npx --yes skills add telegraphic-dev/a2a-exposed`) 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 a2a-exposed`; 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)
+- **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.
+
+See the repository README and the skills in `skills/` for full documentation. License: MIT.

package/bin/a2a-exposed.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// `--config-dir DIR` (anywhere on the command line) is the same as A2A_CONFIG_DIR=DIR; it must be set before the
+// config module loads, so main is imported afterwards.
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+	const a = argv[i];
+	if (a === "--config-dir" || a.startsWith("--config-dir=")) {
+		const v = a === "--config-dir" ? argv[i + 1] : a.slice("--config-dir=".length);
+		if (!v || v.startsWith("--")) { console.error("error: --config-dir needs a directory"); process.exit(1); }
+		process.env.A2A_CONFIG_DIR = v;
+		argv.splice(i, a === "--config-dir" ? 2 : 1);
+		break;
+	}
+}
+const { main } = await import("../lib/main.mjs");
+
+main(argv).catch((e) => {
+	const known = e && (e.name === "CliError" || e.constructor?.name === "CliError" || e.code?.startsWith?.("ERR_PARSE_ARGS"));
+	console.error(`error: ${known ? e.message : e?.stack || e}`);
+	process.exit(1);
+});

package/lib/a2a.mjs

@@ -0,0 +1,187 @@
+// Minimal A2A client helpers (0.3 + 1.0) and HTTP utilities.
+import crypto from "node:crypto";
+
+export const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export class CliError extends Error {}
+export const die = (msg) => { throw new CliError(msg); };
+
+export function checkId(v, what = "id") {
+	if (typeof v !== "string" || !ID_RE.test(v)) die(`invalid ${what}`);
+	return v;
+}
+
+export const newId = () => crypto.randomUUID();
+
+/** Hosts that only resolve on a private network (Tailnet, LAN, loopback). Same rules as the Worker's isPrivateHost. */
+export function isPrivateHost(host) {
+	const h = String(host || "").toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+	if (!h.includes(".") && !h.includes(":")) return true; // single-label names (localhost, MagicDNS short names)
+	if (/(^|\.)(localhost|local|lan|home|internal|intranet|corp|home\.arpa|ts\.net)$/.test(h)) return true;
+	const m = h.match(/^(\d+)\.(\d+)\.\d+\.\d+$/);
+	if (m) {
+		const [a, b] = [Number(m[1]), Number(m[2])];
+		return a === 10 || a === 127 || a === 0 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127);
+	}
+	if (!h.includes(":")) return false;
+	if (h === "::" || h === "::1" || /^f[cd]/.test(h) || /^fe[89ab]/.test(h) || /^fec/.test(h)) return true; // unspecified, loopback, ULA, link-/site-local
+	// IPv4 embedded in IPv6 (mapped ::ffff:a.b.c.d, NAT64 64:ff9b::, deprecated compatible ::a.b.c.d): judge the IPv4.
+	// URL parsing normalizes the dotted tail to hex (::ffff:7f00:1), so both spellings are handled.
+	const e = h.match(/^(?:::ffff:|64:ff9b::|::)(?:(\d+\.\d+\.\d+\.\d+)|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/);
+	if (e) {
+		const v4 = e[1] || [parseInt(e[2], 16) >> 8, parseInt(e[2], 16) & 255, parseInt(e[3], 16) >> 8, parseInt(e[3], 16) & 255].join(".");
+		return isPrivateHost(v4);
+	}
+	return false;
+}
+
+/** Problem with an upstream URL for proxy mode ("" when fine): the Worker calls it from Cloudflare, so it must be https
+ *  on a public hostname (a Cloudflare Tunnel hostname behind Access), never a Tailnet / LAN / localhost address. */
+export function upstreamUrlProblem(v) {
+	let u;
+	try { u = new URL(v); } catch { return "is not a URL"; }
+	if (u.protocol !== "https:") return "must be https";
+	if (u.username || u.password) return "must not contain credentials (export UPSTREAM_TOKEN instead)";
+	if (isPrivateHost(u.hostname))
+		return `is a private-network address (${u.hostname}) that the Worker cannot reach: publish the agent through a Cloudflare Tunnel hostname behind Access and pass that (setup skill: "Already have A2A on a Tailnet or LAN")`;
+	return "";
+}
+/** Problem with an upstream card URL ("" when fine): an upstream URL (see above) on the same origin (scheme, host,
+ *  port) as the upstream endpoint, because the Worker fetches the card with UPSTREAM_TOKEN and the Access service
+ *  token; a card on any other origin would receive those credentials. */
+export function upstreamCardUrlProblem(card, upstream) {
+	const why = upstreamUrlProblem(card);
+	if (why) return why;
+	let up;
+	try { up = new URL(upstream).origin; } catch { return ""; } // the upstream URL's own problem is reported for --upstream
+	const got = new URL(card).origin;
+	if (got !== up)
+		return `must be on the upstream's origin (${up}), not ${got}: the Worker fetches the card with UPSTREAM_TOKEN and the Access service token, which only ever go to the upstream itself`;
+	return "";
+}
+export const randomToken = (bytes = 32) => crypto.randomBytes(bytes).toString("base64url");
+
+export async function httpJson(url, { method, body, headers = {}, timeout = 30000 } = {}) {
+	const init = { method: method || (body === undefined ? "GET" : "POST"), headers: { accept: "application/json", ...headers }, signal: AbortSignal.timeout(timeout) };
+	if (body !== undefined) {
+		init.headers["content-type"] = "application/json";
+		init.body = JSON.stringify(body);
+	}
+	let r;
+	try { r = await fetch(url, init); }
+	catch (e) { die(`request to ${new URL(url).origin} failed: ${e?.cause?.code || e?.cause?.message || e?.message || e}`); }
+	const text = await r.text();
+	let data = text;
+	try { data = text ? JSON.parse(text) : null; } catch { /* keep text */ }
+	return { status: r.status, data };
+}
+
+// Cloudflare edge errors (HTML or "error code: NNNN" bodies, not the Worker's own JSON): code -> what it means here
+const CF_ERRORS = {
+	1042: "no Worker answers on this workers.dev host yet: a new deployment takes up to ~30 s to propagate; try again shortly",
+	1101: "the Worker threw an exception (see the Worker's logs)",
+	1102: "the Worker exceeded its CPU or memory limit",
+	1015: "rate limited by Cloudflare",
+	1033: "the Cloudflare Tunnel has no running connector",
+	1016: "origin DNS error",
+};
+
+/** Cloudflare edge error code (1042, 1101, ...) in a response body, or null. */
+export function cfErrorCode(data) {
+	if (typeof data !== "string") return null;
+	const m = /error(?:\s+code)?[:\s]+(1\d{3})\b/i.exec(data);
+	return m ? Number(m[1]) : null;
+}
+
+/** One readable line for a failed HTTP response: the Worker's JSON error, a Cloudflare error code and title, or a short
+ *  excerpt (never a raw HTML page). */
+export function describeHttp(status, data) {
+	const code = cfErrorCode(data);
+	if (code) return `HTTP ${status}, Cloudflare error ${code}${CF_ERRORS[code] ? `: ${CF_ERRORS[code]}` : ""}`;
+	if (data && typeof data === "object") {
+		const e = data.error;
+		const msg = typeof e === "string" ? e : e && typeof e === "object" ? `${e.code !== undefined ? `${e.code} ` : ""}${e.message || ""}`.trim() : "";
+		if (msg) return `HTTP ${status}: ${msg}${data.error_description ? ` (${data.error_description})` : ""}`;
+		return `HTTP ${status}: ${JSON.stringify(data).slice(0, 200)}`;
+	}
+	const text = String(data ?? "").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+	return `HTTP ${status}${text ? `: ${text.slice(0, 160)}${text.length > 160 ? "..." : ""}` : ""}`;
+}
+
+/** Lowercase A2A task state ("completed", "input-required", ...) from a 0.3 or 1.0 task. */
+export const plainState = (t) => {
+	const s = t && t.status && t.status.state;
+	return typeof s === "string" && s.startsWith("TASK_STATE_") ? s.slice(11).toLowerCase().replace(/_/g, "-") : s;
+};
+
+/** First 12 hex chars of sha256(value), or null when unset (same as the Worker's `wake preview` fingerprints). */
+export const fingerprint = (v) => (v ? crypto.createHash("sha256").update(String(v), "utf8").digest("hex").slice(0, 12) : null);
+
+export function textOf(msgOrParts) {
+	const parts = Array.isArray(msgOrParts) ? msgOrParts : (msgOrParts && msgOrParts.parts) || [];
+	const out = [];
+	for (const x of parts) {
+		if (!x || typeof x !== "object") continue;
+		if ("text" in x) out.push(String(x.text));
+		else if ("data" in x) out.push(JSON.stringify(x.data));
+		else if (x.kind === "file" || "url" in x || "raw" in x) {
+			const f = x.file || {};
+			out.push(`[file ${f.name || x.filename || f.uri || x.url || ""}]`);
+		}
+	}
+	return out.join("\n");
+}
+
+export async function fetchCard(base) {
+	for (const p of ["/.well-known/agent-card.json", "/.well-known/agent.json"]) {
+		try {
+			const { status, data } = await httpJson(base + p, { timeout: 15000 });
+			if (status === 200 && data && typeof data === "object") return data;
+		} catch { /* try next */ }
+	}
+	return null;
+}
+
+/** Does an agent card send peers to `base`? "" when it does, else what it advertises instead. */
+export function cardUrlProblem(card, base) {
+	const norm = (u) => { try { const x = new URL(u); return x.origin + x.pathname.replace(/\/+$/, ""); } catch { return null; } };
+	const want = norm(base);
+	const urls = [...new Set([...((card && card.supportedInterfaces) || []).map((i) => i && i.url), card && card.url].filter(Boolean))];
+	if (!urls.length) return "it advertises no endpoint URL (supportedInterfaces[].url)";
+	const wrong = urls.filter((u) => norm(u) !== want);
+	return wrong.length ? `it advertises ${wrong.join(", ")} instead of ${base.replace(/\/$/, "")}/` : "";
+}
+
+/** Choose the JSON-RPC endpoint + protocol version from an agent card (prefers 1.0). */
+export function pickEndpoint(base, card, force) {
+	const ifaces = ((card && card.supportedInterfaces) || []).filter((i) => String(i.protocolBinding || "").toUpperCase() === "JSONRPC");
+	if (force) {
+		const hit = ifaces.find((i) => String(i.protocolVersion || "").startsWith(force));
+		if (hit) return [hit.url, force];
+		return [(card && card.url) || base + "/", force];
+	}
+	const v1 = ifaces.find((i) => String(i.protocolVersion || "").startsWith("1"));
+	if (v1) return [v1.url, "1.0"];
+	if (card && card.url) return [card.url, "0.3"];
+	if (ifaces.length) return [ifaces[0].url, String(ifaces[0].protocolVersion || "0.3")];
+	return [base + "/", "0.3"];
+}
+
+/** JSON-RPC call to a peer. `peer` ({ alias, base }) makes a 401 say how to re-pair with that peer. */
+export async function rpc(url, version, token, method03, method1, params, peer = null) {
+	const v1 = version.startsWith("1");
+	const headers = { "A2A-Version": v1 ? "1.0" : "0.3" };
+	if (token) headers.authorization = `Bearer ${token}`;
+	const body = { jsonrpc: "2.0", id: newId(), method: v1 ? method1 : method03, params };
+	const { status, data } = await httpJson(url, { body, headers });
+	if (status === 401) {
+		const who = peer && peer.alias ? `peer "${peer.alias}"` : new URL(url).origin;
+		const base = (peer && peer.base) || new URL(url).origin;
+		die(token
+			? `${who} rejected our token (HTTP 401: revoked, rotated, or never valid there). Re-pair: a2a-exposed connect ${base}${peer && peer.alias ? ` --alias ${peer.alias}` : ""} (its owner approves), or ask its owner for a new token`
+			: `${who} needs a token (HTTP 401): a2a-exposed connect ${base}${peer && peer.alias ? ` --alias ${peer.alias}` : ""} (its owner approves)`);
+	}
+	if (status !== 200 || !data || typeof data !== "object" || "error" in data)
+		die(`peer returned ${data && typeof data === "object" && data.error ? `JSON-RPC error ${describeHttp(status, data).replace(/^HTTP \d+: /, "")} (HTTP ${status})` : describeHttp(status, data)}`);
+	return data.result;
+}

package/lib/commands.mjs

@@ -0,0 +1,262 @@
+// Day-to-day commands: inbox / reply / history (owner API) and outbound send / poll.
+import fs from "node:fs";
+import * as C from "./config.mjs";
+import { checkId, describeHttp, die, fetchCard, httpJson, newId, pickEndpoint, plainState, randomToken, rpc, textOf } from "./a2a.mjs";
+
+const q = encodeURIComponent;
+const out = (obj) => console.log(JSON.stringify(obj, null, 2));
+export const baseUrl = () => C.get("A2A_BASE_URL").replace(/\/$/, "");
+
+export async function owner(method, path, body) {
+	const base = baseUrl(), tok = C.get("A2A_OWNER_TOKEN");
+	if (!base || !tok) die(`A2A_BASE_URL / A2A_OWNER_TOKEN missing (run \`a2a-exposed init\` or edit ${C.CONFIG_FILE})`);
+	const { status, data } = await httpJson(base + path, { method, body, headers: { authorization: `Bearer ${tok}` } });
+	if (status < 200 || status >= 300) die(`worker ${method} ${path} -> ${describeHttp(status, data)}`);
+	return data;
+}
+
+/** Owner API call that returns { status, data } instead of dying, so callers can explain errors themselves. */
+export async function ownerTry(method, path, body) {
+	const base = baseUrl(), tok = C.get("A2A_OWNER_TOKEN");
+	if (!base || !tok) die(`A2A_BASE_URL / A2A_OWNER_TOKEN missing (run \`a2a-exposed init\` or edit ${C.CONFIG_FILE})`);
+	return httpJson(base + path, { method, body, headers: { authorization: `Bearer ${tok}` } });
+}
+
+function printPush(res) {
+	for (const r of (res && res.push) || []) console.error(`push -> ${r.url}: ${r.ok ? "ok" : "FAILED"} (${r.info})`);
+}
+
+const readStdin = () => fs.readFileSync(0, "utf8");
+
+// ---------------------------------------------------------------- inbound side
+export async function inbox(o) {
+	const qs = [];
+	if (o.context) qs.push("context=" + q(o.context));
+	if (o.all) qs.push("all=1");
+	const rows = await owner("GET", "/owner/inbox" + (qs.length ? "?" + qs.join("&") : ""));
+	// pending pairing requests: polling agents get no pairing wake, so the inbox shows them too (not with --context:
+	// that is one conversation). An older Worker without pairing: nothing to show.
+	let pairing = [];
+	if (!o.context) {
+		try { const r = await ownerTry("GET", "/owner/pairing"); if (r.status === 200 && r.data && Array.isArray(r.data.pending)) pairing = r.data.pending.map((p) => ({ ...p, approval: r.data.mode })); } catch { /* unreachable: the inbox call above already worked */ }
+	}
+	if (o.json) {
+		out(rows); // unchanged shape (an array of tasks); pairing requests go to stderr as one JSON line
+		if (pairing.length) console.error(JSON.stringify({ pendingPairingRequests: pairing.length, requests: pairing.map(({ userCode, clientName, clientId, verificationUriComplete, expiresAt, approval }) => ({ userCode, clientName: clientName || clientId || null, verificationUriComplete, expiresAt, approval })), instructions: PAIRING_NOTE }));
+		return;
+	}
+	if (!rows.length) console.log(pairing.length || o.context ? "(no unhandled tasks)" : "(no unhandled tasks, no pending pairing requests)");
+	for (const r of rows) {
+		console.log(`--- task ${r.taskId}  [${r.state}]  from=${r.from}  context=${r.contextId}  at=${r.updated}`);
+		console.log("UNTRUSTED PEER MESSAGE >>>");
+		console.log(r.text);
+		console.log("<<< END PEER MESSAGE");
+	}
+	if (pairing.length) {
+		console.log(`=== ${pairing.length} pending pairing request${pairing.length === 1 ? "" : "s"} (another agent asks to connect; ${pairing[0].approval} approval)`);
+		for (const p of pairing) {
+			console.log(`--- code ${p.userCode}  ${JSON.stringify(p.clientName || p.clientId || "(no name)")} (claimed, untrusted)  expires ${p.expiresAt}${p.replacesLabel ? `  replaces token "${p.replacesLabel}"` : ""}`);
+			console.log(`    link: ${p.verificationUriComplete}`);
+		}
+		console.log(PAIRING_NOTE);
+	}
+}
+
+const PAIRING_NOTE = "Tell your human who is asking, the code and the link (details: a2a-exposed pair list). Never approve on your own: in human mode they approve on the link with their approval password; in agent mode run `pair approve <code>` only after they say yes.";
+
+export const show = async (id) => out(await owner("GET", `/owner/tasks/${q(id)}`));
+
+export async function working(id) {
+	printPush(await owner("POST", `/owner/tasks/${q(id)}/working`, {}));
+	console.log(`${id} -> working`);
+}
+
+export async function reply(id, o) {
+	const text = o.text ?? (o.stdin || !process.stdin.isTTY ? readStdin() : undefined);
+	if (!text) die("--text or --stdin required");
+	const res = await owner("POST", `/owner/tasks/${q(id)}/reply`, {
+		text, state: o.state, artifact: !!o.artifact, artifactName: o["artifact-name"], force: !!o.force,
+	});
+	printPush(res);
+	console.log(`${id} -> ${o.state}`);
+}
+
+export async function history(ctx, o) {
+	const rows = await owner("GET", `/owner/history/${q(ctx)}?n=${Number(o.n || 50)}`);
+	if (o.json) return out(rows);
+	for (const e of rows) {
+		const tag = [e.event, e.state || e.role].filter(Boolean).join("/");
+		console.log(`${e.ts} ${(e.dir || "").padEnd(5)} ${(e.peer || "-").padEnd(10)} ${e.task_id || "-"} ${tag}: ${(e.text || "").slice(0, 400)}`);
+	}
+}
+
+export async function contexts() {
+	for (const r of await owner("GET", "/owner/contexts")) console.log(`${r.last}  ${r.context_id}  (${r.entries} entries)`);
+}
+
+// ---------------------------------------------------------------- inbound peer tokens (one per peer label)
+export async function token(action, label, o) {
+	if (action === "list") {
+		for (const r of await owner("GET", "/owner/peers")) {
+			const via = r.source === "pairing" ? `\tvia pairing: code ${r.user_code || "?"}${r.client_name ? `, ${JSON.stringify(r.client_name)}` : ""}` : "";
+			console.log(`${r.label}\tcreated=${r.created_at}\t${r.revoked_at ? "REVOKED " + r.revoked_at : "active"}${via}`);
+		}
+		return;
+	}
+	if (!label) die("label required");
+	if (action === "issue" || action === "rotate") {
+		// rotate replaces an existing label's token; a typo must not silently issue a token under a new label
+		const res = await owner("POST", "/owner/peers", { label, rotate: action === "rotate" || !!o.rotate, mustExist: action === "rotate" });
+		console.log(res.token);
+		console.error(`# label=${res.label}  agent card: ${res.card}  (token shown once; hand it to the peer over a private channel)`);
+		return;
+	}
+	if (action === "revoke") {
+		const r = await ownerTry("DELETE", `/owner/peers/${q(label)}`);
+		// an older Worker answers 200 {"revoked": false} for an unknown label: a typo must never look like success
+		if (r.status === 200 && r.data && r.data.revoked === true) {
+			if (o.json) return out({ revoked: true, label });
+			return console.log(`revoked ${label}: its token gets HTTP 401 from now on`);
+		}
+		if (r.status === 404 || (r.status === 200 && r.data && r.data.revoked === false))
+			die((r.data && r.data.error) || `no active token with label ${label} (see: a2a-exposed token list)`);
+		die(`could not revoke ${label}: ${describeHttp(r.status, r.data)}`);
+	}
+	die(`unknown token action ${action} (issue|list|revoke|rotate)`);
+}
+
+// ---------------------------------------------------------------- outbound peers (agents we call)
+/** Peer tokens follow the usual rule (the environment overrides config.env). When a peer token is set in both and the
+ *  two differ, say so on stderr, naming only the variable (never a value). `justSaved`: the CLI has just written a new
+ *  token to config.env (connect, peers add --token-stdin) that the environment value will keep shadowing. */
+export function warnPeerTokenEnv(key, justSaved = false) {
+	if (!key || !C.envOverridesFile(key)) return false;
+	console.error(justSaved
+		? `warning: ${key} is set in the environment and overrides the token just saved in ${C.CONFIG_FILE}; the next send or poll would still use the environment value. To use the new token: unset ${key} (in the shell or service that sets it)`
+		: `warning: ${key} is set in the environment and overrides the different peer token saved in ${C.CONFIG_FILE}; using the environment value. To use the saved token: unset ${key} (in the shell or service that sets it)`);
+	return true;
+}
+
+/** A peer's bearer token from the environment or config.env, warning when the environment shadows a different saved one. */
+export function peerToken(key) {
+	if (!key) return "";
+	warnPeerTokenEnv(key);
+	return C.get(key);
+}
+
+function resolvePeer(to) {
+	const peers = C.loadPeers();
+	if (peers[to]) {
+		const pe = peers[to];
+		return [to, pe.url.replace(/\/$/, ""), peerToken(pe.token_env)];
+	}
+	if (/^https?:\/\//.test(to)) {
+		for (const [alias, pe] of Object.entries(peers)) if (pe.url.replace(/\/$/, "") === to.replace(/\/$/, "")) return resolvePeer(alias);
+		return [to, to.replace(/\/$/, ""), peerToken("A2A_PEER_TOKEN")];
+	}
+	die(`unknown peer alias ${JSON.stringify(to)} (see: a2a-exposed peers list)`);
+}
+
+export function peers(sub, args, o) {
+	const all = C.loadPeers();
+	if (sub === "add") {
+		const [alias, url] = args;
+		if (!alias || !url) die("usage: peers add <alias> <url> [--token-env VAR | --token-stdin]");
+		if (!/^https?:\/\//.test(url)) die("URL must be http(s)");
+		const tokenEnv = o["token-env"] || C.peerTokenVar(alias);
+		// token_stored is always recorded (true/false); entries without it come from an older CLI (see `peers rm`)
+		all[alias] = { url: url.replace(/\/$/, ""), token_env: tokenEnv, token_stored: false };
+		if (o["token-stdin"]) {
+			const t = readStdin().trim();
+			if (!t) die("no token on stdin");
+			C.saveConfig({ [tokenEnv]: t });
+			all[alias].token_stored = true; // written to config.env by us: `peers rm` removes it again
+			warnPeerTokenEnv(tokenEnv, true);
+		} else if (warnPeerTokenEnv(tokenEnv)) { /* both set and different: warned */ }
+		else if (!C.get(tokenEnv)) console.error(`note: no token stored; set ${tokenEnv} in the environment or ${C.CONFIG_FILE} (or re-run with --token-stdin)`);
+		C.savePeers(all);
+		return console.log(`peer ${alias} -> ${all[alias].url}`);
+	}
+	if (sub === "rm") {
+		const [alias] = args;
+		if (!alias) die("usage: peers rm <alias>");
+		const pe = all[alias];
+		// Tokens the CLI stored in config.env go with the peer: the default PEER_<ALIAS>_TOKEN, a variable stored
+		// with --token-stdin (token_stored: true), and, for entries written by an older CLI (no token_stored
+		// field), whatever --token-env variable they reference, since that CLI stored --token-stdin tokens there
+		// too. Never a variable another peer still uses, never the CLI's own settings, and only from config.env
+		// (CLI-owned): a value that lives only in the process environment is the user's and stays.
+		const vars = new Set([C.peerTokenVar(alias)]);
+		if (pe && pe.token_env && (pe.token_stored === true || !("token_stored" in pe))) vars.add(pe.token_env);
+		delete all[alias];
+		const inUse = new Set(Object.values(all).map((x) => x.token_env));
+		const reserved = (k) => /^(A2A_|CLOUDFLARE_|WAKE_|CF_PROFILE$)/.test(k);
+		const drop = [...vars].filter((k) => !inUse.has(k) && !reserved(k) && k in C.fileConfig());
+		if (!pe && !drop.length) die(`unknown peer alias ${JSON.stringify(alias)} (see: a2a-exposed peers list)`);
+		if (pe) C.savePeers(all);
+		if (drop.length) C.saveConfig(Object.fromEntries(drop.map((k) => [k, null])));
+		return console.log(`removed ${alias}${drop.length ? ` (and ${drop.join(", ")} from ${C.CONFIG_FILE})` : ""}`);
+	}
+	for (const [k, v] of Object.entries(all)) {
+		const te = v.token_env || "";
+		warnPeerTokenEnv(te);
+		console.log(`${k}\t${v.url}\ttoken_env=${te || "-"}\t${te && C.get(te) ? "(set)" : "(missing)"}`);
+	}
+}
+
+async function logHistory(ctx, entry) {
+	try { await owner("POST", "/owner/history", { contextId: ctx, ...entry }); }
+	catch { console.error("warning: could not log history to the worker"); }
+}
+
+export async function send(o) {
+	if (!o.to) die("--to required");
+	const [alias, base, tok] = resolvePeer(o.to);
+	const card = await fetchCard(base);
+	const [url, version] = pickEndpoint(base, card, o.proto);
+	const text = o.text ?? readStdin();
+	const v1 = version.startsWith("1");
+	const msg = { messageId: newId(), role: v1 ? "ROLE_USER" : "user", parts: v1 ? [{ text }] : [{ kind: "text", text }] };
+	if (!v1) msg.kind = "message";
+	if (o.context) msg.contextId = checkId(o.context, "contextId");
+	if (o.task) msg.taskId = checkId(o.task, "taskId");
+	const conf = v1 ? { returnImmediately: true } : { blocking: false };
+	let pushToken = null;
+	if (o.push) {
+		if (!baseUrl()) die("--push needs A2A_BASE_URL (your Worker)");
+		pushToken = randomToken(24);
+		conf[v1 ? "taskPushNotificationConfig" : "pushNotificationConfig"] = { url: baseUrl() + "/push", token: pushToken };
+	}
+	const res = await rpc(url, version, tok, "message/send", "SendMessage", { message: msg, configuration: conf }, { alias: C.loadPeers()[alias] ? alias : null, base });
+	// printed and stored exactly as the peer returned it (1.0: TASK_STATE_* / ROLE_*; 0.3: lowercase)
+	const obj = res && typeof res === "object" && ("task" in res || "message" in res) ? res.task || res.message : res;
+	const isTask = obj && typeof obj === "object" && "status" in obj;
+	const ctx = (obj && obj.contextId) || o.context || newId();
+	const tid = isTask ? obj.id : null;
+	await logHistory(ctx, { dir: "out", peer: alias, taskId: tid, role: "user", text, data: { messageId: msg.messageId, endpoint: url, protocol: version } });
+	if (tid) await owner("POST", "/owner/outbound", { taskId: tid, contextId: ctx, peer: alias, endpoint: url, protocol: version, pushToken, task: obj });
+	else if (obj && obj.parts) await logHistory(ctx, { dir: "in", peer: alias, role: "agent", event: "direct_message", text: textOf(obj) });
+	out(obj);
+	if (tid) console.error(`# task ${tid}: ${plainState(obj)}  (check: a2a-exposed poll --to ${alias} ${tid})`);
+}
+
+export async function poll(taskId, o) {
+	if (!o.to) die("--to required");
+	const [alias, base, tok] = resolvePeer(o.to);
+	const tid = checkId(taskId, "taskId");
+	let rec = {};
+	try { rec = await owner("GET", `/owner/outbound/${q(tid)}`); } catch { rec = {}; }
+	const [url, version] = rec.endpoint ? [rec.endpoint, rec.protocol || "0.3"] : pickEndpoint(base, await fetchCard(base), o.proto);
+	const res = await rpc(url, version, tok, "tasks/get", "GetTask", { id: tid }, { alias: C.loadPeers()[alias] ? alias : null, base });
+	if (rec.endpoint) {
+		await owner("PUT", `/owner/outbound/${q(tid)}`, { task: res });
+		let txt = textOf((res.status || {}).message || {});
+		const arts = (res.artifacts || []).map((x) => textOf(x)).join("\n");
+		if (arts && arts !== txt) txt = (txt ? txt + "\n" : "") + arts;
+		await logHistory(rec.contextId, { dir: "in", peer: alias, taskId: tid, event: "poll", state: plainState(res), text: txt });
+	}
+	out(res);
+	console.error(`# task ${tid}: ${plainState(res)}`);
+}
+
+export const outbound = async (id) => out(await owner("GET", `/owner/outbound/${q(id)}`));

package/lib/config.mjs

@@ -0,0 +1,97 @@
+// Config storage: ~/.config/a2a-exposed/config.env (chmod 600) + peers.json. Before the rename the directory was
+// ~/.config/a2a-over-webhook: when only that one exists it is used as is (nothing is moved or copied).
+// Environment variables always override values from config.env.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** <base>/a2a-exposed, or the pre-rename <base>/a2a-over-webhook when only that exists (an existing deployment). */
+export function defaultConfigDir(base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), exists = fs.existsSync) {
+	const dir = path.join(base, "a2a-exposed"), legacy = path.join(base, "a2a-over-webhook");
+	return !exists(dir) && exists(legacy) ? legacy : dir;
+}
+
+export const CONFIG_DIR = process.env.A2A_CONFIG_DIR || defaultConfigDir();
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.env");
+export const PEERS_FILE = path.join(CONFIG_DIR, "peers.json");
+
+export function parseEnv(text) {
+	const out = {};
+	for (const raw of text.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+		if (!m) continue;
+		let v = m[2];
+		if (v.startsWith('"')) {
+			try { v = JSON.parse(v); } catch { v = v.slice(1, -1); }
+		} else if (v.startsWith("'") && v.endsWith("'")) v = v.slice(1, -1);
+		out[m[1]] = v;
+	}
+	return out;
+}
+
+export function serializeEnv(obj) {
+	const lines = ["# a2a-exposed config (contains secrets: keep chmod 600, never commit)"];
+	for (const [k, v] of Object.entries(obj)) {
+		if (v === undefined || v === null) continue;
+		const s = String(v);
+		lines.push(`${k}=${/^[A-Za-z0-9_./:@+,-]*$/.test(s) ? s : JSON.stringify(s)}`);
+	}
+	return lines.join("\n") + "\n";
+}
+
+let cache = null;
+export function fileConfig() {
+	if (cache) return cache;
+	try { cache = parseEnv(fs.readFileSync(CONFIG_FILE, "utf8")); } catch { cache = {}; }
+	return cache;
+}
+
+/** Value from the environment, else config.env, else default. */
+export function get(key, dflt = "") {
+	const e = process.env[key];
+	if (e !== undefined && e !== "") return e;
+	const f = fileConfig()[key];
+	return f !== undefined && f !== "" ? f : dflt;
+}
+
+function ensureDir() {
+	fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+function writePrivate(file, data) {
+	ensureDir();
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, data, { mode: 0o600 });
+	fs.chmodSync(tmp, 0o600);
+	fs.renameSync(tmp, file);
+}
+
+/** Merge updates into config.env (undefined values are left alone, null removes the key). */
+export function saveConfig(updates) {
+	const cur = { ...fileConfig() };
+	for (const [k, v] of Object.entries(updates)) {
+		if (v === undefined) continue;
+		if (v === null) delete cur[k];
+		else cur[k] = String(v);
+	}
+	writePrivate(CONFIG_FILE, serializeEnv(cur));
+	cache = cur;
+}
+
+export function loadPeers() {
+	try { return JSON.parse(fs.readFileSync(PEERS_FILE, "utf8")) || {}; } catch { return {}; }
+}
+
+export function savePeers(peers) {
+	writePrivate(PEERS_FILE, JSON.stringify(peers, null, 2) + "\n");
+}
+
+/** Set (non-empty) both in the environment and in config.env, with different values: get() returns the environment's. */
+export function envOverridesFile(key) {
+	const e = process.env[key], f = fileConfig()[key];
+	return !!e && !!f && e !== f;
+}
+
+export const peerTokenVar = (alias) => `PEER_${alias.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_TOKEN`;