a2acalling 0.5.4 → 0.6.0

package/README.md

@@ -33,7 +33,7 @@ a2a create --name "My Agent" --owner "Your Name" --tier friends
 # Output:
 # 🤝 Your Name is inviting you to connect agents!
 # Your agent can reach My Agent for: chat, web, files
-# a2a://random-name.trycloudflare.com:443/fed_abc123xyz
+# a2a://your-host.com/fed_abc123xyz
 ```
 
 ### Call someone else's agent
@@ -74,9 +74,9 @@ node scripts/install-openclaw.js setup
 
 Setup behavior:
 - Runtime auto-detects OpenClaw when available and falls back to generic mode if unavailable.
-- If OpenClaw gateway is detected, dashboard is exposed on gateway at `/a2a` (proxied to A2A backend).
+- If OpenClaw gateway is detected, dashboard is exposed on gateway at `/a2a` and A2A API at `/api/a2a/*` (proxied to A2A backend).
 - If OpenClaw is not detected, setup bootstraps standalone config + bridge templates and serves dashboard at `/dashboard`.
-- If no public hostname is configured, setup defaults to secure Cloudflare Quick Tunnel for internet-facing invites.
+- Setup inspects port 80 and prints reverse proxy guidance for stable internet-facing ingress.
 - Setup prints the exact dashboard URL at the end.
 
 Before the first `a2a call`, the owner must set permissions and disclosure tiers. Run onboarding first:
@@ -369,9 +369,8 @@ app.listen(3001);
 
 | Variable | Description |
 |----------|-------------|
-| `A2A_HOSTNAME` | Hostname for invite URLs (required for creates) |
+| `A2A_HOSTNAME` | Hostname for invite URLs (required for internet-facing invites) |
 | `A2A_PORT` | Server port (default: 3001) |
-| `A2A_DISABLE_QUICK_TUNNEL` | Set `true` to disable auto Cloudflare Quick Tunnel host resolution |
 | `A2A_CONFIG_DIR` | Config directory (default: `~/.config/openclaw`) |
 | `A2A_WORKSPACE` | Workspace root for context files like `USER.md` (default: current directory) |
 | `A2A_RUNTIME` | Runtime mode: `auto` (default), `openclaw`, or `generic` |

package/SKILL.md

@@ -53,9 +53,10 @@ Extract: professional context, interests, goals, skills, sensitive areas. Group
 
 ## Network Ingress (Internet-Facing Invites)
 
-- By default, A2A now prefers a secure Quick Tunnel endpoint for invite URLs when no public hostname is configured.
-- If the owner has custom infrastructure (domain, reverse proxy, managed tunnel), they can set `A2A_HOSTNAME` to their own public endpoint and bypass Quick Tunnel.
-- Managed/domain-specific ingress automation is intentionally not bundled yet. Advanced users can implement it based on their own network and security requirements.
+- A2A does not bundle an auto-tunneling service for internet-facing ingress.
+- For stable internet-facing invites, set `A2A_HOSTNAME` to your public endpoint (domain or public IP).
+- Recommended: run the A2A backend on an internal port and expose it via a reverse proxy on `:443` (HTTPS) or `:80` (HTTP), routing `/api/a2a/*` to the backend.
+- `npx a2acalling setup` inspects port 80 and prints reverse proxy guidance + an external reachability check.
 
 ## Commands
 

package/bin/cli.js

@@ -170,15 +170,13 @@ async function resolveInviteHostname() {
     const config = new A2AConfig();
     const resolved = await resolveInviteHost({
       config,
-      defaultPort: process.env.PORT || process.env.A2A_PORT || 3001,
-      preferQuickTunnel: true
+      defaultPort: process.env.PORT || process.env.A2A_PORT || 3001
     });
     return resolved;
   } catch (err) {
     return resolveInviteHost({
       fallbackHost: process.env.OPENCLAW_HOSTNAME || process.env.HOSTNAME || 'localhost',
-      defaultPort: process.env.PORT || process.env.A2A_PORT || 3001,
-      preferQuickTunnel: true
+      defaultPort: process.env.PORT || process.env.A2A_PORT || 3001
     });
   }
 }

package/docs/protocol.md

@@ -259,13 +259,16 @@ Owner can reply to inject into the conversation.
 
 ## OpenClaw Integration
 
-### Gateway Route Registration
+### Gateway Proxy (Recommended)
 
-Add to gateway routes:
-```javascript
-const a2a = require('./skills/a2a/scripts/server');
-app.use('/api/a2a', a2a);
-```
+Run A2A Calling as its own server (separate process), and let the OpenClaw gateway proxy to it:
+
+- A2A backend (separate): `a2a server --port 3001`
+- OpenClaw gateway path(s):
+  - `/a2a` proxies to the A2A dashboard UI (`/dashboard`)
+  - `/api/a2a/*` proxies to the A2A backend API
+
+This keeps the A2A server decoupled from OpenClaw's gateway runtime while still allowing the gateway to be the single public entry point.
 
 ### Agent Context
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2acalling",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Agent-to-agent calling for OpenClaw - A2A agent communication",
   "main": "src/index.js",
   "bin": {

package/scripts/install-openclaw.js

@@ -4,11 +4,11 @@
  *
  * Supports automatic setup:
  * - If OpenClaw gateway is detected, install a gateway HTTP proxy plugin
- *   so dashboard is accessible at /a2a on gateway.
+ *   so dashboard and A2A API are accessible at /a2a and /api/a2a on gateway.
  * - If gateway is not detected, dashboard runs on standalone A2A server.
  * - If OpenClaw is not installed, bootstrap standalone runtime templates.
- * - If no public hostname is configured, default to secure Quick Tunnel
- *   for internet-facing invite URLs (lazy cloudflared download).
+ * - Networking-aware: inspects port 80 and prints reverse proxy guidance
+ *   for stable internet-facing ingress.
  *
  * Usage:
  *   npx a2acalling install
@@ -20,6 +20,8 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
 const { execSync } = require('child_process');
 
 // Paths
@@ -287,8 +289,8 @@ echo "a2a notify: $payload" >&2
 
 const DASHBOARD_PLUGIN_MANIFEST = {
   id: DASHBOARD_PLUGIN_ID,
-  name: 'A2A Dashboard Proxy',
-  description: 'Proxy A2A dashboard routes through OpenClaw gateway',
+  name: 'A2A Gateway Proxy',
+  description: 'Proxy A2A API + dashboard routes through OpenClaw gateway (backend runs separately)',
   version: '1.0.0',
   configSchema: {
     type: 'object',
@@ -309,7 +311,7 @@ import https from "node:https";
 
 const PLUGIN_ID = "a2a-dashboard-proxy";
 const UI_PREFIX = "/a2a";
-const API_PREFIX = "/api/a2a/dashboard";
+const API_PREFIX = "/api/a2a";
 
 function sendJson(res: ServerResponse, status: number, body: unknown) {
   res.statusCode = status;
@@ -364,8 +366,8 @@ function rewriteUiPath(pathname: string): string {
 
 const plugin = {
   id: PLUGIN_ID,
-  name: "A2A Dashboard Proxy",
-  description: "Proxy A2A dashboard routes through OpenClaw gateway",
+  name: "A2A Gateway Proxy",
+  description: "Proxy A2A API + dashboard routes through OpenClaw gateway (backend runs separately)",
   configSchema: {
     type: "object" as const,
     additionalProperties: false,
@@ -423,11 +425,12 @@ const plugin = {
 
       proxyReq.on("error", (err) => {
         const backend = backendBase.toString();
+        const suggestedPort = backendBase.port || (backendBase.protocol === "https:" ? "443" : "80");
         if (isApi) {
           sendJson(res, 502, {
             success: false,
-            error: "dashboard_backend_unreachable",
-            message: \`Could not reach A2A server at \${backend}: \${err.message}\`
+            error: "a2a_backend_unreachable",
+            message: \`Could not reach A2A backend at \${backend}: \${err.message}\`
           });
           return;
         }
@@ -438,7 +441,7 @@ const plugin = {
   <h1>A2A Dashboard Unavailable</h1>
   <p>The gateway proxy is active, but the A2A backend is not reachable.</p>
   <p>Expected backend: <code>\${backend}</code></p>
-  <p>Start the backend with: <code>a2a server --port 3001</code></p>
+  <p>Start the backend with: <code>a2a server --port \${suggestedPort}</code></p>
 </body></html>\`);
       });
 
@@ -491,69 +494,221 @@ function readExistingConfiguredInviteHost() {
     if (!parsed.hostname || isLocalOrUnroutableHost(parsed.hostname)) {
       return '';
     }
+    // Legacy: Cloudflare quick tunnels are ephemeral and no longer supported.
+    if (String(parsed.hostname).toLowerCase().endsWith('.trycloudflare.com')) {
+      return '';
+    }
     return existing;
   } catch (err) {
     return '';
   }
 }
 
-async function maybeSetupQuickTunnel(port) {
-  const disabled = Boolean(flags['no-quick-tunnel']) ||
-    String(process.env.A2A_DISABLE_QUICK_TUNNEL || '').toLowerCase() === 'true';
-  if (disabled) return null;
-
+function safeJsonParse(text) {
   try {
-    const { ensureQuickTunnel } = require('../src/lib/quick-tunnel');
-    const tunnel = await ensureQuickTunnel({ localPort: Number.parseInt(String(port), 10) || 3001 });
-    if (!tunnel || !tunnel.host) return null;
-    return {
-      ...tunnel,
-      inviteHost: `${tunnel.host}:443`
-    };
+    return JSON.parse(String(text || ''));
   } catch (err) {
-    warn(`Quick Tunnel setup failed: ${err.message}`);
-    warn('Falling back to direct host invites (may require firewall/NAT config).');
     return null;
   }
 }
 
+function looksLikePong(body) {
+  const parsed = safeJsonParse(body);
+  if (parsed && typeof parsed === 'object' && parsed.pong === true) return true;
+  return String(body || '').includes('"pong":true') || String(body || '').includes('"pong": true');
+}
+
+function fetchUrlText(url, timeoutMs = 5000) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      reject(new Error('invalid_url'));
+      return;
+    }
+
+    const client = parsed.protocol === 'https:' ? https : http;
+    const req = client.request({
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      method: 'GET',
+      path: parsed.pathname + parsed.search,
+      headers: {
+        'User-Agent': `a2acalling/${process.env.npm_package_version || 'dev'} (setup-check)`
+      },
+      timeout: timeoutMs
+    }, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+
+      res.on('data', (chunk) => {
+        data += chunk;
+        if (data.length > 1024 * 256) {
+          req.destroy(new Error('response_too_large'));
+        }
+      });
+
+      res.on('end', () => {
+        resolve({
+          statusCode: res.statusCode || 0,
+          headers: res.headers || {},
+          body: data
+        });
+      });
+    });
+
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('timeout')));
+    req.end();
+  });
+}
+
+async function probeLocalA2APing(port) {
+  try {
+    const res = await fetchUrlText(`http://127.0.0.1:${port}/api/a2a/ping`, 900);
+    return { ok: looksLikePong(res.body), statusCode: res.statusCode, body: res.body };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : 'request_failed' };
+  }
+}
+
+async function scanPort80() {
+  const { isPortListening, tryBindPort } = require('../src/lib/port-scanner');
+
+  const listening = await isPortListening(80, '127.0.0.1', { timeoutMs: 500 });
+  const bind = await tryBindPort(80, '0.0.0.0');
+  const a2aPing = listening.listening ? await probeLocalA2APing(80) : { ok: false };
+
+  return {
+    listening: Boolean(listening.listening),
+    listeningCode: listening.code,
+    bindOk: Boolean(bind.ok),
+    bindCode: bind.code,
+    a2aPingOk: Boolean(a2aPing.ok),
+    a2aPingStatusCode: a2aPing.statusCode,
+    a2aPingError: a2aPing.error
+  };
+}
+
+async function externalPingCheck(targetUrl) {
+  const providers = [
+    {
+      name: 'allorigins',
+      buildUrl: () => {
+        const u = new URL('https://api.allorigins.win/raw');
+        u.searchParams.set('url', targetUrl);
+        return u.toString();
+      }
+    },
+    {
+      name: 'jina',
+      buildUrl: () => `https://r.jina.ai/${targetUrl}`
+    }
+  ];
+
+  const attempts = [];
+  for (const provider of providers) {
+    const providerUrl = provider.buildUrl();
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const res = await fetchUrlText(providerUrl, 8000);
+      const ok = looksLikePong(res.body);
+      attempts.push({ provider: provider.name, ok, statusCode: res.statusCode });
+      if (ok) {
+        return { ok: true, provider: provider.name, statusCode: res.statusCode, attempts };
+      }
+    } catch (err) {
+      attempts.push({ provider: provider.name, ok: false, error: err && err.message ? err.message : 'request_failed' });
+    }
+  }
+
+  return { ok: false, attempts };
+}
+
 async function install() {
   log('Installing A2A Calling...\n');
 
   const localHostname = process.env.HOSTNAME || 'localhost';
 
-  // Port scanning: use explicit port or scan for available one
-  let port;
+  // Networking scan (port 80) + backend port selection.
+  const port80 = await scanPort80();
+  if (port80.a2aPingOk) {
+    log('Port 80 already serves /api/a2a/ping (A2A detected on :80).');
+  } else if (port80.listening) {
+    warn(`Port 80 is already bound (${port80.listeningCode || 'in_use'}). Setup will use an internal port and recommend reverse proxy routing.`);
+  } else if (!port80.bindOk && port80.bindCode === 'EACCES') {
+    warn('Port 80 appears free but is not bindable by this user (EACCES). Setup will use an unprivileged port unless you run with elevated privileges.');
+  } else if (port80.bindOk) {
+    log('Port 80 is bindable by this user (recommended for inbound A2A if you intend to serve directly on :80).');
+  }
+
+  let backendPort = null;
   if (flags.port) {
-    port = String(flags.port);
+    backendPort = Number.parseInt(String(flags.port), 10);
   } else if (process.env.A2A_PORT) {
-    port = String(process.env.A2A_PORT);
+    backendPort = Number.parseInt(String(process.env.A2A_PORT), 10);
   } else {
-    try {
-      const { findAvailablePort } = require('../src/lib/port-scanner');
-      const available = await findAvailablePort([80, 3001, 8080, 8443, 9001]);
-      port = available ? String(available) : '3001';
-      if (available === 80) {
-        log(`Port 80 is available (recommended for inbound A2A connections)`);
-      } else if (available) {
-        log(`Auto-detected available port: ${available}`);
+    if (port80.bindOk && !port80.listening) {
+      backendPort = 80;
+    } else {
+      try {
+        const { findAvailablePort } = require('../src/lib/port-scanner');
+        backendPort = await findAvailablePort([3001, 8080, 8443, 9001]);
+      } catch (e) {
+        backendPort = null;
       }
-    } catch (e) {
-      port = '3001';
+      if (!backendPort) {
+        backendPort = 3001;
+      }
+      log(`Auto-detected available internal port: ${backendPort}`);
     }
   }
-  const backendUrl = flags['dashboard-backend'] || `http://127.0.0.1:${port}`;
+  if (!Number.isFinite(backendPort) || backendPort <= 0 || backendPort > 65535) {
+    backendPort = 3001;
+  }
+
+  const backendUrl = flags['dashboard-backend'] || `http://127.0.0.1:${backendPort}`;
+
+  // Invite host selection: explicit > existing configured public host > auto resolve to external IP.
   const explicitInviteHost = flags.hostname ||
     process.env.A2A_HOSTNAME ||
     process.env.OPENCLAW_HOSTNAME ||
     readExistingConfiguredInviteHost();
-  const quickTunnel = explicitInviteHost ? null : await maybeSetupQuickTunnel(port);
-  const inviteHost = explicitInviteHost || (quickTunnel && quickTunnel.inviteHost) || `${localHostname}:${port}`;
+
+  let inviteHost = explicitInviteHost;
+  let inviteHostWarnings = [];
+
+  if (!inviteHost) {
+    try {
+      const { A2AConfig } = require('../src/lib/config');
+      const { resolveInviteHost } = require('../src/lib/invite-host');
+      const config = new A2AConfig();
+      const inviteDefaultPort = port80.listening ? 80 : backendPort;
+      const resolved = await resolveInviteHost({
+        config,
+        fallbackHost: localHostname,
+        defaultPort: inviteDefaultPort,
+        refreshExternalIp: true
+      });
+      inviteHost = resolved.host;
+      inviteHostWarnings = resolved.warnings || [];
+    } catch (err) {
+      inviteHost = `${localHostname}:${backendPort}`;
+    }
+  }
+
+  for (const w of inviteHostWarnings) {
+    warn(w);
+  }
+
   const forceStandalone = Boolean(flags.standalone) || String(process.env.A2A_FORCE_STANDALONE || '').toLowerCase() === 'true';
   const hasOpenClawBinary = commandExists('openclaw');
   const hasOpenClawConfig = fs.existsSync(OPENCLAW_CONFIG);
   const hasOpenClaw = !forceStandalone && (hasOpenClawBinary || hasOpenClawConfig);
   let standaloneBootstrap = null;
+  const forceHostname = Boolean(flags.hostname || process.env.A2A_HOSTNAME || process.env.OPENCLAW_HOSTNAME) || !explicitInviteHost;
 
   if (hasOpenClaw) {
     // 1. Create skills directory if needed
@@ -571,13 +726,13 @@ async function install() {
     log(`Installed skill to: ${skillDir}`);
 
     // Ensure config and manifest exist even in OpenClaw path
-    ensureConfigAndManifest(inviteHost, port, {
-      forceHostname: Boolean(flags.hostname || process.env.A2A_HOSTNAME || process.env.OPENCLAW_HOSTNAME || quickTunnel)
+    ensureConfigAndManifest(inviteHost, backendPort, {
+      forceHostname
     });
   } else {
     warn('OpenClaw not detected. Enabling standalone A2A bootstrap.');
-    standaloneBootstrap = ensureStandaloneBootstrap(inviteHost, port, {
-      forceHostname: Boolean(flags.hostname || process.env.A2A_HOSTNAME || process.env.OPENCLAW_HOSTNAME || quickTunnel)
+    standaloneBootstrap = ensureStandaloneBootstrap(inviteHost, backendPort, {
+      forceHostname
     });
   }
 
@@ -586,7 +741,7 @@ async function install() {
   let configUpdated = false;
   let gatewayDetected = false;
   let dashboardMode = 'standalone';
-  let dashboardUrl = `http://${localHostname}:${port}/dashboard`;
+  let dashboardUrl = `http://${localHostname}:${backendPort}/dashboard`;
 
   if (config) {
     // Add custom command for each enabled channel
@@ -650,12 +805,76 @@ async function install() {
     ? 'Runtime auto-selects OpenClaw when available and falls back to generic if needed.'
     : 'Runtime defaults to generic fallback (no OpenClaw dependency required).';
 
+  const { splitHostPort, isLocalOrUnroutableHost } = require('../src/lib/invite-host');
+  const inviteParsed = splitHostPort(inviteHost);
+  const invitePort = inviteParsed.port;
+  const inviteScheme = (!invitePort || invitePort === 443) ? 'https' : 'http';
+  const invitePingUrl = `${inviteScheme}://${inviteHost}/api/a2a/ping`;
+  const inviteLooksLocal = isLocalOrUnroutableHost(inviteParsed.hostname);
+  const expectsReverseProxy = Boolean(
+    (invitePort === 80 && backendPort !== 80) ||
+    ((!invitePort || invitePort === 443) && backendPort !== 443)
+  );
+
+  let externalPing = null;
+  if (!inviteLooksLocal && inviteParsed.hostname) {
+    externalPing = await externalPingCheck(invitePingUrl);
+  }
+
   console.log(`
 ${bold('━━━ Server Setup ━━━')}
 
 To receive incoming calls and host A2A APIs:
 
-  ${green(`A2A_HOSTNAME="${inviteHost}" a2a server --port ${port}`)}
+  ${green(`A2A_HOSTNAME="${inviteHost}" a2a server --port ${backendPort}`)}
+
+${bold('━━━ Ingress Setup ━━━')}
+
+Invite host: ${green(inviteHost)}
+Expected ping URL: ${green(invitePingUrl)}
+
+Port 80 scan:
+  ${port80.a2aPingOk
+    ? green('Port 80 responds to /api/a2a/ping (A2A ready on :80)')
+    : port80.listening
+    ? yellow(`Port 80 has a listener (${port80.listeningCode || 'in_use'})`)
+    : port80.bindOk
+    ? green('Port 80 is free and bindable by this user')
+    : yellow(`Port 80 not bindable (${port80.bindCode || 'unknown'})`)}
+
+${expectsReverseProxy
+  ? `Reverse proxy required:
+  Route ${green('/api/a2a/*')} -> ${green(backendUrl)}
+  Route ${green('/a2a/*')} -> ${green(backendUrl.replace(/\/$/, ''))}${green('/dashboard/*')} (optional dashboard)
+
+  Example (Caddy):
+  ${green(`YOUR_DOMAIN {
+    handle /api/a2a/* {
+      reverse_proxy 127.0.0.1:${backendPort}
+    }
+    handle /a2a* {
+      uri replace /a2a /dashboard
+      reverse_proxy 127.0.0.1:${backendPort}
+    }
+  }`)}
+
+  Example (nginx):
+  ${green(`location /api/a2a/ {
+    proxy_pass http://127.0.0.1:${backendPort}/api/a2a/;
+  }
+  location = /a2a { return 301 /a2a/; }
+  location /a2a/ {
+    proxy_pass http://127.0.0.1:${backendPort}/dashboard/;
+  }`)}`
+  : 'Reverse proxy not required for the selected invite host.'}
+
+${bold('━━━ External Ping ━━━')}
+
+${inviteLooksLocal
+  ? yellow('Skipped external ping: invite host looks local/unroutable. Set --hostname to a public endpoint to enable this check.')
+  : externalPing && externalPing.ok
+  ? green(`External ping OK via ${externalPing.provider}`)
+  : yellow(`External ping FAILED (expected if the server is not running yet, or ingress is not publicly reachable).`)}
 
 ${bold('━━━ Dashboard Setup ━━━')}
 
@@ -663,18 +882,12 @@ Mode: ${dashboardMode === 'gateway' ? green('gateway') : yellow('standalone')}
 Dashboard URL: ${green(dashboardUrl)}
 
 ${dashboardMode === 'gateway'
-  ? `Gateway path /a2a is now proxied to ${backendUrl}.`
+  ? `Gateway paths /a2a and /api/a2a/* are now proxied to ${backendUrl}.`
   : 'No gateway detected. Dashboard is served directly from the A2A server.'}
 
 ${bold('━━━ Runtime Setup ━━━')}
 
 ${runtimeLine}
-${quickTunnel
-  ? `Quick Tunnel enabled:
-  ${green(quickTunnel.url)}
-Invites will use: ${green(inviteHost)}
-`
-  : 'Quick Tunnel not enabled (using configured/direct invite host).'}
 ${standaloneBootstrap
   ? `Standalone bridge templates:
   ${green(standaloneBootstrap.turnScript)}
@@ -740,12 +953,11 @@ Usage:
   npx a2acalling server               Start A2A server
 
 Install Options:
-  --hostname <host>          Hostname for invite URLs (skip quick tunnel when set)
+  --hostname <host>          Public hostname for invite URLs (e.g. myserver.com, myserver.com:80)
   --port <port>              A2A server port (default: 3001)
   --gateway-url <url>        Force gateway base URL for printed dashboard link
   --dashboard-backend <url>  Backend URL used by gateway dashboard proxy
   --standalone               Force standalone bootstrap (ignore OpenClaw detection)
-  --no-quick-tunnel          Disable auto quick tunnel for no-DNS environments
 
 Examples:
   npx a2acalling install --hostname myserver.com --port 3001

package/src/lib/client.js

@@ -5,6 +5,51 @@
 const https = require('https');
 const http = require('http');
 
+function splitHostPort(rawHost) {
+  const host = String(rawHost || '').trim();
+  if (!host) return { hostname: '', port: null };
+
+  // IPv6 in brackets: [::1]:3001
+  const bracketed = host.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (bracketed) {
+    return {
+      hostname: bracketed[1],
+      port: bracketed[2] ? Number.parseInt(bracketed[2], 10) : null
+    };
+  }
+
+  // Only treat the last ":" as a port separator when there's exactly one colon.
+  const lastColon = host.lastIndexOf(':');
+  if (lastColon !== -1 && host.indexOf(':') === lastColon) {
+    const maybePort = host.slice(lastColon + 1);
+    if (/^\d+$/.test(maybePort)) {
+      return {
+        hostname: host.slice(0, lastColon),
+        port: Number.parseInt(maybePort, 10)
+      };
+    }
+  }
+
+  return { hostname: host, port: null };
+}
+
+function resolveProtocolAndPort(host) {
+  const parsed = splitHostPort(host);
+  const hostname = parsed.hostname;
+  const hasExplicitPort = Number.isFinite(parsed.port);
+  const isLocalhost = hostname === 'localhost' ||
+    hostname === '127.0.0.1' ||
+    hostname === '::1' ||
+    hostname.startsWith('127.');
+
+  const port = hasExplicitPort ? parsed.port : (isLocalhost ? 80 : 443);
+  // Use HTTP for localhost or explicit non-443 ports, HTTPS otherwise.
+  const useHttp = isLocalhost || (hasExplicitPort && port !== 443);
+  const protocol = useHttp ? http : https;
+
+  return { protocol, hostname, port };
+}
+
 class A2AClient {
   constructor(options = {}) {
     this.timeout = options.timeout || 60000;
@@ -50,13 +95,7 @@ class A2AClient {
       timeout_seconds: timeoutSeconds || 60
     });
 
-    const isLocalhost = host === 'localhost' || host.startsWith('localhost:') || host.startsWith('127.');
-    const hasExplicitPort = host.includes(':');
-    const port = hasExplicitPort ? parseInt(host.split(':')[1]) : (isLocalhost ? 80 : 443);
-    // Use HTTP for localhost or explicit non-443 ports, HTTPS otherwise
-    const useHttp = isLocalhost || (hasExplicitPort && port !== 443);
-    const protocol = useHttp ? http : https;
-    const hostname = host.split(':')[0];
+    const { protocol, hostname, port } = resolveProtocolAndPort(host);
 
     return new Promise((resolve, reject) => {
       const req = protocol.request({
@@ -125,12 +164,7 @@ class A2AClient {
       conversation_id: conversationId
     });
 
-    const isLocalhost = host === 'localhost' || host.startsWith('localhost:') || host.startsWith('127.');
-    const hasExplicitPort = host.includes(':');
-    const port = hasExplicitPort ? parseInt(host.split(':')[1]) : (isLocalhost ? 80 : 443);
-    const useHttp = isLocalhost || (hasExplicitPort && port !== 443);
-    const protocol = useHttp ? http : https;
-    const hostname = host.split(':')[0];
+    const { protocol, hostname, port } = resolveProtocolAndPort(host);
 
     return new Promise((resolve, reject) => {
       const req = protocol.request({
@@ -187,12 +221,7 @@ class A2AClient {
       ({ host } = endpoint);
     }
 
-    const isLocalhost = host === 'localhost' || host.startsWith('localhost:') || host.startsWith('127.');
-    const hasExplicitPort = host.includes(':');
-    const port = hasExplicitPort ? parseInt(host.split(':')[1]) : (isLocalhost ? 80 : 443);
-    const useHttp = isLocalhost || (hasExplicitPort && port !== 443);
-    const protocol = useHttp ? http : https;
-    const hostname = host.split(':')[0];
+    const { protocol, hostname, port } = resolveProtocolAndPort(host);
 
     return new Promise((resolve, reject) => {
       const req = protocol.request({
@@ -234,12 +263,7 @@ class A2AClient {
       ({ host } = endpoint);
     }
 
-    const isLocalhost = host === 'localhost' || host.startsWith('localhost:') || host.startsWith('127.');
-    const hasExplicitPort = host.includes(':');
-    const port = hasExplicitPort ? parseInt(host.split(':')[1]) : (isLocalhost ? 80 : 443);
-    const useHttp = isLocalhost || (hasExplicitPort && port !== 443);
-    const protocol = useHttp ? http : https;
-    const hostname = host.split(':')[0];
+    const { protocol, hostname, port } = resolveProtocolAndPort(host);
 
     return new Promise((resolve, reject) => {
       const req = protocol.request({

package/src/lib/invite-host.js

@@ -124,10 +124,10 @@ function isPublicIpHostname(hostname) {
   return false;
 }
 
-function isEphemeralTunnelHostname(hostname) {
+function isLegacyTunnelHostname(hostname) {
   const host = String(hostname || '').trim().toLowerCase();
   if (!host) return false;
-  // Quick tunnels (cloudflared) are not stable across restarts.
+  // Legacy: Cloudflare Quick Tunnel hostnames were ephemeral and are now unsupported.
   if (host.endsWith('.trycloudflare.com')) return true;
   return false;
 }
@@ -155,7 +155,8 @@ async function resolveInviteHost(options = {}) {
     : 'default';
 
   const parsed = splitHostPort(candidate);
-  const desiredPort = parsed.port ||
+  const candidateIsLegacyTunnel = candidateSource !== 'env' && isLegacyTunnelHostname(parsed.hostname);
+  const desiredPort = (candidateIsLegacyTunnel ? null : parsed.port) ||
     Number.parseInt(String(options.defaultPort || ''), 10) ||
     readIntEnv('PORT') ||
     readIntEnv('A2A_PORT') ||
@@ -169,18 +170,17 @@ async function resolveInviteHost(options = {}) {
     ? options.externalIpTtlMs
     : undefined;
 
-  const preferQuickTunnel = Boolean(options.preferQuickTunnel) ||
-    String(process.env.A2A_PREFER_QUICK_TUNNEL || '').toLowerCase() === 'true';
-  const quickTunnelDisabled = Boolean(options.disableQuickTunnel) ||
-    String(process.env.A2A_DISABLE_QUICK_TUNNEL || '').toLowerCase() === 'true';
-
-  // If a previous run persisted an ephemeral tunnel hostname into config (e.g. trycloudflare),
-  // treat it like "unroutable" so we always refresh via tunnel/external IP instead of returning
-  // a stale endpoint.
-  const candidateIsEphemeralTunnel = candidateSource !== 'env' && isEphemeralTunnelHostname(parsed.hostname);
+  // If a previous run persisted a legacy Cloudflare Quick Tunnel hostname into config (e.g. trycloudflare),
+  // treat it like "unroutable" so we don't emit stale/unsupported invite endpoints.
+  if (candidateIsLegacyTunnel) {
+    warnings.push(
+      `Detected legacy Quick Tunnel hostname "${candidateHostWithPort}". Quick Tunnel support was removed. ` +
+      `Set A2A_HOSTNAME="your-public-host:port" (or wire a reverse proxy) to enable internet-facing invites.`
+    );
+  }
 
   const shouldReplaceWithExternalIp = isLocalOrUnroutableHost(parsed.hostname) ||
-    candidateIsEphemeralTunnel || (
+    candidateIsLegacyTunnel || (
       options.refreshExternalIp && isPublicIpHostname(parsed.hostname)
     );
 
@@ -193,28 +193,6 @@ async function resolveInviteHost(options = {}) {
     };
   }
 
-  if (preferQuickTunnel && !quickTunnelDisabled) {
-    try {
-      const { ensureQuickTunnel } = require('./quick-tunnel');
-      const tunnel = await ensureQuickTunnel({
-        localPort: desiredPort
-      });
-      if (tunnel && tunnel.host) {
-        const tunnelParsed = splitHostPort(tunnel.host);
-        const finalHost = formatHostPort(tunnelParsed.hostname, tunnelParsed.port || 443);
-        warnings.push(`Using secure Quick Tunnel endpoint "${finalHost}" for internet-facing invites.`);
-        return {
-          host: finalHost,
-          source: 'quick_tunnel',
-          originalHost: candidateHostWithPort,
-          warnings
-        };
-      }
-    } catch (err) {
-      warnings.push(`Quick Tunnel unavailable (${err.message}). Falling back to external IP host detection.`);
-    }
-  }
-
   const external = await getExternalIp({
     ttlMs,
     timeoutMs: options.externalIpTimeoutMs,

package/src/lib/port-scanner.js

@@ -8,20 +8,32 @@
 const net = require('net');
 
 /**
- * Check if a port is available on the given host.
+ * Attempt to bind a port and return a structured result.
+ * Useful for distinguishing "already in use" from "permission denied".
+ *
  * @param {number} port
  * @param {string} [host='0.0.0.0']
- * @returns {Promise<boolean>}
+ * @returns {Promise<{ ok: boolean, code?: string, message?: string }>}
  */
