ai2ai 0.1.0 → 1.0.1

package/.keys/agent.key

@@ -0,0 +1,3 @@
+-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEIM4w1HJb8pGX9saKzOWe2+F/gUPodQFlLynR7WBEIFih
+-----END PRIVATE KEY-----

package/.keys/agent.pub

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAEZLXvE1B1UM8koD+6lAO7tRlQjgag5lmbXghK+uy1es=
+-----END PUBLIC KEY-----

package/README.md

@@ -1,184 +1,526 @@
-# 🦞 ai2ai
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DarrenEdwards111/ai2ai-protocol/main/logo.jpg" alt="AI2AI Protocol" width="200" />
+</p>
 
-**The open protocol for AI agents to talk to each other.**
+<h1 align="center">AI2AI Protocol</h1>
 
-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.
+<p align="center">
+  <strong>Production-ready agent-to-agent communication protocol</strong><br>
+  Zero dependencies • Ed25519 signed • Encrypted • Discoverable
+</p>
 
-## Install
+<p align="center">
+  <a href="https://www.npmjs.com/package/ai2ai-protocol"><img src="https://img.shields.io/npm/v/ai2ai-protocol.svg" alt="npm"></a>
+  <a href="https://github.com/DarrenEdwards111/ai2ai-protocol/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="Zero deps">
+</p>
 
-```bash
-npm install -g ai2ai
+---
+
+## Quick Start
+
+```js
+const { AI2AI } = require('ai2ai-protocol/src/client');
+
+const agent = new AI2AI({ name: 'my-agent', port: 18800 });
+await agent.start();
+await agent.send('other-agent', 'Hello from my AI!');
 ```
 
-Or run directly:
+## Features
+
+- 🔐 **Ed25519 signatures** — Every message is cryptographically signed
+- 🔒 **X25519 encryption** — Optional payload encryption (AES-256-GCM)
+- 📡 **Agent discovery** — Registry, DNS TXT, mDNS/Bonjour, .well-known
+- 🔄 **Reliability** — Retry with backoff, circuit breaker, persistent queue
+- 📨 **Delivery receipts** — sent/delivered/read confirmations
+- 🛡️ **Security hardening** — Rate limiting, nonce tracking, message expiry, blocklist
+- 🔑 **Key rotation** — Rotate keys with automatic announcement
+- 💀 **Dead letter queue** — Failed messages preserved for retry
+- 👤 **Human-in-the-loop** — Approval workflow for sensitive actions
+- 🧵 **Conversation threading** — State machine: proposed → negotiating → confirmed
+- 🛒 **Commerce** — Request quotes, make offers, accept/reject (always requires human approval)
+- 📦 **Zero dependencies** — Node.js built-ins only
+
+## Installation
 
 ```bash
-npx ai2ai
+npm install ai2ai-protocol
 ```
 
-## Quick Start
+Or clone directly:
+```bash
+git clone https://github.com/DarrenEdwards111/ai2ai-protocol.git
+```
 
-### 1. Set up your identity
+## Basic Usage
 
-```bash
-ai2ai init
+### Create an Agent
+
+```js
+const { AI2AI } = require('ai2ai-protocol/src/client');
+
+const agent = new AI2AI({
+  name: 'alice-agent',
+  humanName: 'Alice',
+  port: 18800,
+});
+
+// Listen for messages
+agent.on('message', (payload, from) => {
+  console.log(`Message from ${from.human}: ${payload.message}`);
+});
+
+// Listen for requests
+agent.on('request', (intent, payload, from) => {
+  console.log(`Request: ${intent} from ${from.human}`);
+});
+
+await agent.start();
 ```
 
-The setup wizard will ask your name, create an agent identity, generate Ed25519 keys, and save everything to `~/.ai2ai/`.
+### Send Messages
 
-### 2. Start your server
+```js
+// Add a contact
+agent.addContact('bob-agent', { endpoint: 'http://localhost:18801/ai2ai' });
 
-```bash
-ai2ai start
+// Send a message
+await agent.send('bob-agent', 'Hey Bob, are you free for lunch?');
+
+// Send a structured request
+await agent.request('bob-agent', 'schedule.meeting', {
+  subject: 'Team Lunch',
+  proposed_times: ['2026-02-20T12:00:00Z'],
+});
 ```
 
-This starts an HTTP server that listens for incoming AI2AI messages.
+## Discovery
 
-### 3. Connect to a friend
+### Registry
 
-```bash
-ai2ai connect http://friend.example.com:18800/ai2ai
+```js
+const { RegistryServer, RegistryClient } = require('ai2ai-protocol/src/registry');
+
+// Start a registry server
+const registry = new RegistryServer();
+await registry.start(18820);
+
+// Register your agent
+const agent = new AI2AI({
+  name: 'my-agent',
+  port: 18800,
+  registry: 'http://localhost:18820',
+});
+await agent.start();
+await agent.register();
+
+// Discover other agents
+const agents = await agent.discover({ capability: 'schedule.meeting' });
 ```
 
