a2acalling 0.1.0

package/docs/protocol.md

@@ -0,0 +1,241 @@
+# Federation Protocol v0 Reference
+
+## Overview
+
+Federation enables OpenClaw agents to call each other across instances with scoped permissions and owner notification.
+
+## Token Format
+
+```
+a2a://<hostname>/<token>
+```
+
+Example: `a2a://my-server.example.com/fed_abc123xyz`
+
+Token structure: `fed_<base64url(24 random bytes)>`
+
+## API Endpoints
+
+All endpoints are prefixed with `/api/federation/`
+
+### GET /status
+
+Check if federation is enabled.
+
+Response:
+```json
+{
+  "federation": true,
+  "version": "0.1.0",
+  "capabilities": ["invoke", "multi-turn"],
+  "rate_limits": {
+    "per_minute": 10,
+    "per_hour": 100,
+    "per_day": 1000
+  }
+}
+```
+
+### GET /ping
+
+Health check endpoint.
+
+Response:
+```json
+{
+  "pong": true,
+  "timestamp": "2026-02-11T17:54:00Z"
+}
+```
+
+### POST /invoke
+
+Call the agent.
+
+Headers:
+```
+Authorization: Bearer fed_abc123xyz
+Content-Type: application/json
+```
+
+Request body:
+```json
+{
+  "message": "Your question or request",
+  "conversation_id": "optional-for-multi-turn",
+  "caller": {
+    "name": "Alice's Agent",
+    "instance": "alice.example.com",
+    "context": "Why I'm calling"
+  },
+  "timeout_seconds": 60
+}
+```
+
+Success response:
+```json
+{
+  "success": true,
+  "conversation_id": "conv_123456",
+  "response": "The agent's response text",
+  "can_continue": true,
+  "tokens_remaining": 47
+}
+```
+
+Error responses:
+```json
+{"success": false, "error": "token_expired", "message": "..."}
+{"success": false, "error": "token_revoked", "message": "..."}
+{"success": false, "error": "permission_denied", "message": "..."}
+{"success": false, "error": "rate_limited", "message": "..."}
+{"success": false, "error": "missing_token", "message": "..."}
+{"success": false, "error": "missing_message", "message": "..."}
+```
+
+## Permission Scopes
+
+| Scope | Tools | Files | Memory | Actions |
+|-------|-------|-------|--------|---------|
+| `chat-only` | ❌ | ❌ | ❌ | ❌ |
+| `tools-read` | Read | Read | ❌ | ❌ |
+| `tools-write` | All | All | ❌ | Notify owner |
+
+## Disclosure Levels
+
+| Level | Behavior |
+|-------|----------|
+| `public` | Agent may share any non-private information |
+| `minimal` | Agent gives direct answers only, no context about owner |
+| `none` | Agent confirms capability only, provides no actual information |
+
+## Token Storage Schema
+
+Stored in `~/.config/openclaw/federation.json`:
+
+```json
+{
+  "tokens": [
+    {
+      "id": "fed_abc123xyz789",
+      "token_hash": "sha256...",
+      "name": "Alice's agent",
+      "permissions": "chat-only",
+      "disclosure": "minimal",
+      "notify": "all",
+      "max_calls": null,
+      "calls_made": 5,
+      "created_at": "2026-02-11T17:54:00Z",
+      "expires_at": "2026-02-18T17:54:00Z",
+      "last_used": "2026-02-12T10:30:00Z",
+      "revoked": false
+    }
+  ],
+  "remotes": [
+    {
+      "id": "remote_xyz",
+      "name": "Bob's agent",
+      "host": "bob.example.com",
+      "token": "fed_bobtoken123",
+      "added_at": "2026-02-11T18:00:00Z"
+    }
+  ],
+  "calls": []
+}
+```
+
+## Rate Limits
+
+Default per-token limits:
+- 10 requests per minute
+- 100 requests per hour
+- 1000 requests per day
+
+Limits reset on natural boundaries (minute, hour, day UTC).
+
+## Security Considerations
+
+1. **Token hashing**: Tokens stored as SHA-256 hashes server-side
+2. **TLS required**: All federation calls should use HTTPS
+3. **No credential forwarding**: Tokens are never forwarded to other agents
+4. **Audit logging**: All invocations are logged with caller info
+5. **Auto-revocation**: Tokens may auto-revoke after repeated errors
+
+## Multi-turn Conversations
+
+To continue a conversation, include `conversation_id` from the previous response:
+
+```json
+{
+  "message": "Follow-up question",
+  "conversation_id": "conv_123456"
+}
+```
+
+Conversations expire after 1 hour of inactivity.
+
+## Owner Notifications
+
+When `notify: all`:
+```
+🤝 Federation call received
+
+From: Alice's Agent (alice.example.com)
+Token: "Work collab" (expires 2026-02-18)
+
+---
+Alice's Agent: Does Ben have time this week?
+You: Ben is available Thursday 2-4pm.
+---
+
+📊 5 of unlimited calls | Token expires in 6d
+```
+
+Owner can reply to inject into the conversation.
+
+## OpenClaw Integration
+
+### Gateway Route Registration
+
+Add to gateway routes:
+```javascript
+const federation = require('./skills/federation/scripts/server');
+app.use('/api/federation', federation);
+```
+
+### Agent Context
+
+When handling a federation call, inject context:
+```json
+{
+  "federation": {
+    "active": true,
+    "caller": "Alice's Agent",
+    "permissions": "chat-only",
+    "disclosure": "minimal"
+  }
+}
+```
+
+### New Tool: federation_call
+
+```typescript
+federation_call({
+  endpoint: string,    // a2a:// URL
+  message: string,     // Message to send
+  conversation_id?: string  // For multi-turn
+}): {
+  success: boolean,
+  response?: string,
+  conversation_id?: string,
+  error?: string
+}
+```
+
+## Future Protocol Extensions (v1+)
+
+- **Capability advertisement**: Agents declare what they can help with
+- **Cryptographic identity**: Ed25519 signatures for caller verification
+- **Streaming responses**: SSE for long-running operations
+- **Webhooks**: Push notifications instead of polling
+- **Payments**: Token-gated access with usage billing

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "a2acalling",
+  "version": "0.1.0",
+  "description": "Agent-to-agent calling for OpenClaw - federated agent communication",
+  "main": "src/index.js",
+  "bin": {
+    "a2a": "bin/cli.js",
+    "a2acalling": "scripts/install-openclaw.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node test/run.js"
+  },
+  "keywords": [
+    "openclaw",
+    "claudebot",
+    "agent",
+    "federation",
+    "a2a",
+    "ai"
+  ],
+  "author": "OpenClaw Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onthegonow/A2A_for_OpenClaw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/onthegonow/A2A_for_OpenClaw/issues"
+  },
+  "homepage": "https://github.com/onthegonow/A2A_for_OpenClaw#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.10.0"
+  },
+  "devDependencies": {
+    "express": "^5.2.1"
+  }
+}