-function isPortAvailable(port, host = '0.0.0.0') {
+function tryBindPort(port, host = '0.0.0.0') {
   return new Promise((resolve) => {
     const server = net.createServer();
-    server.once('error', () => resolve(false));
-    server.once('listening', () => server.close(() => resolve(true)));
+    server.once('error', (err) => resolve({ ok: false, code: err && err.code ? String(err.code) : 'ERROR', message: err ? String(err.message || '') : '' }));
+    server.once('listening', () => server.close(() => resolve({ ok: true })));
     server.listen(port, host);
   });
 }
 
+/**
+ * Check if a port is available on the given host for binding by the current user.
+ * @param {number} port
+ * @param {string} [host='0.0.0.0']
+ * @returns {Promise<boolean>}
+ */
+function isPortAvailable(port, host = '0.0.0.0') {
+  return tryBindPort(port, host).then((res) => Boolean(res && res.ok));
+}
+
 /**
  * Find the first available port from a list of candidates.
  * @param {number[]} candidates - Ports to try in order
@@ -35,4 +47,37 @@ async function findAvailablePort(candidates, host = '0.0.0.0') {
   return null;
 }
 
-module.exports = { isPortAvailable, findAvailablePort };
+/**
+ * Check whether a TCP listener exists on the given host/port.
+ * This does NOT require binding privileges; it simply attempts to connect.
+ *
+ * @param {number} port
+ * @param {string} [host='127.0.0.1']
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs=400]
+ * @returns {Promise<{ listening: boolean, code?: string, message?: string }>}
+ */
+function isPortListening(port, host = '127.0.0.1', options = {}) {
+  const timeoutMs = Number.parseInt(String(options.timeoutMs || 400), 10) || 400;
+
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      try { socket.destroy(); } catch (e) {}
+      resolve(result);
+    };
+
+    socket.setTimeout(timeoutMs, () => finish({ listening: false, code: 'ETIMEDOUT', message: 'connect_timeout' }));
+    socket.once('connect', () => finish({ listening: true }));
+    socket.once('error', (err) => {
+      const code = err && err.code ? String(err.code) : 'ERROR';
+      finish({ listening: false, code, message: err ? String(err.message || '') : '' });
+    });
+  });
+}
+
+module.exports = { tryBindPort, isPortAvailable, isPortListening, findAvailablePort };