-This pings the remote agent, exchanges public keys, and saves them as a contact.
+### DNS TXT Record
 
-### 4. Send messages
+Add a DNS TXT record:
+```
+_ai2ai.yourdomain.com  TXT  "endpoint=https://your-server.com/ai2ai"
+```
 
-```bash
-# Simple message
-ai2ai send alex "Hey, are you free this weekend?"
+### Local Network (mDNS)
 
-# Scheduling (auto-detected)
-ai2ai send alex "dinner next Thursday at 7pm?"
+```js
+const { startLocalDiscovery } = require('ai2ai-protocol/src/registry');
 
-# Questions (auto-detected)
-ai2ai send alex "What time works for you?"
+const discovery = startLocalDiscovery((agent) => {
+  console.log(`Found: ${agent.agentId} at ${agent.endpoint}`);
+});
+
+discovery.announce('my-agent', 18800, 'Alice');
+discovery.query();
 ```
 
-AI2AI automatically detects message intent:
-- **Scheduling keywords** → `schedule.meeting` intent
-- **Questions** → `info.request` intent
-- **Everything else** → `message.relay` intent
+## Security Model
 
-### 5. Check for responses
+| Feature | Description |
+|---------|-------------|
+| **Ed25519 signatures** | Every message signed with sender's private key |
+| **X25519 encryption** | Optional ECDH + AES-256-GCM payload encryption |
+| **Nonce tracking** | Prevent replay attacks |
+| **Message expiry** | Reject messages older than configurable TTL (default 24h) |
+| **Rate limiting** | Per-agent request throttling |
+| **Agent blocklist** | Block specific agents |
+| **Key rotation** | Rotate keys with announcement to contacts |
+| **Verification cache** | Cache signature verification results |
+| **Trust levels** | none → known → trusted (commerce always requires approval) |
+
+## Integrations
+
+### OpenClaw
+
+```js
+const { createOpenClawAdapter } = require('ai2ai-protocol/src/integrations/openclaw');
+
+const adapter = createOpenClawAdapter({
+  agentName: 'my-agent',
+  onMessage: (payload, from) => console.log(from, payload),
+  notify: (text) => console.log(text),
+});
+await adapter.start();
+```
 
-```bash
-ai2ai pending
+### Webhooks
+
+```js
+const { createWebhookForwarder } = require('ai2ai-protocol/src/integrations/webhook');
+
+const webhook = createWebhookForwarder({
+  url: 'https://your-server.com/webhook',
+  secret: 'shared-secret',
+});
+
+agent.on('message', webhook.handler);
+```
+
+### Express Middleware
+
+```js
+const { ai2aiMiddleware } = require('ai2ai-protocol/src/integrations/express');
+
+app.use('/ai2ai', ai2aiMiddleware({
+  agentName: 'my-agent',
+  onMessage: (payload, from, envelope) => { ... },
+}));
+```
+
+## Protocol Specification
+
+See [SPEC.md](SPEC.md) for the full protocol specification including:
+- Message envelope format
+- All message types and intent types
+- Security model
+- Discovery mechanisms
+- Error codes
+- Versioning rules
+
+## API Reference
+
+### `AI2AI` (Production Client)
+
+```js
+const agent = new AI2AI({
+  name: string,           // Agent ID
+  humanName: string,      // Human operator name
+  port: number,           // Server port (default: 18800)
+  registry: string,       // Registry URL
+  timeout: number,        // Request timeout ms (default: 30000)
+  messageTTL: number,     // Message TTL ms (default: 86400000)
+  dataDir: string,        // Data directory
+});
+
+await agent.start(port?)          // Start HTTP server
+await agent.stop()                // Stop agent
+await agent.register(url?)        // Register with registry
+await agent.send(id, msg, opts?)  // Send message
+await agent.request(id, intent, payload, opts?)  // Send request
+await agent.discover(query?)      // Search registry
+agent.addContact(id, info)        // Add/update contact
+agent.getContact(id)              // Get contact
+agent.on('message', handler)      // Listen for messages
+agent.on('request', handler)      // Listen for requests
+agent.on('receipt', handler)      // Listen for receipts
 ```
 
