a2a-exposed 0.0.0-stage → 0.4.1

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "a2a-exposed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "a2a-exposed",
+	"version": "0.4.1",
+	"description": "Give any AI agent a public A2A (Agent2Agent) endpoint: Cloudflare Worker inbox + wake webhook or scheduled inbox checks",
+	"type": "module",
+	"bin": {
+		"a2a-exposed": "bin/a2a-exposed.mjs"
+	},
+	"files": [
+		"bin/",
+		"lib/",
+		"worker/",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"prepack": "node scripts/sync-worker.mjs && node -e \"require('fs').copyFileSync('../LICENSE','LICENSE')\"",
+		"test": "node --test test/*.test.mjs"
+	},
+	"engines": {
+		"node": ">=22.18"
+	},
+	"keywords": [
+		"a2a",
+		"agent2agent",
+		"ai-agent",
+		"webhook",
+		"cloudflare-workers",
+		"d1",
+		"claude-code",
+		"openclaw",
+		"hermes",
+		"cli"
+	],
+	"homepage": "https://github.com/telegraphic-dev/a2a-exposed#readme",
+	"bugs": "https://github.com/telegraphic-dev/a2a-exposed/issues",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/telegraphic-dev/a2a-exposed.git",
+		"directory": "cli"
+	},
+	"license": "MIT",
+	"author": "Telegraphic Developer",
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/worker/cloudflare.config.ts