package/src/lib/quick-tunnel.js

@@ -1,332 +0,0 @@
-/**
- * Quick Tunnel Support (Cloudflare)
- *
- * Default behavior for no-DNS environments:
- * - lazily download cloudflared on first use (smallest viable binary path)
- * - start a quick tunnel to local A2A server
- * - persist tunnel metadata so invite generation can reuse it
- *
- * Intentionally minimal:
- * - no account-required managed tunnel flow yet
- * - no domain routing automation yet
- *
- * If owners need fixed hostnames or custom ingress, they can wire their own
- * proxy/tunnel and set A2A_HOSTNAME to that endpoint.
- */
-
-const fs = require('fs');
-const path = require('path');
-const http = require('http');
-const https = require('https');
-const { spawn } = require('child_process');
-
-const CONFIG_DIR = process.env.A2A_CONFIG_DIR ||
-  process.env.OPENCLAW_CONFIG_DIR ||
-  path.join(process.env.HOME || '/tmp', '.config', 'openclaw');
-
-const BIN_DIR = path.join(CONFIG_DIR, 'bin');
-const CLOUDFLARED_BIN = path.join(BIN_DIR, process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
-const TUNNEL_STATE_FILE = path.join(CONFIG_DIR, 'a2a-quick-tunnel.json');
-
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
-
-function isExecutable(filePath) {
-  try {
-    fs.accessSync(filePath, fs.constants.X_OK);
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-function commandExists(name) {
-  const paths = String(process.env.PATH || '').split(path.delimiter);
-  for (const p of paths) {
-    const full = path.join(p, name);
-    if (fs.existsSync(full) && isExecutable(full)) return full;
-    if (process.platform === 'win32') {
-      const exe = `${full}.exe`;
-      if (fs.existsSync(exe)) return exe;
-    }
-  }
-  return null;
-}
-
-function readJson(filePath) {
-  try {
-    if (!fs.existsSync(filePath)) return null;
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (err) {
-    return null;
-  }
-}
-
-function writeJson(filePath, value) {
-  ensureDir(path.dirname(filePath));
-  const tmp = `${filePath}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(value, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, filePath);
-  try {
-    fs.chmodSync(filePath, 0o600);
-  } catch (err) {
-    // Best effort.
-  }
-}
-
-function isProcessAlive(pid) {
-  if (!pid || !Number.isFinite(pid)) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-function resolveCloudflaredAssetName() {
-  const arch = process.arch;
-  const platform = process.platform;
-
-  if (platform === 'linux') {
-    if (arch === 'x64') return 'cloudflared-linux-amd64';
-    if (arch === 'arm64') return 'cloudflared-linux-arm64';
-  }
-  if (platform === 'darwin') {
-    if (arch === 'x64') return 'cloudflared-darwin-amd64.tgz';
-    if (arch === 'arm64') return 'cloudflared-darwin-arm64.tgz';
-  }
-  if (platform === 'win32' && arch === 'x64') {
-    return 'cloudflared-windows-amd64.exe';
-  }
-
-  throw new Error(`cloudflared_unsupported_platform:${platform}-${arch}`);
-}
-
-function downloadFile(url, destination, redirectsLeft = 5) {
-  return new Promise((resolve, reject) => {
-    let parsed;
-    try {
-      parsed = new URL(url);
-    } catch (err) {
-      reject(new Error('invalid_download_url'));
-      return;
-    }
-
-    const client = parsed.protocol === 'https:' ? https : http;
-    const req = client.get({
-      protocol: parsed.protocol,
-      hostname: parsed.hostname,
-      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-      path: parsed.pathname + parsed.search,
-      headers: {
-        'User-Agent': 'a2acalling/quick-tunnel'
-      }
-    }, (res) => {
-      const status = res.statusCode || 0;
-      if (status >= 300 && status < 400 && res.headers.location && redirectsLeft > 0) {
-        res.resume();
-        downloadFile(res.headers.location, destination, redirectsLeft - 1).then(resolve).catch(reject);
-        return;
-      }
-      if (status < 200 || status >= 300) {
-        res.resume();
-        reject(new Error(`download_failed_status_${status}`));
-        return;
-      }
-
-      const tmp = `${destination}.download`;
-      const out = fs.createWriteStream(tmp, { mode: 0o755 });
-      res.pipe(out);
-      out.on('finish', () => {
-        out.close(() => {
-          fs.renameSync(tmp, destination);
-          resolve(destination);
-        });
-      });
-      out.on('error', (err) => {
-        reject(err);
-      });
-    });
-
-    req.on('error', reject);
-  });
-}
-
-function extractTarGz(archivePath, outputDir) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('tar', ['-xzf', archivePath, '-C', outputDir], {
-      stdio: ['ignore', 'pipe', 'pipe']
-    });
-    let stderr = '';
-    child.stderr.on('data', chunk => { stderr += chunk.toString('utf8'); });
-    child.on('error', reject);
-    child.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`tar_extract_failed:${stderr || code}`));
-    });
-  });
-}
-
-async function ensureCloudflaredBinary() {
-  if (process.env.A2A_CLOUDFLARED_BIN && isExecutable(process.env.A2A_CLOUDFLARED_BIN)) {
-    return { path: process.env.A2A_CLOUDFLARED_BIN, source: 'env' };
-  }
-
-  const systemPath = commandExists(process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
-  if (systemPath) {
-    return { path: systemPath, source: 'system' };
-  }
-
-  if (fs.existsSync(CLOUDFLARED_BIN) && isExecutable(CLOUDFLARED_BIN)) {
-    return { path: CLOUDFLARED_BIN, source: 'cached' };
-  }
-
-  ensureDir(BIN_DIR);
-  const asset = resolveCloudflaredAssetName();
-  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset}`;
-  const downloadedPath = path.join(BIN_DIR, asset);
-
-  await downloadFile(url, downloadedPath);
-
-  if (asset.endsWith('.tgz')) {
-    await extractTarGz(downloadedPath, BIN_DIR);
-    try {
-      fs.unlinkSync(downloadedPath);
-    } catch (err) {
-      // Best effort.
-    }
-  } else if (downloadedPath !== CLOUDFLARED_BIN) {
-    fs.renameSync(downloadedPath, CLOUDFLARED_BIN);
-  }
-
-  if (!fs.existsSync(CLOUDFLARED_BIN)) {
-    throw new Error('cloudflared_install_failed');
-  }
-  try {
-    fs.chmodSync(CLOUDFLARED_BIN, 0o755);
-  } catch (err) {
-    // Best effort.
-  }
-
-  return { path: CLOUDFLARED_BIN, source: 'downloaded' };
-}
-
-function parseTryCloudflareUrl(line) {
-  const match = String(line || '').match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
-  return match ? match[0] : null;
-}
-
-function readQuickTunnelState() {
-  return readJson(TUNNEL_STATE_FILE);
-}
-
-function normalizeHostFromUrl(urlText) {
-  try {
-    const parsed = new URL(urlText);
-    return parsed.host;
-  } catch (err) {
-    return '';
-  }
-}
-
-async function startQuickTunnel(options = {}) {
-  const localPort = Number.parseInt(String(options.localPort || 3001), 10) || 3001;
-  const targetUrl = options.targetUrl || `http://127.0.0.1:${localPort}`;
-  const timeoutMs = Number.parseInt(String(options.timeoutMs || 25000), 10) || 25000;
-  const binary = options.binaryPath || (await ensureCloudflaredBinary()).path;
-
-  const args = [
-    'tunnel',
-    '--url',
-    targetUrl,
-    '--no-autoupdate',
-    '--protocol',
-    'http2'
-  ];
-
-  const child = spawn(binary, args, {
-    detached: true,
-    stdio: ['ignore', 'pipe', 'pipe']
-  });
-
-  return new Promise((resolve, reject) => {
-    let finished = false;
-    const timer = setTimeout(() => {
-      if (finished) return;
-      finished = true;
-      try { process.kill(child.pid); } catch (err) {}
-      reject(new Error('quick_tunnel_timeout'));
-    }, timeoutMs);
-
-    function handleLine(line) {
-      const url = parseTryCloudflareUrl(line);
-      if (!url || finished) return;
-      finished = true;
-      clearTimeout(timer);
-
-      const host = normalizeHostFromUrl(url);
-      const state = {
-        pid: child.pid,
-        url,
-        host,
-        local_port: localPort,
-        target_url: targetUrl,
-        started_at: new Date().toISOString(),
-        binary
-      };
-      writeJson(TUNNEL_STATE_FILE, state);
-
-      // Keep tunnel alive independently from caller process.
-      child.unref();
-      resolve({
-        url,
-        host,
-        pid: child.pid,
-        localPort,
-        source: 'started'
-      });
-    }
-
-    child.stdout.on('data', (chunk) => handleLine(chunk.toString('utf8')));
-    child.stderr.on('data', (chunk) => handleLine(chunk.toString('utf8')));
-    child.on('error', (err) => {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timer);
-      reject(err);
-    });
-    child.on('exit', (code) => {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timer);
-      reject(new Error(`quick_tunnel_exit_${code}`));
-    });
-  });
-}
-
-async function ensureQuickTunnel(options = {}) {
-  const localPort = Number.parseInt(String(options.localPort || 3001), 10) || 3001;
-  const state = readQuickTunnelState();
-  if (state && state.url && state.host && state.local_port === localPort && isProcessAlive(state.pid)) {
-    return {
-      url: state.url,
-      host: state.host,
-      pid: state.pid,
-      localPort,
-      source: 'state'
-    };
-  }
-
-  return startQuickTunnel({ ...options, localPort });
-}
-
-module.exports = {
-  TUNNEL_STATE_FILE,
-  ensureCloudflaredBinary,
-  ensureQuickTunnel,
-  readQuickTunnelState
-};