a2acalling 0.3.4 → 0.3.6

package/README.md

@@ -58,10 +58,10 @@ npm install -g a2acalling
 npm install a2acalling
 ```
 
-### For OpenClaw Users
+### Setup (Auto-Detect Runtime)
 
 ```bash
-# Auto setup (detects gateway and configures dashboard location)
+# Auto setup (detects OpenClaw gateway/runtime or configures standalone mode)
 npx a2acalling setup
 
 # Or clone and install
@@ -72,8 +72,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 gateway is not detected, dashboard is served directly by A2A server at `/dashboard`.
+- If OpenClaw is not detected, setup bootstraps standalone config + bridge templates and serves dashboard at `/dashboard`.
 - 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:
@@ -325,6 +326,14 @@ app.listen(3001);
 | `A2A_HOSTNAME` | Hostname for invite URLs (required for creates) |
 | `A2A_PORT` | Server port (default: 3001) |
 | `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` |
+| `A2A_RUNTIME_FAILOVER` | Fallback to generic runtime if OpenClaw runtime errors (default: `true`) |
+| `A2A_AGENT_COMMAND` | Generic runtime command for inbound turn handling (reads JSON from stdin) |
+| `A2A_SUMMARY_COMMAND` | Generic runtime command for call summaries (reads JSON from stdin) |
+| `A2A_NOTIFY_COMMAND` | Generic runtime command for owner notifications (reads JSON from stdin) |
+| `A2A_AGENT_NAME` | Override local agent display name |
+| `A2A_OWNER_NAME` | Override owner display name |
 | `A2A_COLLAB_MODE` | Conversation style: `adaptive` (default) or `deep_dive` |
 | `A2A_ADMIN_TOKEN` | Protect dashboard/conversation admin routes for non-local access |
 

package/package.json

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

