ai2ai 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# 🦞 ai2ai
+
+**The open protocol for AI agents to talk to each other.**
+
+AI2AI lets your AI agent communicate with other AI agents — scheduling meetings, relaying messages, asking questions, and more. No platform lock-in, no central server. Just agents talking to agents.
+
+## Install
+
+```bash
+npm install -g ai2ai
+```
+
+Or run directly:
+
+```bash
+npx ai2ai
+```
+
+## Quick Start
+
+### 1. Set up your identity
+
+```bash
+ai2ai init
+```
+
+The setup wizard will ask your name, create an agent identity, generate Ed25519 keys, and save everything to `~/.ai2ai/`.
+
+### 2. Start your server
+
+```bash
+ai2ai start
+```
+
+This starts an HTTP server that listens for incoming AI2AI messages.
+
+### 3. Connect to a friend
+
+```bash
+ai2ai connect http://friend.example.com:18800/ai2ai
+```
+
+This pings the remote agent, exchanges public keys, and saves them as a contact.
+
+### 4. Send messages
+
+```bash
+# Simple message
+ai2ai send alex "Hey, are you free this weekend?"
+
+# Scheduling (auto-detected)
+ai2ai send alex "dinner next Thursday at 7pm?"
+
+# Questions (auto-detected)
+ai2ai send alex "What time works for you?"
+```
+
+AI2AI automatically detects message intent:
+- **Scheduling keywords** → `schedule.meeting` intent
+- **Questions** → `info.request` intent
+- **Everything else** → `message.relay` intent
+
+### 5. Check for responses
+
+```bash
+ai2ai pending
+```
+
+### 6. Approve or reject
+
+```bash
+ai2ai approve 1 "Thursday works for me!"
+ai2ai reject 2
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai2ai init` | Interactive setup wizard |
+| `ai2ai start` | Start the AI2AI server |
+| `ai2ai connect <endpoint>` | Connect to another agent |
+| `ai2ai send <contact> <msg>` | Send a message to a contact |
+| `ai2ai pending` | Show pending messages |
+| `ai2ai approve <id> [reply]` | Approve a pending message |
+| `ai2ai reject <id>` | Reject a pending message |
+| `ai2ai contacts` | List known contacts |
+| `ai2ai status` | Show server & agent status |
+
+## Protocol
+
+AI2AI uses a simple JSON envelope over HTTP:
+
+```json
+{
+  "ai2ai": "0.1",
+  "id": "uuid",
+  "timestamp": "2025-02-07T12:00:00.000Z",
+  "from": {
+    "agent": "darren-assistant",
+    "node": "darren-assistant-node",
+    "human": "Darren"
+  },
+  "to": {
+    "agent": "alex-assistant",
+    "node": "alex-assistant-node",
+    "human": "Alex"
+  },
+  "conversation": "uuid",
+  "type": "request",
+  "intent": "message.relay",
+  "payload": {
+    "message": "Hey, are you free Thursday?",
+    "urgency": "low",
+    "reply_requested": true
+  },
+  "signature": "base64-ed25519-signature"
+}
+```
+
+### Message Types
+
+- **`ping`** — Handshake, exchange capabilities and public keys
+- **`request`** — Ask another agent to do something
+- **`response`** — Reply to a request
+- **`confirm`** — Accept a proposal
+- **`reject`** — Decline a proposal
+- **`inform`** — One-way notification
+
+### Supported Intents
+
+- `schedule.meeting` — Schedule a meeting
+- `schedule.call` — Schedule a call
+- `message.relay` — Relay a message to a human
+- `info.request` — Ask a question
+- `info.share` — Share information
+- `social.introduction` — Introduce two people
+
+## Security
+
+- **Ed25519 signatures** — Every message is signed with your agent's private key
+- **Key exchange** — Public keys are exchanged during the `connect` handshake
+- **Signature verification** — Incoming messages from known contacts are verified
+- **Trust levels** — Contacts have trust levels (`none`, `known`, `trusted`)
+- **Rate limiting** — 20 messages per minute per agent
+- **Human approval** — All incoming requests go to a pending queue for human review
+
+## Configuration
+
+All data is stored in `~/.ai2ai/`:
+
+```
+~/.ai2ai/
+├── config.json       # Agent configuration
+├── contacts.json     # Known contacts
+├── keys/
+│   ├── agent.pub     # Ed25519 public key
+│   └── agent.key     # Ed25519 private key (mode 0600)
+├── pending/          # Messages awaiting approval
+├── conversations/    # Conversation history
+└── logs/             # Server logs
+```
+
+## Discovery
+
+Your agent serves a `.well-known/ai2ai.json` endpoint for web-based discovery:
+
+```
+GET http://localhost:18800/.well-known/ai2ai.json
+```
+
+## Requirements
+
+- **Node.js 18+**
+- **Zero external dependencies** — Uses only Node.js built-in modules
+
+## License
+
+MIT
+
+## Links
+
+- [Protocol Specification](https://github.com/DarrenEdwards111/ai2ai-protocol)
+- [Report Issues](https://github.com/DarrenEdwards111/ai2ai-protocol/issues)

package/bin/ai2ai.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * ai2ai — The open protocol for AI agents to talk to each other
+ *
+ * Usage:
+ *   ai2ai init                    Interactive setup wizard
+ *   ai2ai start                   Start the AI2AI server
+ *   ai2ai connect <endpoint>      Connect to another agent
+ *   ai2ai send <contact> <msg>    Send a message to a contact
+ *   ai2ai pending                 Show pending messages
+ *   ai2ai approve <id> [reply]    Approve a pending message
+ *   ai2ai reject <id>             Reject a pending message
+ *   ai2ai contacts                List known contacts
+ *   ai2ai status                  Show server & agent status
+ */
+
+'use strict';
+
+const HELP = `
+🦞 ai2ai — Agent-to-Agent Communication Protocol
+
+Usage:
+  ai2ai init                       Set up your AI2AI identity
+  ai2ai start                      Start the AI2AI server
+  ai2ai connect <endpoint>         Connect to another agent
+  ai2ai send <contact> <message>   Send a message to a contact
+  ai2ai pending                    Show pending messages
+  ai2ai approve <id> [reply]       Approve a pending message
+  ai2ai reject <id>                Reject a pending message
+  ai2ai contacts                   List known contacts
+  ai2ai status                     Show server & agent status
+
+Examples:
+  ai2ai init
+  ai2ai start
+  ai2ai connect http://friend.example.com:18800/ai2ai
+  ai2ai send alex "dinner next Thursday?"
+  ai2ai pending
+  ai2ai approve 1 "Thursday works for me"
+
+Options:
+  --help, -h     Show this help message
+  --version, -v  Show version number
+`;
+
+const VERSION = '0.1.0';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  console.log(`ai2ai v${VERSION}`);
+  process.exit(0);
+}
+
+const commands = {
+  init:     () => require('../lib/init').run(),
+  start:    () => require('../lib/start').run(),
+  connect:  () => require('../lib/connect').run(args.slice(1)),
+  send:     () => require('../lib/send').run(args.slice(1)),
+  pending:  () => require('../lib/pending').run(),
+  approve:  () => require('../lib/approve').run(args.slice(1)),
+  reject:   () => require('../lib/approve').runReject(args.slice(1)),
+  contacts: () => require('../lib/contacts').run(),
+  status:   () => require('../lib/status').run(),
+};
+
+if (!commands[command]) {
+  console.error(`\n❌ Unknown command: ${command}\n`);
+  console.log(HELP);
+  process.exit(1);
+}
+
+// Run the command
+Promise.resolve(commands[command]()).catch(err => {
+  console.error(`\n❌ Error: ${err.message}\n`);
+  if (process.env.AI2AI_DEBUG) {
+    console.error(err.stack);
+  }
+  process.exit(1);
+});

package/lib/approve.js

@@ -0,0 +1,137 @@
+/**
+ * ai2ai approve / reject — Handle pending messages
+ * Approve with an optional reply, or reject.
+ */
+
+'use strict';
+
+const { requireConfig, findContact } = require('./config');
+const { createEnvelope, sendRequest } = require('./protocol');
+const { getPendingByNumber, removePending } = require('./pending');
+
+/**
+ * Send a response back to the originating agent
+ */
+async function sendResponse(envelope, type, payload) {
+  const config = requireConfig();
+  const from = envelope.from;
+
+  // Find their endpoint
+  const contact = findContact(from.agent);
+  if (!contact?.endpoint) {
+    console.log(`  ⚠️  No endpoint for ${from.agent}. Response saved locally only.`);
+    return null;
+  }
+
+  const response = createEnvelope({
+    to: {
+      agent: from.agent,
+      node: from.node || `${from.agent}-node`,
+      human: from.human || from.agent,
+    },
+    type,
+    intent: envelope.intent,
+    conversationId: envelope.conversation,
+    payload,
+  });
+
+  return sendRequest(contact.endpoint, response);
+}
+
+async function run(args) {
+  if (!args[0]) {
+    console.error('\n  ❌ Usage: ai2ai approve <number> [reply]');
+    console.error('  Example: ai2ai approve 1 "Thursday works!"\n');
+    process.exit(1);
+  }
+
+  const num = parseInt(args[0]);
+  if (isNaN(num)) {
+    console.error(`\n  ❌ "${args[0]}" is not a valid number.\n`);
+    process.exit(1);
+  }
+
+  const pending = getPendingByNumber(num);
+  if (!pending) {
+    console.error(`\n  ❌ No pending message #${num}. Run \`ai2ai pending\` to check.\n`);
+    process.exit(1);
+  }
+
+  const reply = args.slice(1).join(' ').replace(/^["']|["']$/g, '') || null;
+  const from = pending.envelope?.from?.human || pending.envelope?.from?.agent || 'Unknown';
+
+  console.log(`\n  ✅ Approving message from ${from}...`);
+
+  // Build response payload
+  const responsePayload = {};
+
+  if (pending.envelope?.intent === 'schedule.meeting') {
+    const times = pending.envelope.payload?.proposed_times || [];
+    const num = reply ? parseInt(reply) : null;
+    if (num && num >= 1 && num <= times.length) {
+      responsePayload.accepted_time = times[num - 1];
+      responsePayload.message = `Accepted: ${new Date(times[num - 1]).toLocaleString()}`;
+    } else {
+      responsePayload.counter_proposal = reply;
+      responsePayload.message = reply || 'Approved';
+    }
+  } else if (pending.envelope?.intent === 'info.request') {
+    responsePayload.answer = reply || 'Acknowledged';
+  } else {
+    responsePayload.message = reply || 'Approved';
+    responsePayload.is_reply = !!reply;
+  }
+
+  try {
+    const result = await sendResponse(pending.envelope, 'response', responsePayload);
+    if (result) {
+      console.log(`  📤 Response sent to ${from}'s agent.`);
+    }
+  } catch (err) {
+    console.log(`  ⚠️  Could not send response: ${err.message}`);
+    console.log('     (The approval is still recorded locally.)');
+  }
+
+  // Remove from pending
+  removePending(pending.id);
+  console.log(`  🗑️  Removed from pending.\n`);
+}
+
+async function runReject(args) {
+  if (!args[0]) {
+    console.error('\n  ❌ Usage: ai2ai reject <number>');
+    console.error('  Example: ai2ai reject 1\n');
+    process.exit(1);
+  }
+
+  const num = parseInt(args[0]);
+  if (isNaN(num)) {
+    console.error(`\n  ❌ "${args[0]}" is not a valid number.\n`);
+    process.exit(1);
+  }
+
+  const pending = getPendingByNumber(num);
+  if (!pending) {
+    console.error(`\n  ❌ No pending message #${num}. Run \`ai2ai pending\` to check.\n`);
+    process.exit(1);
+  }
+
+  const reason = args.slice(1).join(' ').replace(/^["']|["']$/g, '') || 'Declined';
+  const from = pending.envelope?.from?.human || pending.envelope?.from?.agent || 'Unknown';
+
+  console.log(`\n  ❌ Rejecting message from ${from}...`);
+
+  try {
+    const result = await sendResponse(pending.envelope, 'reject', { reason });
+    if (result) {
+      console.log(`  📤 Rejection sent to ${from}'s agent.`);
+    }
+  } catch (err) {
+    console.log(`  ⚠️  Could not send rejection: ${err.message}`);
+  }
+
+  removePending(pending.id);
+  console.log(`  🗑️  Removed from pending.\n`);
+}
+
+module.exports = { run, runReject };

package/lib/config.js

@@ -0,0 +1,120 @@
+/**
+ * AI2AI Config — Configuration and path management
+ * All config stored in ~/.ai2ai/
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const AI2AI_DIR = path.join(os.homedir(), '.ai2ai');
+const CONFIG_PATH = path.join(AI2AI_DIR, 'config.json');
+const CONTACTS_PATH = path.join(AI2AI_DIR, 'contacts.json');
+const KEYS_DIR = path.join(AI2AI_DIR, 'keys');
+const PENDING_DIR = path.join(AI2AI_DIR, 'pending');
+const CONVERSATIONS_DIR = path.join(AI2AI_DIR, 'conversations');
+const LOGS_DIR = path.join(AI2AI_DIR, 'logs');
+
+/**
+ * Ensure all required directories exist
+ */
+function ensureDirs() {
+  for (const dir of [AI2AI_DIR, KEYS_DIR, PENDING_DIR, CONVERSATIONS_DIR, LOGS_DIR]) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Load config from disk
+ */
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save config to disk
+ */
+function saveConfig(config) {
+  ensureDirs();
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Load config or exit with a helpful message
+ */
+function requireConfig() {
+  const config = loadConfig();
+  if (!config) {
+    console.error('\n❌ No AI2AI configuration found.');
+    console.error('   Run `ai2ai init` to set up your agent.\n');
+    process.exit(1);
+  }
+  return config;
+}
+
+/**
+ * Load contacts from disk
+ */
+function loadContacts() {
+  if (!fs.existsSync(CONTACTS_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(CONTACTS_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save contacts to disk
+ */
+function saveContacts(contacts) {
+  ensureDirs();
+  fs.writeFileSync(CONTACTS_PATH, JSON.stringify(contacts, null, 2));
+}
+
+/**
+ * Find a contact by name or agent ID (fuzzy match)
+ */
+function findContact(query) {
+  const contacts = loadContacts();
+  const q = query.toLowerCase();
+
+  // Exact match on agent ID
+  if (contacts[q]) return { id: q, ...contacts[q] };
+
+  // Search by human name or agent ID prefix
+  for (const [id, contact] of Object.entries(contacts)) {
+    if (id.toLowerCase().includes(q)) return { id, ...contact };
+    if (contact.humanName && contact.humanName.toLowerCase().includes(q)) {
+      return { id, ...contact };
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  AI2AI_DIR,
+  CONFIG_PATH,
+  CONTACTS_PATH,
+  KEYS_DIR,
+  PENDING_DIR,
+  CONVERSATIONS_DIR,
+  LOGS_DIR,
+  ensureDirs,
+  loadConfig,
+  saveConfig,
+  requireConfig,
+  loadContacts,
+  saveContacts,
+  findContact,
+};

package/lib/connect.js

@@ -0,0 +1,89 @@
+/**
+ * ai2ai connect — Connect to another AI agent
+ * Pings the remote endpoint, exchanges keys, and saves as contact.
+ */
+
+'use strict';
+
+const { requireConfig, loadContacts, saveContacts } = require('./config');
+const { createPingEnvelope, sendRequest } = require('./protocol');
+const { getFingerprint } = require('./crypto');
+
+async function run(args) {
+  if (!args[0]) {
+    console.error('\n  ❌ Usage: ai2ai connect <endpoint>');
+    console.error('  Example: ai2ai connect http://friend.example.com:18800/ai2ai\n');
+    process.exit(1);
+  }
+
+  let endpoint = args[0];
+
+  // Auto-append /ai2ai if needed
+  if (!endpoint.endsWith('/ai2ai')) {
+    if (endpoint.endsWith('/')) endpoint += 'ai2ai';
+    else endpoint += '/ai2ai';
+  }
+
+  const config = requireConfig();
+
+  console.log(`\n  🔗 Connecting to ${endpoint}...`);
+
+  try {
+    const envelope = createPingEnvelope();
+    const response = await sendRequest(endpoint, envelope);
+
+    if (response.status !== 'ok' || response.type !== 'ping') {
+      console.error(`\n  ❌ Unexpected response: ${JSON.stringify(response)}\n`);
+      process.exit(1);
+    }
+
+    const payload = response.payload || {};
+    const agentName = payload.agent_name || 'unknown';
+    const remoteFingerprint = payload.fingerprint || '(none)';
+
+    // Save as contact
+    const contacts = loadContacts();
+
+    // Try to find the agent name from the response
+    // The server may return its identity in various fields
+    let contactId = agentName;
+    if (contactId === 'unknown' && payload.public_key) {
+      // Use fingerprint-based ID as fallback
+      contactId = `agent-${getFingerprint(payload.public_key).slice(0, 9).replace(/:/g, '')}`;
+    }
+
+    contacts[contactId] = {
+      ...contacts[contactId],
+      endpoint,
+      publicKey: payload.public_key || null,
+      fingerprint: remoteFingerprint,
+      capabilities: payload.capabilities || [],
+      timezone: payload.timezone || null,
+      trustLevel: contacts[contactId]?.trustLevel || 'known',
+      connectedAt: contacts[contactId]?.connectedAt || new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+    };
+
+    saveContacts(contacts);
+
+    console.log(`
+  ✅ Connected!
+
+  🤖 Agent:        ${contactId}
+  🔑 Fingerprint:  ${remoteFingerprint}
+  🕐 Timezone:     ${payload.timezone || 'Unknown'}
+  🛠️  Capabilities: ${(payload.capabilities || []).join(', ') || 'None listed'}
+  📁 Saved to contacts
+
+  You can now:
+    ai2ai send ${contactId} "Hello!"
+`);
+
+  } catch (err) {
+    console.error(`\n  ❌ Connection failed: ${err.message}`);
+    console.error('  Make sure the remote agent is running.\n');
+    process.exit(1);
+  }
+}
+
+module.exports = { run };

package/lib/contacts.js

@@ -0,0 +1,62 @@
+/**
+ * ai2ai contacts — List all known contacts
+ */
+
+'use strict';
+
+const { loadContacts } = require('./config');
+
+/**
+ * Format trust level with emoji
+ */
+function trustEmoji(level) {
+  switch (level) {
+    case 'trusted': return '🟢 trusted';
+    case 'known':   return '🟡 known';
+    case 'none':    return '⚪ none';
+    default:        return '⚪ none';
+  }
+}
+
+async function run() {
+  const contacts = loadContacts();
+  const ids = Object.keys(contacts);
+
+  if (ids.length === 0) {
+    console.log('\n  📭 No contacts yet.');
+    console.log('  Run `ai2ai connect <endpoint>` to add one.\n');
+    return;
+  }
+
+  console.log(`\n  👥 Contacts (${ids.length})\n`);
+  console.log('  ─'.repeat(25));
+
+  for (const id of ids) {
+    const c = contacts[id];
+    const human = c.humanName || '(unknown)';
+    const trust = trustEmoji(c.trustLevel);
+    const endpoint = c.endpoint || '(no endpoint)';
+    const lastSeen = c.lastSeen ? new Date(c.lastSeen).toLocaleString() : 'Never';
+    const caps = (c.capabilities || []).length;
+
+    console.log(`
+  🤖 ${id}
+     Human:       ${human}
+     Trust:       ${trust}
+     Endpoint:    ${endpoint}
+     Capabilities: ${caps} intents
+     Last seen:   ${lastSeen}`);
+
+    if (c.fingerprint) {
+      console.log(`     Fingerprint: ${c.fingerprint}`);
+    }
+    if (c.timezone) {
+      console.log(`     Timezone:    ${c.timezone}`);
+    }
+  }
+
+  console.log('\n  ─'.repeat(25));
+  console.log('');
+}
+
+module.exports = { run };