a2acalling 0.4.0 → 0.5.0

package/README.md

@@ -32,7 +32,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://your-host.com:3001/fed_abc123xyz
+# a2a://random-name.trycloudflare.com:443/fed_abc123xyz
 ```
 
 ### Call someone else's agent
@@ -75,6 +75,7 @@ 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 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 prints the exact dashboard URL at the end.
 
 Before the first `a2a call`, the owner must set permissions and disclosure tiers. Run onboarding first:
@@ -199,7 +200,7 @@ Dashboard paths:
 Tokens use the `a2a://` URI scheme:
 
 ```
-a2a://<hostname>:<port>/<token>
+a2a://<hostname>[:port]/<token>
 ```
 
 ### API Endpoints
@@ -325,6 +326,7 @@ app.listen(3001);
 |----------|-------------|
 | `A2A_HOSTNAME` | Hostname for invite URLs (required for creates) |
 | `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

@@ -51,6 +51,12 @@ cat ~/.config/openclaw/a2a-config.json 2>/dev/null | grep '"onboardingComplete"'
 
 Extract: professional context, interests, goals, skills, sensitive areas. Group them into Public/Friends/Family tiers based on sensitivity.
 
+## 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.
+
 ## Commands
 
 ### Quickstart

package/bin/cli.js

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

package/package.json

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

package/scripts/install-openclaw.js

@@ -7,6 +7,8 @@
  *   so dashboard is accessible at /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).
  *
  * Usage:
  *   npx a2acalling install
@@ -140,7 +142,7 @@ function writeExecutableFile(filePath, content) {
  * Ensure config and disclosure manifest exist.
  * Called from both OpenClaw and standalone install paths.
  */
-function ensureConfigAndManifest(hostname, port) {
+function ensureConfigAndManifest(inviteHost, port, options = {}) {
   const configDir = resolveA2AConfigDir();
   ensureDir(configDir);
 
@@ -153,8 +155,9 @@ function ensureConfigAndManifest(hostname, port) {
     config.setDefaults(defaults);
 
     const agent = config.getAgent() || {};
-    if (!agent.hostname) {
-      config.setAgent({ hostname: `${hostname}:${port}` });
+    const desiredHost = String(inviteHost || '').trim();
+    if ((desiredHost && !agent.hostname) || (desiredHost && options.forceHostname)) {
+      config.setAgent({ hostname: desiredHost });
     }
 
     const manifest = loadManifest();
@@ -172,8 +175,8 @@ function ensureConfigAndManifest(hostname, port) {
   return configDir;
 }
 
-function ensureStandaloneBootstrap(hostname, port) {
-  const configDir = ensureConfigAndManifest(hostname, port);
+function ensureStandaloneBootstrap(inviteHost, port, options = {}) {
+  const configDir = ensureConfigAndManifest(inviteHost, port, options);
 
   const configFile = path.join(configDir, 'a2a-config.json');
   const manifestFile = path.join(configDir, 'a2a-disclosure.json');
@@ -417,10 +420,47 @@ function loadSkillMd() {
   return null;
 }
 
+function readExistingConfiguredInviteHost() {
+  try {
+    const { A2AConfig } = require('../src/lib/config');
+    const { splitHostPort, isLocalOrUnroutableHost } = require('../src/lib/invite-host');
+    const config = new A2AConfig();
+    const existing = String((config.getAgent() || {}).hostname || '').trim();
+    if (!existing) return '';
+    const parsed = splitHostPort(existing);
+    if (!parsed.hostname || isLocalOrUnroutableHost(parsed.hostname)) {
+      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;
+
+  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`
+    };
+  } catch (err) {
+    warn(`Quick Tunnel setup failed: ${err.message}`);
+    warn('Falling back to direct host invites (may require firewall/NAT config).');
+    return null;
+  }
+}
+
 async function install() {
   log('Installing A2A Calling...\n');
 
-  const hostname = flags.hostname || process.env.HOSTNAME || 'localhost';
+  const localHostname = process.env.HOSTNAME || 'localhost';
 
   // Port scanning: use explicit port or scan for available one
   let port;
@@ -443,6 +483,12 @@ async function install() {
     }
   }
   const backendUrl = flags['dashboard-backend'] || `http://127.0.0.1:${port}`;