package/scripts/install-openclaw.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 /**
- * A2A Calling - OpenClaw Integration Installer
+ * A2A Calling Setup Installer
  *
  * Supports automatic setup:
  * - If OpenClaw gateway is detected, install a gateway HTTP proxy plugin
  *   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.
  *
  * Usage:
  *   npx a2acalling install
@@ -16,6 +17,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { execSync } = require('child_process');
 
 // Paths
@@ -111,6 +113,112 @@ function resolveGatewayBaseUrl() {
   return `http://127.0.0.1:${fallbackPort}`;
 }
 
+function resolveA2AConfigDir() {
+  return process.env.A2A_CONFIG_DIR ||
+    process.env.OPENCLAW_CONFIG_DIR ||
+    path.join(process.env.HOME || '/tmp', '.config', 'openclaw');
+}
+
+function safeRead(filePath) {
+  try {
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  } catch (err) {
+    return '';
+  }
+}
+
+function writeExecutableFile(filePath, content) {
+  fs.writeFileSync(filePath, content, { mode: 0o755 });
+  try {
+    fs.chmodSync(filePath, 0o755);
+  } catch (err) {
+    // Non-fatal on platforms without chmod support.
+  }
+}
+
+function ensureStandaloneBootstrap(hostname, port) {
+  const configDir = resolveA2AConfigDir();
+  ensureDir(configDir);
+
+  const configFile = path.join(configDir, 'a2a-config.json');
+  const manifestFile = path.join(configDir, 'a2a-disclosure.json');
+
+  try {
+    const { A2AConfig } = require('../src/lib/config');
+    const { loadManifest, saveManifest, generateDefaultManifest } = require('../src/lib/disclosure');
+
+    const config = new A2AConfig();
+    const defaults = config.getDefaults() || {};
+    config.setDefaults(defaults);
+
+    const agent = config.getAgent() || {};
+    if (!agent.hostname) {
+      config.setAgent({
+        hostname: `${hostname}:${port}`
+      });
+    }
+
+    const manifest = loadManifest();
+    if (!manifest || Object.keys(manifest).length === 0) {
+      const generated = generateDefaultManifest({
+        user: safeRead(path.join(process.cwd(), 'USER.md')),
+        heartbeat: safeRead(path.join(process.cwd(), 'HEARTBEAT.md')),
+        soul: safeRead(path.join(process.cwd(), 'SOUL.md'))
+      });
+      saveManifest(generated);
+      log(`Generated default disclosure manifest: ${manifestFile}`);
+    }
+  } catch (err) {
+    warn(`Standalone config bootstrap failed: ${err.message}`);
+  }
+
+  const bridgeDir = path.join(configDir, 'runtime-bridge');
+  ensureDir(bridgeDir);
+  const turnScript = path.join(bridgeDir, 'a2a-turn.sh');
+  const summaryScript = path.join(bridgeDir, 'a2a-summary.sh');
+  const notifyScript = path.join(bridgeDir, 'a2a-notify.sh');
+
+  if (!fs.existsSync(turnScript)) {
+    writeExecutableFile(turnScript, `#!/usr/bin/env bash
+set -euo pipefail
+payload="$(cat || true)"
+echo '{"response":"Generic bridge placeholder: your agent bridge is active. I received your message and can continue the call. What collaboration outcome should we target?"}'
+`);
+  }
+
+  if (!fs.existsSync(summaryScript)) {
+    writeExecutableFile(summaryScript, `#!/usr/bin/env bash
+set -euo pipefail
+payload="$(cat || true)"
+echo '{"summary":"Generic summary placeholder generated by standalone bridge.","ownerSummary":"Generic summary placeholder generated by standalone bridge."}'
+`);
+  }
+
+  if (!fs.existsSync(notifyScript)) {
+    writeExecutableFile(notifyScript, `#!/usr/bin/env bash
+set -euo pipefail
+payload="$(cat || true)"
+echo "a2a notify: $payload" >&2
+`);
+  }
+
+  let generatedAdminToken = null;
+  if (!process.env.A2A_ADMIN_TOKEN) {
+    generatedAdminToken = crypto.randomBytes(24).toString('base64url');
+  }
+
+  return {
+    configDir,
+    configFile,
+    manifestFile,
+    bridgeDir,
+    turnScript,
+    summaryScript,
+    notifyScript,
+    generatedAdminToken
+  };
+}
+
 const DASHBOARD_PLUGIN_MANIFEST = {
   id: DASHBOARD_PLUGIN_ID,
   name: 'A2A Dashboard Proxy',
@@ -378,20 +486,30 @@ a2a server --port 3001
 `;
 
 function install() {
-  log('Installing A2A Calling for OpenClaw...\n');
+  log('Installing A2A Calling...\n');
 
   const hostname = flags.hostname || process.env.HOSTNAME || 'localhost';
   const port = String(flags.port || process.env.A2A_PORT || '3001');
   const backendUrl = flags['dashboard-backend'] || `http://127.0.0.1:${port}`;
-
-  // 1. Create skills directory if needed
-  ensureDir(OPENCLAW_SKILLS);
-
-  // 2. Install skill
-  const skillDir = path.join(OPENCLAW_SKILLS, SKILL_NAME);
-  ensureDir(skillDir);
-  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), SKILL_MD);
-  log(`Installed skill to: ${skillDir}`);
+  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;
+
+  if (hasOpenClaw) {
+    // 1. Create skills directory if needed
+    ensureDir(OPENCLAW_SKILLS);
+
+    // 2. Install skill
+    const skillDir = path.join(OPENCLAW_SKILLS, SKILL_NAME);
+    ensureDir(skillDir);
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), SKILL_MD);
+    log(`Installed skill to: ${skillDir}`);
+  } else {
+    warn('OpenClaw not detected. Enabling standalone A2A bootstrap.');
+    standaloneBootstrap = ensureStandaloneBootstrap(hostname, port);
+  }
 
   // 3. Update OpenClaw config + gateway plugin setup (if available)
   let config = loadOpenClawConfig();
@@ -450,6 +568,12 @@ function install() {
     warn('Skipping OpenClaw command/plugin config updates');
   }
 
+  const runtimeLine = forceStandalone
+    ? 'Runtime forced to standalone mode for this setup run.'
+    : hasOpenClawBinary
+    ? 'Runtime auto-selects OpenClaw when available and falls back to generic if needed.'
+    : 'Runtime defaults to generic fallback (no OpenClaw dependency required).';
+
   console.log(`
 ${bold('━━━ Server Setup ━━━')}
 
@@ -466,6 +590,25 @@ ${dashboardMode === 'gateway'
   ? `Gateway path /a2a is now proxied to ${backendUrl}.`
   : 'No gateway detected. Dashboard is served directly from the A2A server.'}
 
+${bold('━━━ Runtime Setup ━━━')}
+
+${runtimeLine}
+${standaloneBootstrap
+  ? `Standalone bridge templates:
+  ${green(standaloneBootstrap.turnScript)}
+  ${green(standaloneBootstrap.summaryScript)}
+  ${green(standaloneBootstrap.notifyScript)}
+
+Optional bridge wiring:
+  export A2A_RUNTIME=generic
+  export A2A_AGENT_COMMAND="${standaloneBootstrap.turnScript}"
+  export A2A_SUMMARY_COMMAND="${standaloneBootstrap.summaryScript}"
+  export A2A_NOTIFY_COMMAND="${standaloneBootstrap.notifyScript}"
+${standaloneBootstrap.generatedAdminToken ? `
+Suggested dashboard admin token (set in env, do not commit):
+  export A2A_ADMIN_TOKEN="${standaloneBootstrap.generatedAdminToken}"` : ''}`
+  : 'No standalone bridge templates were created because OpenClaw was detected.'}
+
 ${bold('━━━ Usage ━━━')}
 
 In your chat app, use:
@@ -506,11 +649,11 @@ function uninstall() {
 
 function showHelp() {
   console.log(`
-${bold('A2A Calling - OpenClaw Integration')}
+${bold('A2A Calling Setup')}
 
 Usage:
-  npx a2acalling install [options]    Install A2A for OpenClaw
-  npx a2acalling setup [options]      Alias for install (auto gateway/standalone)
+  npx a2acalling install [options]    Install A2A (OpenClaw-aware + standalone)
+  npx a2acalling setup [options]      Alias for install (auto runtime detection)
   npx a2acalling uninstall            Remove A2A skill + dashboard plugin
   npx a2acalling server               Start A2A server
 
@@ -519,10 +662,12 @@ Install Options:
   --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)
 
 Examples:
   npx a2acalling install --hostname myserver.com --port 3001
   npx a2acalling setup --dashboard-backend http://127.0.0.1:3001
+  npx a2acalling setup --standalone
   npx a2acalling uninstall
 `);
 }

package/src/index.js

@@ -18,6 +18,7 @@ const { TokenStore } = require('./lib/tokens');
 const { A2AClient, A2AError } = require('./lib/client');
 const { createRoutes } = require('./routes/a2a');
 const { createDashboardApiRouter, createDashboardUiRouter } = require('./routes/dashboard');
+const { createRuntimeAdapter, resolveRuntimeMode } = require('./lib/runtime-adapter');
 
 // Lazy load optional dependencies
 let ConversationStore = null;
@@ -48,6 +49,10 @@ module.exports = {
   // Dashboard routes
   createDashboardApiRouter,
   createDashboardUiRouter,
+
+  // Runtime adapter
+  createRuntimeAdapter,
+  resolveRuntimeMode,
   
   // Conversation storage (requires better-sqlite3)
   ConversationStore,

package/src/lib/config.js

@@ -112,8 +112,13 @@ class A2AConfig {
       this.config.createdAt = this.config.updatedAt;
     }
     const tmpPath = `${CONFIG_FILE}.tmp`;
-    fs.writeFileSync(tmpPath, JSON.stringify(this.config, null, 2));
+    fs.writeFileSync(tmpPath, JSON.stringify(this.config, null, 2), { mode: 0o600 });
     fs.renameSync(tmpPath, CONFIG_FILE);
+    try {
+      fs.chmodSync(CONFIG_FILE, 0o600);
+    } catch (err) {
+      // Best effort - ignore on platforms without chmod support.
+    }
   }
 
   // Check if onboarding is complete

package/src/lib/conversations.js

@@ -39,6 +39,11 @@ class ConversationStore {
     try {
       const Database = require('better-sqlite3');
       this.db = new Database(this.dbPath);
+      try {
+        fs.chmodSync(this.dbPath, 0o600);
+      } catch (err) {
+        // Best effort - ignore on platforms without chmod support.
+      }
       this._migrate();
       return this.db;
     } catch (err) {

package/src/lib/disclosure.js

@@ -39,8 +39,13 @@ function saveManifest(manifest) {
   }
   manifest.updated_at = new Date().toISOString();
   const tmpPath = `${MANIFEST_FILE}.tmp`;
-  fs.writeFileSync(tmpPath, JSON.stringify(manifest, null, 2));
+  fs.writeFileSync(tmpPath, JSON.stringify(manifest, null, 2), { mode: 0o600 });
   fs.renameSync(tmpPath, MANIFEST_FILE);
+  try {
+    fs.chmodSync(MANIFEST_FILE, 0o600);
+  } catch (err) {
+    // Best effort - ignore on platforms without chmod support.
+  }
 }
 
 /**

package/src/lib/runtime-adapter.js

@@ -0,0 +1,460 @@
+/**
+ * Runtime adapter for inbound A2A calls.
+ *
+ * Modes:
+ * - openclaw: uses `openclaw` CLI for turn handling, summaries, notifications
+ * - generic: platform-agnostic fallback that never hard-fails calls
+ *
+ * Selection:
+ * - A2A_RUNTIME=openclaw|generic|auto (default: auto)
+ * - auto picks openclaw if CLI exists, otherwise generic
+ *
+ * Generic bridge hooks:
+ * - A2A_AGENT_COMMAND   command that receives JSON payload on stdin and returns text or JSON
+ * - A2A_SUMMARY_COMMAND command that receives JSON payload on stdin and returns summary text/JSON
+ * - A2A_NOTIFY_COMMAND  command that receives JSON payload on stdin for owner notifications
+ */
+
+const { execSync } = require('child_process');
+
+function commandExists(command) {
+  try {
+    execSync(`command -v ${command}`, { stdio: 'ignore' });
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function cleanText(value, maxLength = 300) {
+  return String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maxLength);
+}
+
+function toBool(value, fallback = true) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  return !(normalized === '0' || normalized === 'false' || normalized === 'no');
+}
+
+function resolveRuntimeMode() {
+  const requested = String(process.env.A2A_RUNTIME || 'auto').trim().toLowerCase();
+  const hasOpenClaw = commandExists('openclaw');
+
+  if (requested === 'generic') {
+    return {
+      mode: 'generic',
+      requested,
+      hasOpenClaw,
+      reason: 'A2A_RUNTIME=generic'
+    };
+  }
+
+  if (requested === 'openclaw') {
+    if (hasOpenClaw) {
+      return {
+        mode: 'openclaw',
+        requested,
+        hasOpenClaw,
+        reason: 'A2A_RUNTIME=openclaw'
+      };
+    }
+    return {
+      mode: 'generic',
+      requested,
+      hasOpenClaw,
+      warning: 'A2A_RUNTIME=openclaw but openclaw CLI not found, falling back to generic runtime',
+      reason: 'forced-openclaw-missing'
+    };
+  }
+
+  if (hasOpenClaw) {
+    return {
+      mode: 'openclaw',
+      requested: 'auto',
+      hasOpenClaw,
+      reason: 'openclaw CLI detected'
+    };
+  }
+
+  return {
+    mode: 'generic',
+    requested: 'auto',
+    hasOpenClaw,
+    reason: 'openclaw CLI not detected'
+  };
+}
+
+function normalizeOpenClawOutput(raw) {
+  const lines = String(raw || '')
+    .split('\n')
+    .filter(line => {
+      if (!line.trim()) return false;
+      if (line.includes('[telegram-topic-tracker]')) return false;
+      if (line.includes('Plugin registered')) return false;
+      return true;
+    });
+  return lines.join('\n').trim();
+}
+
+function parseCommandTextOutput(rawOutput, keys = ['response', 'text', 'message']) {
+  const output = String(rawOutput || '').trim();
+  if (!output) {
+    return '';
+  }
+
+  try {
+    const parsed = JSON.parse(output);
+    if (parsed && typeof parsed === 'object') {
+      for (const key of keys) {
+        if (typeof parsed[key] === 'string' && parsed[key].trim()) {
+          return parsed[key].trim();
+        }
+      }
+    }
+  } catch (err) {
+    // Plain text output is valid for bridge commands.
+  }
+
+  return output;
+}
+
+function parseSummaryOutput(rawOutput) {
+  const output = String(rawOutput || '').trim();
+  if (!output) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(output);
+    if (parsed && typeof parsed === 'object') {
+      const summary = cleanText(parsed.summary || parsed.text || parsed.message, 1500);
+      return {
+        ...parsed,
+        summary: summary || null,
+        ownerSummary: cleanText(
+          parsed.ownerSummary || parsed.owner_summary || summary || '',
+          1500
+        ) || null
+      };
+    }
+  } catch (err) {
+    // Plain text is also acceptable.
+  }
+
+  const summary = cleanText(output, 1500);
+  return {
+    summary,
+    ownerSummary: summary
+  };
+}
+
+function runCommand(command, payload, options = {}) {
+  const payloadJson = JSON.stringify(payload || {});
+  const timeoutMs = options.timeoutMs || 60000;
+  return execSync(command, {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    input: payloadJson,
+    cwd: options.cwd || process.cwd(),
+    env: {
+      ...process.env,
+      A2A_PAYLOAD_JSON: payloadJson
+    }
+  });
+}
+
+function escapeCliValue(value) {
+  return String(value || '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '');
+}
+
+function buildFallbackResponse(message, context = {}, reason = null) {
+  const callerName = cleanText(context.callerName || context.caller?.name || 'caller');
+  const ownerName = cleanText(context.ownerName || 'the owner');
+  const allowedTopics = Array.isArray(context.allowedTopics)
+    ? context.allowedTopics.filter(Boolean).slice(0, 4)
+    : [];
+  const topicText = allowedTopics.length > 0
+    ? allowedTopics.join(', ')
+    : 'permitted topics';
+  const excerpt = cleanText(message, 220) || 'No message content provided.';
+
+  let prefix = `I am running in generic A2A mode for ${ownerName}.`;
+  if (reason) {
+    prefix = `I switched to generic fallback mode (${cleanText(reason, 120)}).`;
+  }
+
+  return `${prefix} I received from ${callerName}: "${excerpt}". ` +
+    `We can still work through concrete overlap on ${topicText} and line up actionable next steps. ` +
+    `What outcome should we target first?`;
+}
+
+function buildFallbackSummary(messages = [], callerInfo = {}, reason = null) {
+  const inbound = messages.filter(m => m.direction === 'inbound');
+  const outbound = messages.filter(m => m.direction !== 'inbound');
+  const caller = cleanText(callerInfo?.name || 'Unknown caller');
+  const lastInbound = inbound.length > 0
+    ? cleanText(inbound[inbound.length - 1].content, 220)
+    : '';
+
+  const summary = [
+    `Call concluded with ${caller}.`,
+    `Inbound turns: ${inbound.length}. Outbound turns: ${outbound.length}.`,
+    lastInbound ? `Latest caller request: "${lastInbound}".` : '',
+    reason ? `Summary mode: ${cleanText(reason, 140)}.` : 'Summary mode: generic fallback.'
+  ].filter(Boolean).join(' ');
+
+  return {
+    summary,
+    ownerSummary: summary,
+    relevance: 'unknown',
+    goalsTouched: [],
+    ownerActionItems: [],
+    callerActionItems: [],
+    jointActionItems: [],
+    collaborationOpportunity: {
+      found: false,
+      rationale: 'Generic fallback summary (no platform-specific summarizer configured)'
+    },
+    followUp: lastInbound
+      ? `Clarify the next concrete step for: ${lastInbound}`
+      : 'Ask both owners to confirm desired follow-up scope.',
+    notes: reason
+      ? `Fallback summary generated after runtime issue: ${cleanText(reason, 180)}`
+      : 'Fallback summary generated by generic runtime.'
+  };
+}
+
+function createRuntimeAdapter(options = {}) {
+  const workspaceDir = options.workspaceDir || process.cwd();
+  const modeInfo = resolveRuntimeMode();
+  const failoverEnabled = toBool(process.env.A2A_RUNTIME_FAILOVER, true);
+
+  const genericAgentCommand = process.env.A2A_AGENT_COMMAND || '';
+  const genericSummaryCommand = process.env.A2A_SUMMARY_COMMAND || '';
+  const genericNotifyCommand = process.env.A2A_NOTIFY_COMMAND || '';
+
+  async function runOpenClawTurn({ sessionId, prompt, timeoutMs }) {
+    const timeoutSeconds = Math.max(5, Math.min(300, Math.round((timeoutMs || 65000) / 1000)));
+    const escapedPrompt = escapeCliValue(prompt);
+    const output = execSync(
+      `openclaw agent --session-id "${sessionId}" --message "${escapedPrompt}" --timeout ${timeoutSeconds} 2>&1`,
+      {
+        encoding: 'utf8',
+        timeout: (timeoutMs || 65000) + 5000,
+        maxBuffer: 1024 * 1024,
+        cwd: workspaceDir,
+        env: { ...process.env, FORCE_COLOR: '0' }
+      }
+    );
+    return normalizeOpenClawOutput(output) || '[Sub-agent returned empty response]';
+  }
+
+  async function runOpenClawSummary({ sessionId, prompt, timeoutMs }) {
+    const timeoutSeconds = Math.max(5, Math.min(120, Math.round((timeoutMs || 35000) / 1000)));
+    const escapedPrompt = escapeCliValue(prompt);
+    const output = execSync(
+      `openclaw agent --session-id "${sessionId}" --message "${escapedPrompt}" --timeout ${timeoutSeconds} 2>&1`,
+      {
+        encoding: 'utf8',
+        timeout: (timeoutMs || 35000) + 5000,
+        cwd: workspaceDir,
+        env: { ...process.env, FORCE_COLOR: '0' }
+      }
+    );
+    const summaryText = cleanText(normalizeOpenClawOutput(output), 1500);
+    if (!summaryText) {
+      return null;
+    }
+    return {
+      summary: summaryText,
+      ownerSummary: summaryText
+    };
+  }
+
+  async function runOpenClawNotify({ callerName, callerOwner, message }) {
+    const notification = `🤝 **A2A Call**\nFrom: ${callerName}${callerOwner}\n> ${message.slice(0, 150)}...`;
+    execSync(
+      `openclaw message send --channel telegram --message "${escapeCliValue(notification)}"`,
+      { timeout: 10000, stdio: 'pipe' }
+    );
+  }
+
+  async function runGenericTurn({ message, caller, context, runtimeError }) {
+    const payload = {
+      mode: 'a2a-turn',
+      message,
+      caller: caller || {},
+      context: context || {}
+    };
+
+    if (genericAgentCommand) {
+      try {
+        const output = runCommand(genericAgentCommand, payload, {
+          timeoutMs: context?.timeoutMs || 65000
+        });
+        const text = parseCommandTextOutput(output);
+        if (text) {
+          return text;
+        }
+      } catch (err) {
+        runtimeError = err.message;
+        console.error(`[a2a] Generic agent command failed: ${err.message}`);
+      }
+    }
+
+    return buildFallbackResponse(message, {
+      caller,
+      callerName: caller?.name,
+      ownerName: context?.ownerName,
+      allowedTopics: context?.allowedTopics
+    }, runtimeError);
+  }
+
+  async function runGenericSummary({ messages, callerInfo, reason }) {
+    const payload = {
+      mode: 'a2a-summary',
+      messages,
+      caller: callerInfo || {}
+    };
+
+    if (genericSummaryCommand) {
+      try {
+        const output = runCommand(genericSummaryCommand, payload, { timeoutMs: 35000 });
+        const parsed = parseSummaryOutput(output);
+        if (parsed && parsed.summary) {
+          return parsed;
+        }
+      } catch (err) {
+        reason = err.message;
+        console.error(`[a2a] Generic summary command failed: ${err.message}`);
+      }
+    }
+
+    return buildFallbackSummary(messages, callerInfo, reason);
+  }
+
+  async function runGenericNotify(payload) {
+    if (!genericNotifyCommand) {
+      return;
+    }
+    try {
+      runCommand(genericNotifyCommand, payload, { timeoutMs: 10000 });
+    } catch (err) {
+      console.error(`[a2a] Generic notify command failed: ${err.message}`);
+    }
+  }
+
+  async function runTurn({ sessionId, prompt, message, caller, context = {}, timeoutMs }) {
+    if (modeInfo.mode !== 'openclaw') {
+      return runGenericTurn({ message, caller, context });
+    }
+
+    try {
+      return await runOpenClawTurn({ sessionId, prompt, timeoutMs });
+    } catch (err) {
+      if (!failoverEnabled) {
+        throw err;
+      }
+      console.error(`[a2a] OpenClaw runtime failed, switching to generic fallback: ${err.message}`);
+      return runGenericTurn({
+        message,
+        caller,
+        context,
+        runtimeError: `openclaw runtime unavailable: ${err.message}`
+      });
+    }
+  }
+
+  async function summarize({ sessionId, prompt, messages, callerInfo }) {
+    if (modeInfo.mode !== 'openclaw') {
+      return runGenericSummary({ messages, callerInfo });
+    }
+
+    try {
+      const result = await runOpenClawSummary({
+        sessionId,
+        prompt,
+        timeoutMs: 35000
+      });
+      if (result && result.summary) {
+        return result;
+      }
+      return runGenericSummary({
+        messages,
+        callerInfo,
+        reason: 'empty summary from openclaw runtime'
+      });
+    } catch (err) {
+      if (!failoverEnabled) {
+        throw err;
+      }
+      console.error(`[a2a] OpenClaw summary failed, using generic fallback: ${err.message}`);
+      return runGenericSummary({
+        messages,
+        callerInfo,
+        reason: `openclaw summary unavailable: ${err.message}`
+      });
+    }
+  }
+
+  async function notify({ level, token, caller, message, conversationId }) {
+    const payload = {
+      mode: 'a2a-notify',
+      level,
+      token: token || null,
+      caller: caller || null,
+      message,
+      conversationId
+    };
+
+    if (modeInfo.mode !== 'openclaw') {
+      return runGenericNotify(payload);
+    }
+
+    if (level !== 'all') {
+      return;
+    }
+
+    const callerName = caller?.name || 'Unknown';
+    const callerOwner = caller?.owner ? ` (${caller.owner})` : '';
+
+    try {
+      await runOpenClawNotify({ callerName, callerOwner, message: message || '' });
+    } catch (err) {
+      if (!failoverEnabled) {
+        throw err;
+      }
+      console.error(`[a2a] OpenClaw notify failed, running generic notifier: ${err.message}`);
+      await runGenericNotify(payload);
+    }
+  }
+
+  return {
+    mode: modeInfo.mode,
+    requestedMode: modeInfo.requested,
+    hasOpenClaw: modeInfo.hasOpenClaw,
+    reason: modeInfo.reason,
+    warning: modeInfo.warning || null,
+    failoverEnabled,
+    runTurn,
+    summarize,
+    notify,
+    buildFallbackResponse
+  };
+}
+
+module.exports = {
+  createRuntimeAdapter,
+  resolveRuntimeMode,
+  buildFallbackResponse
+};

package/src/lib/tokens.js

@@ -44,8 +44,13 @@ class TokenStore {
   _save(db) {
     // Atomic write: write to temp file, then rename
     const tmpPath = `${this.dbPath}.tmp.${process.pid}`;
-    fs.writeFileSync(tmpPath, JSON.stringify(db, null, 2));
+    fs.writeFileSync(tmpPath, JSON.stringify(db, null, 2), { mode: 0o600 });
     fs.renameSync(tmpPath, this.dbPath);
+    try {
+      fs.chmodSync(this.dbPath, 0o600);
+    } catch (err) {
+      // Best effort - ignore on platforms without chmod support.
+    }
   }
 
   /**
@@ -460,6 +465,78 @@ class TokenStore {
     this._save(db);
     return { success: true, remote: removed };
   }
+
+  /**
+   * Ensure an inbound caller is present in contacts.
+   *
+   * Inbound callers authenticate with a token we issued; we usually don't
+   * have their endpoint URL, so these records are "placeholders" with:
+   * - host: "inbound"
+   * - no token stored
+   * - linked_token_id: token id used to call us (tok_...)
+   *
+   * This allows mapping call history (SQLite contact_id=tok_...) to a contact
+   * row in the dashboard via linked_token_id.
+   */
+  ensureInboundContact(caller, tokenId) {
+    if (!caller || !caller.name) {
+      return null;
+    }
+
+    const name = String(caller.name || '').trim().slice(0, 120);
+    const owner = caller.owner ? String(caller.owner).trim().slice(0, 120) : null;
+
+    const db = this._load();
+    db.remotes = db.remotes || [];
+
+    // Prefer stable linking by the token used for inbound auth.
+    let remote = tokenId
+      ? db.remotes.find(r => r.linked_token_id === tokenId)
+      : null;
+
+    // Fallback match by agent name/owner (less reliable, but helpful).
+    if (!remote) {
+      remote = db.remotes.find(r => r.name === name || (owner && r.owner === owner));
+    }
+
+    if (remote) {
+      remote.name = remote.name || name;
+      if (owner && !remote.owner) {
+        remote.owner = owner;
+      }
+      if (tokenId && !remote.linked_token_id) {
+        remote.linked_token_id = tokenId;
+      }
+      remote.host = remote.host || 'inbound';
+      remote.tags = Array.isArray(remote.tags) ? remote.tags : [];
+      if (!remote.tags.includes('inbound')) {
+        remote.tags.push('inbound');
+      }
+      remote.status = remote.status || 'unknown';
+      remote.updated_at = new Date().toISOString();
+      this._save(db);
+      return remote;
+    }
+
+    const contact = {
+      id: crypto.randomBytes(8).toString('hex'),
+      name,
+      owner,
+      host: 'inbound',
+      token_hash: null,
+      token_enc: null,
+      notes: tokenId ? `Inbound caller via token ${tokenId}` : 'Inbound caller',
+      tags: ['inbound'],
+      linked_token_id: tokenId || null,
+      status: 'unknown',
+      last_seen: null,
+      added_at: new Date().toISOString()
+    };
+
+    db.remotes.push(contact);
+    this._save(db);
+    return contact;
+  }
 }
 
 // Legacy tier values from old records → label mapping

package/src/routes/a2a.js

@@ -57,6 +57,14 @@ const MAX_MESSAGE_LENGTH = 10000;  // 10KB max message
 const MAX_TIMEOUT_SECONDS = 300;   // 5 min max timeout
 const MIN_TIMEOUT_SECONDS = 5;     // 5 sec min timeout
 
+function isLoopbackAddress(ip) {
+  if (!ip) return false;
+  if (ip === '::1' || ip === '127.0.0.1' || ip === '::ffff:127.0.0.1') {
+    return true;
+  }
+  return ip.startsWith('::ffff:127.');
+}
+
 function checkRateLimit(tokenId, limits = { minute: 10, hour: 100, day: 1000 }) {
   const now = Date.now();
   const minute = Math.floor(now / 60000);
@@ -399,9 +407,18 @@ function createRoutes(options = {}) {
   router.get('/conversations', (req, res) => {
     // This endpoint should be protected by local auth, not A2A tokens
     // For now, require an admin token or local access
+    const expected = process.env.A2A_ADMIN_TOKEN;
     const adminToken = req.headers['x-admin-token'];
-    if (adminToken !== process.env.A2A_ADMIN_TOKEN && req.ip !== '127.0.0.1') {
-      return res.status(401).json({ error: 'unauthorized' });
+    if (!isLoopbackAddress(req.ip)) {
+      if (!expected) {
+        return res.status(401).json({
+          error: 'admin_token_required',
+          message: 'Set A2A_ADMIN_TOKEN to access conversation admin routes from non-local addresses'
+        });
+      }
+      if (adminToken !== expected) {
+        return res.status(401).json({ error: 'unauthorized' });
+      }
     }
 
     const convStore = getConversationStore();
@@ -426,9 +443,18 @@ function createRoutes(options = {}) {
    * Get conversation details with context
    */
   router.get('/conversations/:id', (req, res) => {
+    const expected = process.env.A2A_ADMIN_TOKEN;
     const adminToken = req.headers['x-admin-token'];
-    if (adminToken !== process.env.A2A_ADMIN_TOKEN && req.ip !== '127.0.0.1') {
-      return res.status(401).json({ error: 'unauthorized' });
+    if (!isLoopbackAddress(req.ip)) {
+      if (!expected) {
+        return res.status(401).json({
+          error: 'admin_token_required',
+          message: 'Set A2A_ADMIN_TOKEN to access conversation admin routes from non-local addresses'
+        });
+      }
+      if (adminToken !== expected) {
+        return res.status(401).json({ error: 'unauthorized' });
+      }
     }
 
     const convStore = getConversationStore();

package/src/routes/dashboard.js

@@ -169,7 +169,11 @@ function ensureDashboardAccess(req, res, next) {
     return next();
   }
   if (!adminToken) {
-    return next();
+    return res.status(401).json({
+      success: false,
+      error: 'admin_token_required',
+      message: 'Set A2A_ADMIN_TOKEN to access dashboard from non-local addresses'
+    });
   }
   if (headerToken === adminToken || queryToken === adminToken) {
     return next();

package/src/server.js

@@ -2,17 +2,17 @@
 /**
  * A2A Server
  * 
- * Routes A2A calls to OpenClaw sub-agents.
+ * Routes A2A calls through a runtime adapter (OpenClaw or generic fallback).
  * Auto-adds contacts, generates summaries, notifies owner.
  */
 
 const express = require('express');
-const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const { createRoutes } = require('./routes/a2a');
 const { createDashboardApiRouter, createDashboardUiRouter } = require('./routes/dashboard');
 const { TokenStore } = require('./lib/tokens');
+const { createRuntimeAdapter } = require('./lib/runtime-adapter');
 const { getTopicsForTier, formatTopicsForPrompt, loadManifest } = require('./lib/disclosure');
 const {
   buildConnectionPrompt,
@@ -21,16 +21,23 @@ const {
 } = require('./lib/prompt-template');
 
 const port = process.env.PORT || parseInt(process.argv[2]) || 3001;
-const workspaceDir = process.env.OPENCLAW_WORKSPACE || '/root/clawd';
+const workspaceDir = process.env.A2A_WORKSPACE || process.env.OPENCLAW_WORKSPACE || process.cwd();
 
 // Load workspace context for agent identity
 function loadAgentContext() {
-  let context = { name: 'bappybot', owner: 'Ben Pollack' };
+  let context = {
+    name: process.env.A2A_AGENT_NAME || process.env.AGENT_NAME || 'a2a-agent',
+    owner: process.env.A2A_OWNER_NAME || process.env.USER || 'Agent Owner'
+  };
   
   try {
     const userPath = path.join(workspaceDir, 'USER.md');
     if (fs.existsSync(userPath)) {
       const content = fs.readFileSync(userPath, 'utf8');
+      const agentMatch = content.match(/\*\*Agent:\*\*\s*([^\n]+)/i);
+      if (agentMatch && agentMatch[1]) {
+        context.name = agentMatch[1].trim().slice(0, 80) || context.name;
+      }
       const nameMatch = content.match(/\*\*Name:\*\*\s*([^\n]+)/);
       if (nameMatch) {
         const name = nameMatch[1].trim();
@@ -46,12 +53,20 @@ function loadAgentContext() {
 
 const agentContext = loadAgentContext();
 const tokenStore = new TokenStore();
+const runtime = createRuntimeAdapter({
+  workspaceDir,
+  agentContext
+});
 const VALID_PHASES = new Set(['handshake', 'explore', 'deep_dive', 'synthesize', 'close']);
 const collaborationSessions = new Map();
 const COLLAB_STATE_TTL_MS = readPositiveIntEnv('A2A_COLLAB_STATE_TTL_MS', 6 * 60 * 60 * 1000);
 const MAX_COLLAB_SESSIONS = readPositiveIntEnv('A2A_COLLAB_MAX_SESSIONS', 500);
 
 console.log(`[a2a] Agent: ${agentContext.name} (${agentContext.owner}'s agent)`);
+console.log(`[a2a] Runtime: ${runtime.mode} (${runtime.reason})`);
+if (runtime.warning) {
+  console.warn(`[a2a] Runtime warning: ${runtime.warning}`);
+}
 
 function readPositiveIntEnv(name, fallback) {
   const parsed = Number.parseInt(process.env[name] || '', 10);
@@ -382,42 +397,15 @@ function fallbackCollaborationUpdate(state, inboundMessage, responseText, tierTo
  */
 function ensureContact(caller, tokenId) {
   if (!caller?.name) return null;
-  
+
   try {
-    const remotes = tokenStore.listRemotes();
-    const existing = remotes.find(r => 
-      r.name === caller.name || 
-      (caller.owner && r.owner === caller.owner)
-    );
-    
-    if (existing) {
-      return existing;
+    const contact = tokenStore.ensureInboundContact(caller, tokenId);
+    if (contact) {
+      console.log(`[a2a] 📇 Contact ensured: ${caller.name}${caller.owner ? ` (${caller.owner})` : ''}`);
     }
-    
-    // Create a placeholder contact for the caller
-    const contact = {
-      id: `contact_${Date.now()}`,
-      name: caller.name,
-      owner: caller.owner || null,
-      host: 'inbound', // They called us, we don't have their URL
-      added_at: new Date().toISOString(),
-      notes: `Inbound caller via token ${tokenId}`,
-      tags: ['inbound'],
-      status: 'unknown',
-      linkedTokenId: tokenId
-    };
-    
-    // Save to remotes
-    const db = JSON.parse(fs.readFileSync(tokenStore.dbPath, 'utf8'));
-    db.remotes = db.remotes || [];
-    db.remotes.push(contact);
-    fs.writeFileSync(tokenStore.dbPath, JSON.stringify(db, null, 2));
-    
-    console.log(`[a2a] 📇 New contact added: ${caller.name}${caller.owner ? ` (${caller.owner})` : ''}`);
     return contact;
-    
   } catch (err) {
-    console.error('[a2a] Failed to add contact:', err.message);
+    console.error('[a2a] Failed to ensure contact:', err.message);
     return null;
   }
 }
@@ -489,30 +477,19 @@ async function callAgent(message, a2aContext) {
   const sessionId = `a2a-${conversationId}`;
   
   try {
-    const escapedPrompt = prompt
-      .replace(/\\/g, '\\\\')
-      .replace(/"/g, '\\"')
-      .replace(/\n/g, '\\n')
-      .replace(/\r/g, '');
-    
-    const result = execSync(
-      `openclaw agent --session-id "${sessionId}" --message "${escapedPrompt}" --timeout 55 2>&1`,
-      {
-        encoding: 'utf8',
-        timeout: 65000,
-        maxBuffer: 1024 * 1024,
-        cwd: workspaceDir,
-        env: { ...process.env, FORCE_COLOR: '0' }
+    const rawResponse = await runtime.runTurn({
+      sessionId,
+      prompt,
+      message,
+      caller: a2aContext.caller || {},
+      timeoutMs: 65000,
+      context: {
+        conversationId,
+        tier: tierInfo,
+        ownerName: agentContext.owner,
+        allowedTopics: a2aContext.allowed_topics || []
       }
-    );
-    
-    const lines = result.split('\n').filter(line => 
-      !line.includes('[telegram-topic-tracker]') && 
-      !line.includes('Plugin registered') &&
-      line.trim()
-    );
-    
-    const rawResponse = lines.join('\n').trim() || '[Sub-agent returned empty response]';
+    });
 
     if (collabMode !== 'adaptive') {
       return rawResponse;
@@ -549,8 +526,12 @@ async function callAgent(message, a2aContext) {
     return cleanResponse || '[Sub-agent returned empty response]';
     
   } catch (err) {
-    console.error('[a2a] Sub-agent spawn failed:', err.message);
-    return `[Sub-agent error: ${err.message}]`;
+    console.error('[a2a] Runtime turn handling failed:', err.message);
+    return runtime.buildFallbackResponse(message, {
+      caller: a2aContext.caller,
+      ownerName: agentContext.owner,
+      allowedTopics: a2aContext.allowed_topics || []
+    }, err.message);
   }
 }
 
@@ -584,25 +565,12 @@ Structure your summary with these sections:
 Be concise but specific. No filler.`;
 
   try {
-    const escapedPrompt = prompt.replace(/"/g, '\\"').replace(/\n/g, '\\n');
-    const result = execSync(
-      `openclaw agent --session-id "summary-${Date.now()}" --message "${escapedPrompt}" --timeout 30 2>&1`,
-      { encoding: 'utf8', timeout: 35000, cwd: workspaceDir, env: { ...process.env, FORCE_COLOR: '0' } }
-    );
-    
-    // Filter out noise and get the summary
-    const lines = result.split('\n').filter(line => 
-      !line.includes('[telegram-topic-tracker]') && 
-      !line.includes('Plugin registered') &&
-      line.trim()
-    );
-    
-    const summaryText = lines.join(' ').trim().slice(0, 1000);
-    
-    return {
-      summary: summaryText,
-      ownerSummary: summaryText
-    };
+    return await runtime.summarize({
+      sessionId: `summary-${Date.now()}`,
+      prompt,
+      messages,
+      callerInfo
+    });
   } catch (err) {
     console.error('[a2a] Summary generation failed:', err.message);
     return null;
@@ -615,22 +583,21 @@ Be concise but specific. No filler.`;
 async function notifyOwner({ level, token, caller, message, conversation_id }) {
   const callerName = caller?.name || 'Unknown';
   const callerOwner = caller?.owner ? ` (${caller.owner})` : '';
+  const messageText = String(message || '');
   
   console.log(`[a2a] 📞 Call from ${callerName}${callerOwner}`);
   console.log(`[a2a]    Token: ${token?.name || 'unknown'}`);
-  console.log(`[a2a]    Message: ${message.slice(0, 100)}...`);
-  
-  // Try to notify via Telegram
-  if (level === 'all') {
-    try {
-      const notification = `🤝 **A2A Call**\nFrom: ${callerName}${callerOwner}\n> ${message.slice(0, 150)}...`;
-      execSync(`openclaw message send --channel telegram --message "${notification.replace(/"/g, '\\"')}"`, {
-        timeout: 10000, stdio: 'pipe'
-      });
-    } catch (e) {
-      // Notification failed, continue anyway
-    }
+  if (messageText) {
+    console.log(`[a2a]    Message: ${messageText.slice(0, 100)}...`);
   }
+
+  await runtime.notify({
+    level,
+    token,
+    caller,
+    message: messageText,
+    conversationId: conversation_id
+  });
 }
 
 const app = express();
@@ -668,6 +635,7 @@ app.get('/', (req, res) => {
 app.listen(port, () => {
   console.log(`[a2a] A2A server listening on port ${port}`);
   console.log(`[a2a] Agent: ${agentContext.name} - LIVE`);
+  console.log(`[a2a] Runtime mode: ${runtime.mode}${runtime.failoverEnabled ? ' (failover enabled)' : ''}`);
   console.log(`[a2a] Collaboration mode: ${resolveCollabMode()}`);
-  console.log(`[a2a] Features: sub-agents, auto-contacts, summaries`);
+  console.log(`[a2a] Features: adaptive collaboration, auto-contacts, summaries, dashboard`);
 });