@@ -0,0 +1,75 @@
+// a2a-exposed Worker configuration. Everything deployment-specific comes from environment
+// variables at deploy time (set by `npx a2a-exposed init|deploy`, or export them yourself;
+// see deploy.env.example). Nothing account- or owner-specific is committed here.
+import { bindings, defineConfig, triggers } from "cf/config";
+import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };
+
+const e: Record<string, string | undefined> = (globalThis as any).process?.env ?? {};
+const v = (k: string) => (e[k] ?? "").trim();
+
+const name = v("A2A_WORKER_NAME") || "a2a-exposed";
+const hostname = v("A2A_HOSTNAME"); // e.g. agent.example.com (on a zone in your account)
+// No hostname: serve on <name>.<account subdomain>.workers.dev instead of a custom domain (and the other way round:
+// with a hostname, the workers.dev route is switched off).
+const workersDev = !hostname;
+const wdSubdomain = v("A2A_WORKERS_DEV_SUBDOMAIN"); // the account's workers.dev subdomain, once known
+// Public base URL for the agent card, derived only from where the Worker is served (no override: a local webhook,
+// Tailnet or tunnel URL must never end up in the card). If still unknown, the Worker uses the request's origin.
+const publicUrl = hostname ? `https://${hostname}` : wdSubdomain ? `https://${name}.${wdSubdomain}.workers.dev` : "";
+
+// Plain (non-secret) vars exposed to the Worker; empty values are omitted.
+const plain: Record<string, string> = {
+	PUBLIC_URL: publicUrl,
+	AGENT_NAME: v("A2A_AGENT_NAME"),
+	AGENT_DESCRIPTION: v("A2A_AGENT_DESCRIPTION"),
+	AGENT_VERSION: v("A2A_AGENT_VERSION"),
+	AGENT_SKILLS: v("A2A_AGENT_SKILLS"), // JSON array of A2A AgentSkill objects
+	PROVIDER_ORGANIZATION: v("A2A_PROVIDER_ORGANIZATION"),
+	PROVIDER_URL: v("A2A_PROVIDER_URL"),
+	DOCUMENTATION_URL: v("A2A_DOCUMENTATION_URL"),
+	WAKE_PRESET: v("WAKE_PRESET") || "generic", // grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | generic
+	WAKE_AGENT_ID: v("WAKE_AGENT_ID"), // openclaw presets (default "main")
+	WAKE_KEY_HEADER: v("WAKE_KEY_HEADER"), // generic preset (default "authorization")
+	WAKE_KEY_PREFIX: e.WAKE_KEY_PREFIX ?? "", // generic preset; unset = "Bearer "
+	WAKE_BODY_TEMPLATE: v("WAKE_BODY_TEMPLATE"), // generic preset JSON template
+	WAKE_CLI_COMMAND: v("WAKE_CLI_COMMAND"), // how the woken agent runs the CLI (default "npx a2a-exposed")
+	WAKE_DEBOUNCE_SECONDS: v("WAKE_DEBOUNCE_SECONDS"),
+	WAKE_MAX_PER_HOUR: v("WAKE_MAX_PER_HOUR"),
+	MAX_BODY: v("A2A_MAX_BODY"),
+	RATE_PER_MIN: v("A2A_RATE_PER_MIN"),
+	RETIRED_HOSTNAMES: v("A2A_RETIRED_HOSTNAMES"), // custom domains this agent moved away from (see movedResponse)
+	PAIRING_APPROVAL: v("PAIRING_APPROVAL") || "human", // device-flow pairing: human (approval password on /device) | agent | off
+	PBKDF2_ITERATIONS: v("A2A_PBKDF2_ITERATIONS"), // approval password hashing; default 100000 (the Workers maximum), at least 50000
+	// proxy / expose mode: forward A2A to an agent that already speaks it, published through a Tunnel hostname behind
+	// Access (never a Tailnet / LAN URL: the Worker can't reach those, and they never appear in the public card)
+	UPSTREAM_URL: v("A2A_UPSTREAM_URL"),
+	UPSTREAM_CARD_URL: v("A2A_UPSTREAM_CARD_URL"), // default <upstream origin>/.well-known/agent-card.json
+};
+const envBindings: Record<string, any> = {
+	DB: bindings.d1(v("A2A_D1_ID") ? { name: v("A2A_D1_NAME") || name, id: v("A2A_D1_ID") } : { name: v("A2A_D1_NAME") || name }),
+};
+for (const [k, val] of Object.entries(plain)) if (val !== "" || (k === "WAKE_KEY_PREFIX" && "WAKE_KEY_PREFIX" in e)) envBindings[k] = bindings.text(val);
+
+// Secrets are uploaded separately (never in this file): OWNER_TOKEN, WAKE_WEBHOOK_URL, WAKE_WEBHOOK_KEY, WAKE_HMAC_SECRET,
+// and in proxy mode UPSTREAM_TOKEN, UPSTREAM_ACCESS_CLIENT_ID, UPSTREAM_ACCESS_CLIENT_SECRET.
+// They are declared only in development mode (`cf dev`), so local dev reads them from .dev.vars while
+// production deploys never fail because an optional wake secret is unset.
+const SECRETS = ["OWNER_TOKEN", "WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "UPSTREAM_TOKEN", "UPSTREAM_ACCESS_CLIENT_ID", "UPSTREAM_ACCESS_CLIENT_SECRET"];
+
+export default defineConfig((ctx) => ({
+	...(v("CLOUDFLARE_ACCOUNT_ID") ? { accountId: v("CLOUDFLARE_ACCOUNT_ID") } : {}),
+	worker: {
+		name,
+		compatibilityDate: "2026-10-06",
+		entrypoint,
+		...(hostname ? { domains: [hostname] } : {}),
+		workersDev,
+		// Optional persisted Workers Logs (A2A_WORKERS_LOGS=1, `init|deploy --workers-logs`): the JSON event lines plus
+		// invocation logs with CPU time. Query strings are redacted, so one-time setup links never reach the logs.
+		...(v("A2A_WORKERS_LOGS") === "1" ? { observability: { enabled: true, redactQueryString: true, logs: { enabled: true, invocationLogs: true } } } : {}),
+		env: ctx.mode === "development" ? { ...envBindings, ...Object.fromEntries(SECRETS.map((k) => [k, bindings.secret()])) } : envBindings,
+		// Optional cron flush of debounced wakes (the Worker also flushes opportunistically on every request).
+		// Requires a workers.dev subdomain on the account (always the case for workers.dev deployments).
+		...(v("A2A_ENABLE_CRON") === "1" ? { triggers: [triggers.scheduled({ schedule: "* * * * *" })] } : {}),
+	},
+}));

package/worker/deploy.env.example

@@ -0,0 +1,33 @@
+# Deploy-time settings for a manual `cf deploy` (the CLI's `init`/`deploy` commands set these for you).
+# Usage: cp deploy.env.example deploy.env && edit && set -a && . ./deploy.env && set +a && cf deploy
+CLOUDFLARE_ACCOUNT_ID=
+# Separate Cloudflare login? Add `--profile <name>` to the cf commands (CLI: --cf-profile <name>).
+A2A_WORKER_NAME=a2a-exposed
+A2A_HOSTNAME=agent.example.com     # leave empty to serve on <worker>.<account-subdomain>.workers.dev
+# A2A_RETIRED_HOSTNAMES=             # old custom domains (comma-separated): card 301 -> PUBLIC_URL, else 410
+# A2A_WORKERS_DEV_SUBDOMAIN=         # the account's workers.dev subdomain, so PUBLIC_URL can be set at deploy time
+A2A_D1_ID=
+# A2A_D1_NAME=a2a-exposed     # D1 database name (CLI: --d1-name; default: the worker name)
+A2A_AGENT_NAME=My Agent
+A2A_AGENT_DESCRIPTION=An AI agent reachable over A2A. Replies asynchronously.
+# A2A_AGENT_SKILLS=[{"id":"general","name":"General requests","description":"...","tags":["assistant"]}]
+# A2A_PROVIDER_ORGANIZATION=
+# A2A_PROVIDER_URL=
+WAKE_PRESET=generic
+# WAKE_AGENT_ID=main
+# WAKE_KEY_HEADER=authorization
+# WAKE_KEY_PREFIX=Bearer 
+# WAKE_BODY_TEMPLATE={"text":"{{summary}}"}
+# Command shown in wake hints (CLI: --cli-command; default "npx a2a-exposed"). Until the CLI is on npm:
+# WAKE_CLI_COMMAND=node /path/to/a2a-exposed/cli/bin/a2a-exposed.mjs
+# WAKE_DEBOUNCE_SECONDS=10
+# WAKE_MAX_PER_HOUR=0
+# A2A_ENABLE_CRON=1
+# Proxy / expose mode (CLI: --upstream, --upstream-card-url): front an agent that already speaks A2A on a private
+# network. The upstream must be reachable from Cloudflare: a Tunnel hostname behind Access, not a Tailnet/LAN URL.
+# A2A_UPSTREAM_URL=https://agent-upstream.example.com/a2a
+# A2A_UPSTREAM_CARD_URL=https://agent-upstream.example.com/.well-known/agent-card.json  # same origin as A2A_UPSTREAM_URL (credentials ride with the fetch)
+# Secrets (OWNER_TOKEN, WAKE_WEBHOOK_URL, WAKE_WEBHOOK_KEY, WAKE_HMAC_SECRET, and for a wake URL behind
+# Cloudflare Access WAKE_ACCESS_CLIENT_ID / WAKE_ACCESS_CLIENT_SECRET; in proxy mode UPSTREAM_TOKEN,
+# UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET) go in a separate chmod-600
+# file passed with `cf deploy --secrets-file <file>`; never commit them.

package/worker/migrations/0001_init.sql

@@ -0,0 +1,74 @@
+-- a2a-over-webhook schema
+CREATE TABLE IF NOT EXISTS peers (
+  label TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL,
+  revoked_at TEXT
+);
+CREATE TABLE IF NOT EXISTS tasks (
+  id TEXT PRIMARY KEY,
+  context_id TEXT NOT NULL,
+  peer TEXT NOT NULL,
+  state TEXT NOT NULL,
+  protocol TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  status_json TEXT NOT NULL,          -- TaskStatus (internal 0.3 shape)
+  artifacts_json TEXT NOT NULL DEFAULT '[]',
+  metadata_json TEXT,
+  push_configs_json TEXT NOT NULL DEFAULT '[]'
+);
+CREATE INDEX IF NOT EXISTS tasks_state ON tasks(state, updated_at);
+CREATE INDEX IF NOT EXISTS tasks_ctx ON tasks(context_id);
+CREATE INDEX IF NOT EXISTS tasks_peer ON tasks(peer, updated_at);
+CREATE TABLE IF NOT EXISTS messages (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  message_id TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  context_id TEXT NOT NULL,
+  role TEXT NOT NULL,
+  ts TEXT NOT NULL,
+  message_json TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS messages_task ON messages(task_id, seq);
+CREATE TABLE IF NOT EXISTS history (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  context_id TEXT NOT NULL,
+  ts TEXT NOT NULL,
+  dir TEXT NOT NULL,                  -- in | out | local
+  peer TEXT,
+  task_id TEXT,
+  role TEXT,
+  state TEXT,
+  event TEXT,
+  text TEXT,
+  data_json TEXT
+);
+CREATE INDEX IF NOT EXISTS history_ctx ON history(context_id, seq);
+CREATE TABLE IF NOT EXISTS outbound (
+  task_id TEXT PRIMARY KEY,
+  context_id TEXT NOT NULL,
+  peer TEXT NOT NULL,
+  endpoint TEXT,
+  protocol TEXT,
+  push_token_hash TEXT,
+  sent_at TEXT NOT NULL,
+  task_json TEXT,
+  updates_json TEXT NOT NULL DEFAULT '[]'
+);
+CREATE TABLE IF NOT EXISTS wakes (
+  context_id TEXT PRIMARY KEY,
+  last_sent_ms INTEGER NOT NULL DEFAULT 0,
+  pending_json TEXT,
+  pending_since_ms INTEGER
+);
+CREATE TABLE IF NOT EXISTS rate (
+  peer TEXT NOT NULL,
+  minute INTEGER NOT NULL,
+  count INTEGER NOT NULL,
+  PRIMARY KEY (peer, minute)
+);
+CREATE TABLE IF NOT EXISTS wake_budget (
+  hour INTEGER PRIMARY KEY,           -- unix hour
+  count INTEGER NOT NULL
+);

package/worker/migrations/0002_wake_budget.sql

@@ -0,0 +1,8 @@
+-- wake_budget (hourly wake cap) for databases whose 0001_init.sql predates the table.
+-- D1 records migrations by file name, so a database created by an earlier build with its own
+-- 0001_init.sql (e.g. the s2a2a prototype) never gets wake_budget from the current 0001.
+-- Idempotent: a no-op on databases created from the current 0001_init.sql.
+CREATE TABLE IF NOT EXISTS wake_budget (
+  hour INTEGER PRIMARY KEY,           -- unix hour
+  count INTEGER NOT NULL
+);

package/worker/migrations/0003_device_pairing.sql

@@ -0,0 +1,39 @@
+-- Device-flow pairing (OAuth 2.0 Device Authorization Grant, RFC 8628): a peer agent asks for a token, the inbox
+-- owner approves it (human: /device page + approval password; agent: owner API), the peer redeems it once.
+-- Numbered 0003 so it never collides with a 0002 migration from another branch; D1 applies unapplied files by name.
+CREATE TABLE IF NOT EXISTS device_requests (
+  device_hash TEXT PRIMARY KEY,         -- sha256(device_code); the device code itself is never stored
+  user_code TEXT NOT NULL UNIQUE,       -- normalised (no dash), e.g. WDJB4827
+  client_id TEXT,
+  client_name TEXT,
+  agent_card_url TEXT,
+  ip TEXT,
+  country TEXT,
+  status TEXT NOT NULL,                 -- pending | approved | denied (| redeemed, just before the row is deleted)
+  created_ms INTEGER NOT NULL,
+  expires_ms INTEGER NOT NULL,
+  interval_s INTEGER NOT NULL,
+  last_poll_ms INTEGER NOT NULL DEFAULT 0,
+  failed_attempts INTEGER NOT NULL DEFAULT 0,
+  label TEXT,                           -- peer label chosen at approval
+  decided_ms INTEGER,
+  decided_by TEXT                       -- human | agent | owner | lockout
+);
+CREATE INDEX IF NOT EXISTS device_requests_status ON device_requests(status, expires_ms);
+-- fixed-window counters: device requests per IP / globally, wrong approval passwords per IP / globally, token polls
+CREATE TABLE IF NOT EXISTS pairing_rate (
+  key TEXT NOT NULL,
+  window_start INTEGER NOT NULL,
+  count INTEGER NOT NULL,
+  expires_ms INTEGER NOT NULL,
+  PRIMARY KEY (key, window_start)
+);
+-- owner settings; approval_password = {"alg":"pbkdf2-sha256","iterations":..,"salt":..,"hash":..,"setAt":..}
+CREATE TABLE IF NOT EXISTS settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+-- where a peer token came from: NULL = `token issue`, 'pairing' = device flow (with the user code it was approved under)
+ALTER TABLE peers ADD COLUMN source TEXT;
+ALTER TABLE peers ADD COLUMN user_code TEXT;
+ALTER TABLE peers ADD COLUMN client_name TEXT;

package/worker/migrations/0004_pairing_replace.sql

@@ -0,0 +1,6 @@
+-- Re-pairing: a requester that presents its current active token (Authorization: Bearer) replaces that token on
+-- approval. The new token takes over the label, so no orphan token or "-2" label is left. replaces_hash binds the
+-- request to the token that was presented: if the owner rotates or revokes that token before redemption, the swap
+-- is refused and a fresh label is used instead (a holder of a compromised old token cannot overwrite a rotated one).
+ALTER TABLE device_requests ADD COLUMN replaces_label TEXT;
+ALTER TABLE device_requests ADD COLUMN replaces_hash TEXT;

package/worker/migrations/0005_facade_owners.sql

@@ -0,0 +1,9 @@
+-- Proxy / expose mode (UPSTREAM_URL): which peer label created each upstream task and context, so peers that share
+-- the façade's one upstream credential can't read, cancel or continue each other's tasks. Unused in inbox mode.
+CREATE TABLE IF NOT EXISTS facade_owners (
+	kind TEXT NOT NULL,        -- 'task' | 'context'
+	id TEXT NOT NULL,          -- the upstream's task / context id
+	peer TEXT NOT NULL,        -- peer label (peers.label) that created it through the façade
+	created_at TEXT NOT NULL,
+	PRIMARY KEY (kind, id)
+);

package/worker/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "a2a-exposed-worker",
+	"private": true,
+	"type": "module",
+	"description": "Cloudflare Worker for a2a-exposed: public A2A endpoint, D1 inbox, wake webhooks, owner API",
+	"license": "MIT",
+	"scripts": {
+		"build": "cf build",
+		"deploy": "cf deploy",
+		"test": "node --test test/*.test.ts",
+		"typecheck": "cf workers types && tsc"
+	},
+	"engines": { "node": ">=22.18" },
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "beta",
+		"cf": "^1.0.0-beta.13",
+		"typescript": "^7.0.2",
+		"vite": "^8.3.0"
+	}
+}