-### 6. Approve or reject
+### `RegistryServer`
+
+```js
+const server = new RegistryServer({ staleTimeout: 120000 });
+await server.start(port)  // Start registry HTTP server
+server.stop()             // Stop server
+```
+
+### `RegistryClient`
+
+```js
+const client = new RegistryClient({ registryUrl, agentId });
+await client.register(agentInfo)  // Register
+await client.search(query?)       // Search agents
+await client.resolve(agentId)     // Resolve by ID
+await client.deregister()         // Remove registration
+await client.heartbeat()          // Send keepalive
+```
+
+### Reliability
+
+```js
+const { retryWithBackoff, CircuitBreaker, Deduplicator, DeliveryTracker, DeadLetterQueue, PersistentQueue } = require('ai2ai-protocol/src/reliability');
+```
+
+### Security
+
+```js
+const { KeyRotation, RateLimiter, NonceTracker, Blocklist, VerificationCache, isMessageExpired } = require('ai2ai-protocol/src/security');
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`basic-agent.js`](examples/basic-agent.js) — Minimal working agent
+- [`two-agents.js`](examples/two-agents.js) — Two agents chatting
+- [`with-registry.js`](examples/with-registry.js) — Agent discovery via registry
+- [`webhook-receiver.js`](examples/webhook-receiver.js) — Forward to webhooks
+- [`openclaw-skill.js`](examples/openclaw-skill.js) — OpenClaw integration
+
+## Tests
 
 ```bash
-ai2ai approve 1 "Thursday works for me!"
-ai2ai reject 2
+cd src
+node test.js      # Original 146 tests
+node test-v1.js   # New v1.0 tests (110 tests)
 ```
 
-## Commands
+## Contributing
 
-| 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 |
+1. Fork the repo
+2. Create a feature branch
+3. Run tests: `cd src && node test.js && node test-v1.js`
+4. Submit a PR
+
+## License
+
+Apache 2.0 — See [LICENSE](LICENSE)
+
+---
+
+<p align="center">
+  Built by <a href="https://mikoshi.co.uk">Mikoshi Ltd</a> 🦞
+</p>
+## 📋 Supported Intents
+
+| Intent | Description |
+|--------|-------------|
+| `schedule.meeting` | Propose times, negotiate, confirm |
+| `schedule.call` | Schedule a call |
+| `schedule.group` | Find time for multiple people |
+| `message.relay` | Pass a message to another human |
+| `info.request` | Ask for specific information |
+| `info.share` | Share information (one-way) |
+| `social.introduction` | Introduce two humans via agents |
+| `commerce.request` | Request a quote |
+| `commerce.offer` | Make an offer |
+| `commerce.accept` | Accept a deal |
+| `commerce.reject` | Decline a deal |
+
+Intents are extensible. Add your own.
+
+---
+
+## 🔒 Security
+
+- **Ed25519** message signing — every message is cryptographically signed
+- **X25519 + AES-256-GCM** end-to-end payload encryption
+- **Trust levels** — `none` → `known` → `trusted` (escalate over time)
+- **Human approval** — required for all actions by default
+- **Rate limiting** — per-agent, prevents spam
+- **Prompt injection protection** — structured JSON, not raw text execution
 
-## Protocol
+---
 
-AI2AI uses a simple JSON envelope over HTTP:
+## 📨 Message Format
+
+Every AI2AI message is a JSON envelope:
 
 ```json
 {
   "ai2ai": "0.1",
   "id": "uuid",
-  "timestamp": "2025-02-07T12:00:00.000Z",
+  "timestamp": "2026-02-07T19:00:00Z",
   "from": {
     "agent": "darren-assistant",
-    "node": "darren-assistant-node",
     "human": "Darren"
   },
   "to": {
     "agent": "alex-assistant",
-    "node": "alex-assistant-node",
     "human": "Alex"
   },
-  "conversation": "uuid",
+  "conversation": "conv-uuid",
   "type": "request",
-  "intent": "message.relay",
-  "payload": {
-    "message": "Hey, are you free Thursday?",
-    "urgency": "low",
-    "reply_requested": true
-  },
-  "signature": "base64-ed25519-signature"
+  "intent": "schedule.meeting",
+  "payload": { ... },
+  "requires_human_approval": true,
+  "signature": "ed25519-signature"
 }
 ```
 
-### Message Types
+Message types: `ping` | `request` | `response` | `confirm` | `reject` | `inform`
 
-- **`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
+## 🏗️ Architecture
 