package/scripts/install-openclaw.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * A2A Calling - OpenClaw Integration Installer
+ * 
+ * This script:
+ * 1. Installs the a2a skill to the user's OpenClaw skills directory
+ * 2. Adds /a2a as a custom command in OpenClaw config
+ * 3. Sets up the federation server as a systemd service (optional)
+ * 
+ * Usage:
+ *   npx a2acalling install
+ *   npx a2acalling install --hostname myserver.com
+ *   npx a2acalling install --port 3001
+ *   npx a2acalling uninstall
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Paths
+const OPENCLAW_CONFIG = process.env.OPENCLAW_CONFIG || path.join(process.env.HOME, '.openclaw', 'openclaw.json');
+const OPENCLAW_SKILLS = process.env.OPENCLAW_SKILLS || path.join(process.env.HOME, '.openclaw', 'skills');
+const SKILL_NAME = 'a2a';
+
+// Parse args
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = {};
+for (let i = 1; i < args.length; i++) {
+  if (args[i].startsWith('--')) {
+    const key = args[i].slice(2);
+    flags[key] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+  }
+}
+
+// Colors
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+function log(msg) { console.log(`${green('[a2a]')} ${msg}`); }
+function warn(msg) { console.log(`${yellow('[a2a]')} ${msg}`); }
+function error(msg) { console.error(`${red('[a2a]')} ${msg}`); }
+
+// Skill content
+const SKILL_MD = `---
+name: a2a
+description: "Agent-to-Agent federation. Handle /a2a commands to create tokens, manage connections, and call remote agents. Triggers on: /a2a, federation, agent token, a2a invite."
+---
+
+# A2A Federation
+
+Handle agent-to-agent communication with Telegram inline buttons + \`a2a\` CLI.
+
+## CRITICAL: Forum Topic Threading
+
+When sending messages with buttons in Telegram forum groups, **ALWAYS include threadId**:
+
+1. Extract topic ID from message header (e.g., \`topic:567\`)
+2. Include \`threadId: "TOPIC_ID"\` in ALL message tool calls
+
+## Onboarding (First Run)
+
+**BEFORE showing tiers, ALWAYS read and analyze user context:**
+- HEARTBEAT.md - current tasks/interests
+- USER.md - professional context, shareable bio
+- SOUL.md - agent personality
+- memory/*.md - stored context
+
+**Extract:** Topics of interest, goals, professional context (job seeking?), sensitive areas.
+
+**Personalize tiers based on findings** - not generic examples!
+
+**Step 1:** Show analyzed topics grouped into Public/Friends/Private tiers
+**Step 2:** Confirm default settings (expiration, rate limits)
+**Step 3:** Confirm agent identity
+**Step 4:** Complete - save config, show next steps
+
+Settings saved to ~/.config/openclaw/a2a-config.json
+
+## Main Menu (Post-Onboarding)
+
+\`\`\`javascript
+message({
+  action: "send",
+  channel: "telegram",
+  target: "CHAT_ID",
+  threadId: "TOPIC_ID",  // REQUIRED for forum topics!
+  message: "🤝 **A2A Federation**\\n\\nWhat would you like to do?",
+  buttons: [
+    [{ text: "📝 Create Invite", callback_data: "/a2a invite" }, { text: "📋 List Tokens", callback_data: "/a2a list" }],
+    [{ text: "🗑 Revoke Token", callback_data: "/a2a revoke" }, { text: "📡 Add Remote", callback_data: "/a2a add" }]
+  ]
+})
+\`\`\`
+
+## Commands
+
+### /a2a invite
+\`\`\`bash
+a2a create --name "NAME" --expires "DURATION"
+\`\`\`
+Reply with full shareable invite block.
+
+### /a2a list
+\`\`\`bash
+a2a list
+\`\`\`
+
+### /a2a revoke <id>
+\`\`\`bash
+a2a revoke TOKEN_ID
+\`\`\`
+
+### /a2a add <url> [name]
+\`\`\`bash
+a2a add "URL" "NAME"
+\`\`\`
+
+### /a2a call <url> <msg>
+\`\`\`bash
+a2a call "URL" "MESSAGE"
+\`\`\`
+
+## Server
+
+\`\`\`bash
+a2a server --port 3001
+\`\`\`
+
+## Defaults
+- Expiration: 1 day
+- Max calls: 100
+- Rate limit: 10/min
+`;
+
+function install() {
+  log('Installing A2A Calling for OpenClaw...\n');
+
+  // 1. Create skills directory if needed
+  if (!fs.existsSync(OPENCLAW_SKILLS)) {
+    fs.mkdirSync(OPENCLAW_SKILLS, { recursive: true });
+    log(`Created skills directory: ${OPENCLAW_SKILLS}`);
+  }
+
+  // 2. Install skill
+  const skillDir = path.join(OPENCLAW_SKILLS, SKILL_NAME);
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), SKILL_MD);
+  log(`Installed skill to: ${skillDir}`);
+
+  // 3. Update OpenClaw config
+  if (fs.existsSync(OPENCLAW_CONFIG)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(OPENCLAW_CONFIG, 'utf8'));
+      
+      // Add custom command for each channel that supports it
+      const channels = ['telegram', 'discord', 'slack'];
+      let updated = false;
+      
+      for (const channel of channels) {
+        if (config.channels?.[channel]?.enabled) {
+          if (!config.channels[channel].customCommands) {
+            config.channels[channel].customCommands = [];
+          }
+          
+          const existing = config.channels[channel].customCommands.find(c => c.command === 'a2a');
+          if (!existing) {
+            config.channels[channel].customCommands.push({
+              command: 'a2a',
+              description: 'Agent-to-Agent: create invitations, manage connections'
+            });
+            updated = true;
+            log(`Added /a2a command to ${channel} config`);
+          } else {
+            log(`/a2a command already exists in ${channel} config`);
+          }
+        }
+      }
+      
+      if (updated) {
+        // Backup original
+        const backupPath = `${OPENCLAW_CONFIG}.backup.${Date.now()}`;
+        fs.copyFileSync(OPENCLAW_CONFIG, backupPath);
+        log(`Backed up config to: ${backupPath}`);
+        
+        // Write updated config
+        fs.writeFileSync(OPENCLAW_CONFIG, JSON.stringify(config, null, 2));
+        log('Updated OpenClaw config');
+        warn('Restart OpenClaw gateway to apply changes: openclaw gateway restart');
+      }
+    } catch (e) {
+      warn(`Could not update OpenClaw config: ${e.message}`);
+      warn('You may need to manually add the /a2a custom command');
+    }
+  } else {
+    warn(`OpenClaw config not found at: ${OPENCLAW_CONFIG}`);
+    warn('You may need to manually add the /a2a custom command');
+  }
+
+  // 4. Show server setup instructions
+  const hostname = flags.hostname || process.env.HOSTNAME || 'localhost';
+  const port = flags.port || '3001';
+  
+  console.log(`
+${bold('━━━ Server Setup ━━━')}
+
+To receive incoming calls, run the a2a server:
+
+  ${green(`A2A_HOSTNAME="${hostname}:${port}" a2a server`)}
+
+Or create a systemd service:
+
+  ${green('sudo a2a service install')}
+
+${bold('━━━ Usage ━━━')}
+
+In your chat app, use:
+
+  /a2a invite         Create an invitation token
+  /a2a list           List active tokens
+  /a2a revoke <id>    Revoke a token
+  /a2a add <url>      Add a remote agent
+  /a2a call <url> <msg>  Call a remote agent
+
+${bold('━━━ Done! ━━━')}
+
+${green('✅ A2A Calling installed successfully!')}
+`);
+}
+
+function uninstall() {
+  log('Uninstalling A2A Calling...\n');
+
+  // Remove skill
+  const skillDir = path.join(OPENCLAW_SKILLS, SKILL_NAME);
+  if (fs.existsSync(skillDir)) {
+    fs.rmSync(skillDir, { recursive: true });
+    log(`Removed skill from: ${skillDir}`);
+  }
+
+  // Note about config
+  warn('Custom command in OpenClaw config was not removed.');
+  warn('You can manually remove it if desired.');
+
+  log('✅ Uninstall complete');
+}
+
+function showHelp() {
+  console.log(`
+${bold('A2A Calling - OpenClaw Integration')}
+
+Usage:
+  npx a2acalling install [options]    Install A2A for OpenClaw
+  npx a2acalling uninstall            Remove A2A skill
+  npx a2acalling server               Start federation server
+
+Install Options:
+  --hostname <host>    Hostname for invite URLs (default: system hostname)
+  --port <port>        Server port (default: 3001)
+
+Examples:
+  npx a2acalling install --hostname myserver.com --port 443
+  npx a2acalling server --port 3001
+`);
+}
+
+// Main
+switch (command) {
+  case 'install':
+    install();
+    break;
+  case 'uninstall':
+    uninstall();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+  default:
+    if (command) {
+      error(`Unknown command: ${command}`);
+    }
+    showHelp();
+    process.exit(command ? 1 : 0);
+}

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * A2A Calling - Agent-to-Agent Communication for OpenClaw
+ * 
+ * @example
+ * // Server side - mount routes
+ * const { createRoutes, TokenStore } = require('a2acalling');
+ * const tokenStore = new TokenStore();
+ * app.use('/api/federation', createRoutes({ tokenStore, handleMessage }));
+ * 
+ * @example
+ * // Client side - call remote agent
+ * const { A2AClient } = require('a2acalling');
+ * const client = new A2AClient({ caller: { name: 'My Agent' } });
+ * const response = await client.call('a2a://host/token', 'Hello!');
+ */
+
+const { TokenStore } = require('./lib/tokens');
+const { A2AClient, A2AError } = require('./lib/client');
+const { createRoutes } = require('./routes/federation');
+
+// Lazy load optional dependencies
+let ConversationStore = null;
+let summarizers = null;
+let CallMonitor = null;
+let openclawIntegration = null;
+
+try {
+  ConversationStore = require('./lib/conversations').ConversationStore;
+  summarizers = require('./lib/summarizer');
+  CallMonitor = require('./lib/call-monitor').CallMonitor;
+  openclawIntegration = require('./lib/openclaw-integration');
+} catch (err) {
+  // Optional dependencies not installed
+}
+
+module.exports = {
+  // Token management
+  TokenStore,
+  
+  // Client for outbound calls
+  A2AClient,
+  A2AError,
+  
+  // Express routes for inbound calls
+  createRoutes,
+  
+  // Conversation storage (requires better-sqlite3)
+  ConversationStore,
+  
+  // Call monitoring for auto-conclude
+  CallMonitor,
+  
+  // Summarizers for conversation conclusion
+  ...(summarizers || {}),
+  
+  // OpenClaw integration helpers
+  ...(openclawIntegration || {}),
+  
+  // Version
+  version: require('../package.json').version
+};