package/worker/src/a2a.ts

@@ -0,0 +1,216 @@
+// A2A data-model helpers. Internal storage uses the A2A 0.3 JSON shape
+// (lowercase states, role user/agent, parts with "kind"); converters emit A2A 1.0.
+
+export type Json = any;
+export const TERMINAL = new Set(["completed", "failed", "canceled", "rejected"]);
+export const OPEN = new Set(["submitted", "working"]);
+export const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export class InvalidParams extends Error {}
+
+/** Response for a request on a hostname this agent moved away from (RETIRED_HOSTNAMES, comma-separated), else null.
+ *  Custom domains are not detached by a deploy, so after `--workers-dev` (or a hostname change) the old hostname
+ *  would keep serving: instead it redirects agent-card discovery (301) and answers everything else with 410 Gone. */
+export function movedResponse(reqUrl: string, publicUrl: string, retiredCsv: string | undefined): { status: number; headers: Record<string, string>; body: string } | null {
+	const retired = (retiredCsv || "").split(",").map((h) => h.trim().toLowerCase()).filter(Boolean);
+	if (!retired.length) return null;
+	const u = new URL(reqUrl);
+	if (!retired.includes(u.hostname.toLowerCase())) return null;
+	const base = (publicUrl || "").replace(/\/$/, "");
+	if (base && new URL(base).hostname.toLowerCase() === u.hostname.toLowerCase()) return null; // never retire the live URL
+	const card = base ? `${base}/.well-known/agent-card.json` : "";
+	if (card && (u.pathname === "/.well-known/agent-card.json" || u.pathname === "/.well-known/agent.json"))
+		return { status: 301, headers: { location: card, "cache-control": "no-store" }, body: "" };
+	return {
+		status: 410, headers: { "content-type": "application/json" },
+		body: JSON.stringify({ error: "moved", message: `this agent moved${base ? ` to ${base}` : ""}; update the URL you use for it`, ...(card ? { agentCard: card } : {}) }),
+	};
+}
+
+/** Hosts that only resolve on a private network (Tailnet, LAN, loopback): never a public agent URL. */
+export function isPrivateHost(host: string): boolean {
+	const h = 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;
+}
+
+/** The base URL the agent card advertises: the deployment's PUBLIC_URL (custom hostname or workers.dev, set at deploy
+ *  time) when it is a public https origin, else the origin the request reached the Worker on. A local, Tailnet or
+ *  plain-http URL is never advertised to peers. */
+export function publicOrigin(configured: string | undefined, reqUrl: string): string {
+	try {
+		const u = new URL((configured || "").trim());
+		if (u.protocol === "https:" && !u.username && !u.password && !isPrivateHost(u.hostname)) return u.origin;
+	} catch { /* empty or not a URL */ }
+	return new URL(reqUrl).origin;
+}
+
+export const nowIso = () => new Date().toISOString();
+export const newId = () => crypto.randomUUID();
+
+export function checkId(v: unknown, what = "id"): string {
+	if (typeof v !== "string" || !ID_RE.test(v)) throw new InvalidParams(`invalid ${what}`);
+	return v;
+}
+
+const v1State = (s: string) => "TASK_STATE_" + s.toUpperCase().replace(/-/g, "_");
+export const fromV1State = (s: string) =>
+	typeof s === "string" && s.startsWith("TASK_STATE_") ? s.slice(11).toLowerCase().replace(/_/g, "-") : s;
+const normRole = (r: unknown) => (String(r || "").toLowerCase().includes("agent") ? "agent" : "user");
+
+export function normPart(part: Json): Json {
+	if (!part || typeof part !== "object" || Array.isArray(part)) throw new InvalidParams("part must be an object");
+	const kind = part.kind;
+	let out: Json;
+	if (kind === "text" || (kind === undefined && "text" in part)) {
+		if (typeof part.text !== "string") throw new InvalidParams("text part needs string text");
+		out = { kind: "text", text: part.text };
+	} else if (kind === "data" || (kind === undefined && "data" in part)) {
+		out = { kind: "data", data: part.data };
+	} else if (kind === "file" || (kind === undefined && ("raw" in part || "url" in part))) {
+		const f: Json = { ...(part.file || {}) };
+		if ("raw" in part) f.bytes = part.raw;
+		if ("url" in part) f.uri = part.url;
+		if (part.filename) f.name = part.filename;
+		if (part.mediaType) f.mimeType = part.mediaType;
+		out = { kind: "file", file: f };
+	} else throw new InvalidParams("unsupported part type");
+	if (part.metadata !== undefined) out.metadata = part.metadata;
+	return out;
+}
+
+export function normMessage(msg: Json): Json {
+	if (!msg || typeof msg !== "object") throw new InvalidParams("message must be an object");
+	if (!Array.isArray(msg.parts) || msg.parts.length === 0) throw new InvalidParams("message.parts must be a non-empty array");
+	const out: Json = {
+		kind: "message",
+		role: normRole(msg.role),
+		messageId: typeof msg.messageId === "string" && msg.messageId ? msg.messageId.slice(0, 200) : newId(),
+		parts: msg.parts.slice(0, 100).map(normPart),
+	};
+	for (const k of ["contextId", "taskId", "metadata", "referenceTaskIds", "extensions"])
+		if (msg[k] !== undefined && msg[k] !== null) out[k] = msg[k];
+	return out;
+}
+
+function partToV1(p: Json): Json {
+	let out: Json;
+	if (p.kind === "text") out = { text: p.text };
+	else if (p.kind === "data") out = { data: p.data };
+	else {
+		const f = p.file || {};
+		out = {};
+		if ("bytes" in f) out.raw = f.bytes;
+		if ("uri" in f) out.url = f.uri;
+		if (f.name) out.filename = f.name;
+		if (f.mimeType) out.mediaType = f.mimeType;
+	}
+	if (p.metadata !== undefined) out.metadata = p.metadata;
+	return out;
+}
+
+export function messageToV1(m: Json): Json {
+	const { kind, parts, role, ...rest } = m;
+	return { ...rest, role: role === "agent" ? "ROLE_AGENT" : "ROLE_USER", parts: (parts || []).map(partToV1) };
+}
+
+/** Serialise an internal task for the given protocol version. */
+export function publicTask(task: Json, version: string, historyLength?: number | null): Json {
+	const t: Json = { kind: "task", id: task.id, contextId: task.contextId, status: task.status, artifacts: task.artifacts || [] };
+	if (task.metadata) t.metadata = task.metadata;
+	let hist: Json[] = task.history || [];
+	if (historyLength !== undefined && historyLength !== null) hist = historyLength > 0 ? hist.slice(-historyLength) : [];
+	if (hist.length) t.history = hist;
+	if (version.startsWith("1")) {
+		delete t.kind;
+		const st: Json = { ...t.status, state: v1State(t.status.state) };
+		if (st.message) st.message = messageToV1(st.message);
+		t.status = st;
+		if (t.history) t.history = t.history.map(messageToV1);
+		t.artifacts = t.artifacts.map((a: Json) => ({ ...a, parts: a.parts.map(partToV1) }));
+	}
+	return t;
+}
+
+/** Peer task (0.3 or 1.0) -> internal-ish shape (used only to read state/text; store and show the wire shape). */
+export function taskFromAny(t: Json): Json {
+	if (!t || typeof t !== "object") return t;
+	const out = { ...t };
+	if (out.status && typeof out.status === "object") {
+		const st = { ...out.status, state: fromV1State(out.status.state) };
+		if (st.message) try { st.message = normMessage(st.message); } catch { /* keep */ }
+		out.status = st;
+	}
+	return out;
+}
+
+export function textOf(m: Json): string {
+	const parts = Array.isArray(m) ? m : (m && m.parts) || [];
+	const out: string[] = [];
+	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 {
+			const f = x.file || {};
+			out.push(`[file ${f.name || x.filename || f.uri || x.url || ""}]`);
+		}
+	}
+	return out.join("\n");
+}
+
+export async function sha256(s: string): Promise<string> {
+	const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+	return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** First 12 hex chars of sha256(value), or null when unset: lets the owner compare secrets without revealing them. */
+export async function fingerprint(v: string | undefined | null): Promise<string | null> {
+	return v ? (await sha256(v)).slice(0, 12) : null;
+}
+
+/** Peer token: "a2aow_" + 43 base64url chars (32 random bytes). Only the SHA-256 hash is stored and
+ *  lookups are by hash, so tokens issued with the earlier "s2a_" prefix keep working. */
+export const PEER_TOKEN_PREFIX = "a2aow_";
+
+export function randomToken(prefix = PEER_TOKEN_PREFIX): string {
+	const b = new Uint8Array(32);
+	crypto.getRandomValues(b);
+	return prefix + btoa(String.fromCharCode(...b)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function timingSafeEqualStr(a: string, b: string): boolean {
+	const ea = new TextEncoder().encode(a), eb = new TextEncoder().encode(b);
+	if (ea.length !== eb.length) return false;
+	let r = 0;
+	for (let i = 0; i < ea.length; i++) r |= ea[i] ^ eb[i];
+	return r === 0;
+}
+
+/** Push URLs must be https and not obvious private/loopback literals. */
+export function pushUrlAllowed(url: string): [boolean, string] {
+	let u: URL;
+	try { u = new URL(url); } catch { return [false, "bad url"]; }
+	if (u.protocol !== "https:") return [false, "https required"];
+	const h = u.hostname.replace(/^\[|\]$/g, "");
+	if (/^(localhost|.*\.local|.*\.internal)$/i.test(h)) return [false, "private host not allowed"];
+	if (/^\d+\.\d+\.\d+\.\d+$/.test(h) && /^(10\.|127\.|0\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/.test(h))
+		return [false, "private address not allowed"];
+	if (h.includes(":") && /^(::1?$|fc|fd|fe80|::ffff:)/i.test(h)) return [false, "private address not allowed"];
+	return [true, ""];
+}