-- `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
+```
+┌──────────────────────┐         ┌──────────────────────┐
+│   Darren's Setup     │         │    Alex's Setup       │
+│                      │         │                       │
+│  Human ←→ OpenClaw   │         │  Human ←→ OpenClaw    │
+│           ↕          │  HTTP   │           ↕           │
+│     AI2AI Server ────┼────────→┤     AI2AI Server      │
+│     (port 18810)     │←────────┼     (port 18811)      │
+│           ↕          │         │           ↕           │
+│  Keys | Trust | Log  │         │  Keys | Trust | Log   │
+└──────────────────────┘         └──────────────────────┘
+```
 
-## Security
+- **ai2ai-server.js** — HTTP endpoint, receives incoming messages
+- **ai2ai-client.js** — Sends outgoing messages
+- **ai2ai-handlers.js** — Intent processing (schedule, message, commerce, etc.)
+- **ai2ai-crypto.js** — Ed25519 signing & verification
+- **ai2ai-encryption.js** — X25519 + AES-256-GCM payload encryption
+- **ai2ai-trust.js** — Contact management & trust levels
+- **ai2ai-queue.js** — Disk-backed retry queue with exponential backoff
+- **ai2ai-discovery.js** — DNS, mDNS, .well-known agent discovery
+- **ai2ai-conversations.js** — Conversation state machine & expiry
+- **ai2ai-logger.js** — Structured audit logging
+- **ai2ai-bridge.js** — CLI tool for agents to use the protocol
+- **openclaw-integration.js** — Natural language command parsing
 
-- **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
+## 🎯 Real-World Scenarios
 
-All data is stored in `~/.ai2ai/`:
+Six runnable demos that prove AI2AI works for real multi-agent tasks. Each spins up local agents, completes a task end-to-end, and verifies the result.
+
+```bash
+# Run all demos
+node examples/demo-schedule.js      # Schedule Meeting
+node examples/demo-price-quote.js   # Price Comparison
+node examples/demo-research.js      # Collaborative Research
+node examples/demo-delegation.js    # Delegation Chain
+node examples/demo-info-exchange.js # Information Exchange
+node examples/demo-approval.js      # Human Approval Flow
+```
 
+### 1. 🗓️ Schedule Meeting
+Two agents negotiate a meeting time. Agent B checks its calendar and proposes slots, Agent A picks one, both confirm.
 ```
-~/.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
+  [Alice] Requesting meeting with Bob: "Project Sync"
+  [Bob] Checking calendar... proposing 3 available slots
+  [Alice] Picking: 2026-03-10T14:00
+  ✅ Both agents agreed: "Project Sync" at 2026-03-10T14:00
 ```
 
-## Discovery
+### 2. 💰 Price Comparison
+A buyer agent sends quote requests to two merchant agents, collects responses, and picks the cheapest.
+```
+  [Merchant B] responding £28
+  [Merchant C] responding £32
+  ✅ Buyer selected merchant-b at £28
+```
+
+### 3. 🔬 Collaborative Research
+A researcher agent asks a specialist for technical analysis. The specialist returns structured data with sources, which gets incorporated into a report.
+```
+  [Specialist] Responding with structured answer (confidence: 0.95)
+  [Researcher] Report compiled: "LoRa Modulation Technical Brief" with 3 sections
+  ✅ Report includes specialist contribution
+```
 
-Your agent serves a `.well-known/ai2ai.json` endpoint for web-based discovery:
+### 4. 🔗 Delegation Chain
+Manager → Coordinator → Worker. The coordinator can't fully complete the task, so it delegates a subtask to the worker, combines results, and returns to the manager.
+```
+  [Coordinator] delegating to worker
+  [Worker] Subtask complete
+  [Coordinator] Combining results and sending to manager
+  ✅ Delegation chain complete: manager ← coordinator ← worker
+```
 
+### 5. 📊 Information Exchange
+An agent requests sensor data twice, 2 seconds apart. Verifies both readings have different timestamps and values.
 ```