+  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}`;
   const forceStandalone = Boolean(flags.standalone) || String(process.env.A2A_FORCE_STANDALONE || '').toLowerCase() === 'true';
   const hasOpenClawBinary = commandExists('openclaw');
   const hasOpenClawConfig = fs.existsSync(OPENCLAW_CONFIG);
@@ -465,10 +511,14 @@ async function install() {
     log(`Installed skill to: ${skillDir}`);
 
     // Ensure config and manifest exist even in OpenClaw path
-    ensureConfigAndManifest(hostname, port);
+    ensureConfigAndManifest(inviteHost, port, {
+      forceHostname: Boolean(flags.hostname || process.env.A2A_HOSTNAME || process.env.OPENCLAW_HOSTNAME || quickTunnel)
+    });
   } else {
     warn('OpenClaw not detected. Enabling standalone A2A bootstrap.');
-    standaloneBootstrap = ensureStandaloneBootstrap(hostname, port);
+    standaloneBootstrap = ensureStandaloneBootstrap(inviteHost, port, {
+      forceHostname: Boolean(flags.hostname || process.env.A2A_HOSTNAME || process.env.OPENCLAW_HOSTNAME || quickTunnel)
+    });
   }
 
   // 3. Update OpenClaw config + gateway plugin setup (if available)
@@ -476,7 +526,7 @@ async function install() {
   let configUpdated = false;
   let gatewayDetected = false;
   let dashboardMode = 'standalone';
-  let dashboardUrl = `http://${hostname}:${port}/dashboard`;
+  let dashboardUrl = `http://${localHostname}:${port}/dashboard`;
 
   if (config) {
     // Add custom command for each enabled channel
@@ -539,7 +589,7 @@ ${bold('━━━ Server Setup ━━━')}
 
 To receive incoming calls and host A2A APIs:
 
-  ${green(`A2A_HOSTNAME="${hostname}:${port}" a2a server --port ${port}`)}
+  ${green(`A2A_HOSTNAME="${inviteHost}" a2a server --port ${port}`)}
 
 ${bold('━━━ Dashboard Setup ━━━')}
 
@@ -553,6 +603,12 @@ ${dashboardMode === 'gateway'
 ${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)}
@@ -618,11 +674,12 @@ Usage:
   npx a2acalling server               Start A2A server
 
 Install Options:
-  --hostname <host>          Hostname for invite URLs (default: system hostname)
+  --hostname <host>          Hostname for invite URLs (skip quick tunnel when set)
   --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/invite-host.js

@@ -161,6 +161,11 @@ 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';
+
   const shouldReplaceWithExternalIp = isLocalOrUnroutableHost(parsed.hostname) || (
     options.refreshExternalIp && isPublicIpHostname(parsed.hostname)
   );
@@ -174,6 +179,32 @@ 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);
+        if (candidateSource !== 'env' && config && typeof config.setAgent === 'function') {
+          // Persist the secure public hostname for future invite generation.
+          config.setAgent({ hostname: finalHost });
+        }
+        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,
@@ -216,4 +247,3 @@ module.exports = {
   isLocalOrUnroutableHost,
   resolveInviteHost
 };
-

package/src/lib/quick-tunnel.js

@@ -0,0 +1,332 @@
+/**
+ * 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
+};

package/src/routes/dashboard.js

@@ -509,7 +509,8 @@ function createDashboardApiRouter(options = {}) {
 
     const resolvedHost = await resolveInviteHost({
       config: context.config,
-      defaultPort: process.env.PORT || process.env.A2A_PORT || 3001
+      defaultPort: process.env.PORT || process.env.A2A_PORT || 3001,
+      preferQuickTunnel: true
     });
     const host = resolvedHost.host;
     const inviteUrl = `a2a://${host}/${token}`;