-GET http://localhost:18800/.well-known/ai2ai.json
+  [Sensor] Reading #1: 21.3°C at 2026-02-15T04:16:48Z
+  [Sensor] Reading #2: 21.6°C at 2026-02-15T04:16:50Z
+  ✅ Two readings received with different timestamps
 ```
 
-## Requirements
+### 6. 🔐 Human Approval Flow
+A purchase request for £500 triggers a human approval requirement (threshold: £100). Simulates the human approving before confirming.
+```
+  [Approver] ⚠️ Amount £500 exceeds £100 — human approval required
+  [Approver] 👤 Human reviewed and APPROVED
+  ✅ Human approval flow completed
+```
 
-- **Node.js 18+**
-- **Zero external dependencies** — Uses only Node.js built-in modules
+---
 
-## License
+## 🧪 Tests
+
+```bash
+cd src/
+node test.js
+```
+
+```
+✅ Passed: 146
+❌ Failed: 0
+⏭️  Skipped: 1 (mDNS requires multicast network)
+```
+
+---
+
+## 🗺️ Roadmap
+
+- [x] Protocol spec v0.1
+- [x] Core implementation (server, client, handlers)
+- [x] Ed25519 signing
+- [x] X25519 encryption
+- [x] Trust management
+- [x] Message queuing with retry
+- [x] 11 intent handlers
+- [x] Network discovery (DNS, mDNS, well-known)
+- [x] Conversation state machine
+- [x] OpenClaw skill integration
+- [x] Two-agent live demo
+- [x] 146 tests passing
+- [ ] Agent directory / registry
+- [ ] ActivityPub bridge
+- [ ] Multi-runtime SDKs (Python, Go)
+- [ ] Mobile agent support
+- [ ] Payment rails for commerce intent
+- [ ] Hosted hub (managed endpoints)
+
+---
+
+## 🤔 FAQ
+
+**Q: Does this need powerful models?**
+A: No. qwen2:7b (free, local) handles structured JSON negotiation perfectly. But it works just as well with cloud APIs like Claude, GPT, or Gemini if you prefer. The protocol is model-agnostic — it's just JSON.
+
+**Q: How is this different from MCP or ACP?**
+A: MCP connects agents to tools. ACP connects agents to services. AI2AI connects agents to *each other*, acting as human representatives. It's the social layer.
+
+**Q: What about bad actors?**
+A: Human-in-the-loop by default. Your agent never commits without your approval. Same model as email — you can receive spam, but you don't have to open it.
+
+**Q: Can non-OpenClaw agents use this?**
+A: Yes. The protocol is a JSON HTTP API. Any agent framework can implement it.
+
+---
+
+## 📄 License
+
+Apache 2.0 — Build on it. Fork it. Make it better. Patent protected.
+
+---
+
+## 🌍 The Vision
+
+Email gave humans a decentralised way to communicate.
+The web gave humans a decentralised way to publish.
+**AI2AI gives AI agents a decentralised way to act on behalf of humans.**
 
-MIT
+No company should own the protocol by which our digital representatives talk to each other.
 
-## Links
+The protocol is the product. The simpler it is, the more people build on it.
 
-- [Protocol Specification](https://github.com/DarrenEdwards111/ai2ai-protocol)
-- [Report Issues](https://github.com/DarrenEdwards111/ai2ai-protocol/issues)
+**Built in one night. Open forever. 🦞**

package/SKILL.md

@@ -0,0 +1,39 @@
+# AI2AI — Agent-to-Agent Communication Skill
+
+## Description
+Enables your OpenClaw agent to communicate with other AI agents on behalf of your human. Implements the AI2AI protocol for decentralized agent negotiation.
+
+## Commands
+
+The human can say:
+- **"Talk to [name]'s AI at [address]"** — Initiate handshake with another agent
+- **"Schedule [event] with [name]"** — Start a schedule negotiation
+- **"Send [name] a message via their AI"** — Relay a message through agents
+- **"Show AI2AI contacts"** — List known agents
+- **"AI2AI status"** — Show connection status and recent conversations
+
+## How It Works
+
+1. Human tells their agent what they want
+2. Agent formats an AI2AI message and sends it to the other agent's endpoint
+3. Other agent receives it, interprets it, and asks their human
+4. Response comes back
+5. Your agent tells you the result
+
+All communication is structured JSON. Humans approve everything (unless trust is elevated).
+
+## Files
+- `ai2ai-server.js` — HTTP endpoint that receives incoming AI2AI messages
+- `ai2ai-client.js` — Sends outgoing AI2AI messages  
+- `ai2ai-handlers.js` — Intent handlers (schedule, message, etc.)
+- `ai2ai-trust.js` — Trust management and approval flow
+- `ai2ai-crypto.js` — Ed25519 signing and verification
+- `contacts.json` — Known agents and trust levels
+- `conversations/` — Conversation history
+
+## Configuration
+Set in your OpenClaw config or via environment:
+- `AI2AI_PORT` — Port for incoming connections (default: 18800)
+- `AI2AI_AGENT_NAME` — Your agent's display name
+- `AI2AI_HUMAN_NAME` — Your human's display name
+- `AI2AI_TIMEZONE` — Your timezone