multi-agent-protocol 0.0.3 → 0.0.6

package/docs/agentic-mesh-integration-draft.md

@@ -0,0 +1,459 @@
+# Implementation Guide: Agentic-Mesh Transport for MAP SDK
+ 
+This guide describes how to implement agentic-mesh as a transport option for the Multi-Agent Protocol (MAP) TypeScript SDK.
+ 
+## Overview
+ 
+**Goal:** Allow MAP SDK clients to connect over agentic-mesh encrypted tunnels (Nebula/Tailscale/Headscale).
+ 
+**Architecture:**
+ 
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                 multi-agent-protocol/ts-sdk                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────┐                                               │
+│  │ MAPClient   │  Standard MAP SDK client                      │
+│  └──────┬──────┘                                               │
+│         │                                                       │
+│         ▼                                                       │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │              Transport Layer (pluggable)                 │   │
+│  ├─────────────────────────────────────────────────────────┤   │
+│  │ WebSocketTransport │ StdioTransport │ AgenticMeshTransport │
+│  │                    │                │      (NEW)           │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                              │                  │
+└──────────────────────────────────────────────┼──────────────────┘
+                                               │
+                                               ▼
+                              ┌────────────────────────────┐
+                              │ agentic-mesh TransportAdapter │
+                              │ (Nebula/Tailscale tunnels)   │
+                              └────────────────────────────┘
+```
+ 
+---
+ 
+## Step 1: Create Transport Interface
+ 
+**File:** `multi-agent-protocol/ts-sdk/src/transports/types.ts`
+ 
+Define the base transport interface that all transports implement:
+ 
+```typescript
+import type { MAPFrame } from '../types'
+ 
+/**
+ * Transport interface for MAP protocol communication.
+ */
+export interface Transport {
+  /** Connect to the remote endpoint */
+  connect(): Promise<void>
+ 
+  /** Disconnect from the remote endpoint */
+  disconnect(): Promise<void>
+ 
+  /** Send a frame to the remote endpoint */
+  send(frame: MAPFrame): Promise<void>
+ 
+  /** Async iterator for receiving frames */
+  receive(): AsyncIterable<MAPFrame>
+ 
+  /** Whether currently connected */
+  readonly isConnected: boolean
+}
+ 
+/**
+ * Base transport configuration.
+ */
+export interface TransportConfig {
+  /** Connection timeout in milliseconds */
+  timeout?: number
+}
+```
+ 
+---
+ 
+## Step 2: Create Agentic-Mesh Transport
+ 
+**File:** `multi-agent-protocol/ts-sdk/src/transports/agentic-mesh.ts`
+ 
+### Reusable Components from agentic-mesh
+ 
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `TunnelStream` | [`src/map/stream/tunnel-stream.ts:90`](../src/map/stream/tunnel-stream.ts#L90) | NDJSON framing over transport |
+| `createNdjsonFramer` | [`src/map/stream/tunnel-stream.ts:16`](../src/map/stream/tunnel-stream.ts#L16) | JSON encode/decode utilities |
+| `TransportAdapter` | [`src/transports/types.ts`](../src/transports/types.ts) | Nebula/Tailscale abstraction |
+| `MapFrame` | [`src/map/types.ts:685`](../src/map/types.ts#L685) | Request/Response/Notification types |
+ 
+### Implementation
+ 
+```typescript
+import type { Transport, TransportConfig } from './types'
+import type { MAPFrame } from '../types'
+ 
+// Import from agentic-mesh
+import { TunnelStream } from 'agentic-mesh/map/stream'
+import type { TransportAdapter, PeerEndpoint } from 'agentic-mesh/transports'
+ 
+/**
+ * Configuration for agentic-mesh transport.
+ */
+export interface AgenticMeshTransportConfig extends TransportConfig {
+  /** The agentic-mesh transport adapter (Nebula, Tailscale, Headscale) */
+  transport: TransportAdapter
+ 
+  /** Remote peer to connect to */
+  peer: PeerEndpoint
+ 
+  /** Local peer ID for identification */
+  localPeerId: string
+}
+ 
+/**
+ * MAP transport over agentic-mesh encrypted tunnels.
+ */
+export class AgenticMeshTransport implements Transport {
+  private stream: TunnelStream | null = null
+  private readonly config: AgenticMeshTransportConfig
+ 
+  constructor(config: AgenticMeshTransportConfig) {
+    this.config = config
+  }
+ 
+  get isConnected(): boolean {
+    return this.stream?.isOpen ?? false
+  }
+ 
+  async connect(): Promise<void> {
+    // Start underlying transport if needed
+    if (!this.config.transport.isRunning) {
+      await this.config.transport.start()
+    }
+ 
+    // Create tunnel stream over the mesh transport
+    this.stream = new TunnelStream({
+      transport: this.config.transport,
+      peerId: this.config.peer.id,
+      streamId: `map-${this.config.localPeerId}-${Date.now()}`,
+    })
+ 
+    await this.stream.open()
+  }
+ 
+  async disconnect(): Promise<void> {
+    if (this.stream) {
+      await this.stream.close()
+      this.stream = null
+    }
+  }
+ 
+  async send(frame: MAPFrame): Promise<void> {
+    if (!this.stream?.isOpen) {
+      throw new Error('Transport not connected')
+    }
+    await this.stream.write(frame)
+  }
+ 
+  async *receive(): AsyncIterable<MAPFrame> {
+    if (!this.stream) return
+ 
+    for await (const frame of this.stream) {
+      yield frame
+    }
+  }
+}
+ 
+/**
+ * Create an agentic-mesh transport.
+ */
+export function createAgenticMeshTransport(
+  config: AgenticMeshTransportConfig
+): AgenticMeshTransport {
+  return new AgenticMeshTransport(config)
+}
+```
+ 
+---
+ 
+## Step 3: Export Transport Module
+ 
+**File:** `multi-agent-protocol/ts-sdk/src/transports/index.ts`
+ 
+```typescript
+export * from './types'
+export * from './agentic-mesh'
+ 
+// Re-export other transports
+export * from './websocket'
+export * from './stdio'
+```
+ 
+---
+ 
+## Step 4: Wire into MAP Client
+ 
+**File:** `multi-agent-protocol/ts-sdk/src/client.ts`
+ 
+Modify the MAP client to accept a transport:
+ 
+```typescript
+import type { Transport } from './transports'
+import type {
+  ConnectParams,
+  ConnectResult,
+  MAPFrame,
+  MAPRequestFrame,
+  MAPResponseFrame,
+} from './types'
+ 
+export class MAPClient {
+  private readonly transport: Transport
+  private readonly pendingRequests = new Map<
+    string | number,
+    { resolve: (result: unknown) => void; reject: (error: Error) => void }
+  >()
+  private nextRequestId = 1
+ 
+  constructor(transport: Transport) {
+    this.transport = transport
+  }
+ 
+  async connect(params: ConnectParams): Promise<ConnectResult> {
+    // Connect transport
+    await this.transport.connect()
+ 
+    // Start receiving frames in background
+    this.startReceiving()
+ 
+    // Send MAP connect request
+    return this.request('map/connect', params)
+  }
+ 
+  async disconnect(): Promise<void> {
+    await this.request('map/disconnect', {})
+    await this.transport.disconnect()
+  }
+ 
+  /**
+   * Send a JSON-RPC request and wait for response.
+   */
+  async request<T>(method: string, params: unknown): Promise<T> {
+    const id = this.nextRequestId++
+ 
+    const frame: MAPRequestFrame = {
+      jsonrpc: '2.0',
+      id,
+      method,
+      params,
+    }
+ 
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve: resolve as any, reject })
+      this.transport.send(frame).catch(reject)
+    })
+  }
+ 
+  /**
+   * Start receiving frames from transport.
+   */
+  private async startReceiving(): Promise<void> {
+    try {
+      for await (const frame of this.transport.receive()) {
+        this.handleFrame(frame)
+      }
+    } catch (error) {
+      // Handle disconnect
+      console.error('Transport error:', error)
+    }
+  }
+ 
+  /**
+   * Handle incoming frame.
+   */
+  private handleFrame(frame: MAPFrame): void {
+    // Response frame
+    if ('id' in frame && ('result' in frame || 'error' in frame)) {
+      const pending = this.pendingRequests.get(frame.id)
+      if (pending) {
+        this.pendingRequests.delete(frame.id)
+        if ('error' in frame) {
+          pending.reject(new Error(frame.error.message))
+        } else {
+          pending.resolve(frame.result)
+        }
+      }
+      return
+    }
+ 
+    // Notification frame
+    if ('method' in frame && !('id' in frame)) {
+      this.handleNotification(frame)
+    }
+  }
+ 
+  private handleNotification(frame: MAPNotificationFrame): void {
+    // Handle events, messages, etc.
+    // Emit to subscribers
+  }
+}
+```
+ 
+---
+ 
+## Step 5: Usage Example
+ 
+```typescript
+import { MAPClient } from '@anthropic/multi-agent-protocol'
+import { AgenticMeshTransport } from '@anthropic/multi-agent-protocol/transports/agentic-mesh'
+import { createNebulaTransport } from 'agentic-mesh'
+ 
+async function main() {
+  // 1. Create the encrypted mesh transport
+  const nebulaTransport = createNebulaTransport({
+    configPath: '/etc/nebula/config.yml',
+    certPath: '/etc/nebula/host.crt',
+    keyPath: '/etc/nebula/host.key',
+  })
+ 
+  // 2. Create MAP transport wrapper
+  const transport = new AgenticMeshTransport({
+    transport: nebulaTransport,
+    peer: {
+      id: 'map-server',
+      nebulaIp: '10.0.0.1',
+      port: 4242
+    },
+    localPeerId: 'my-client',
+  })
+ 
+  // 3. Create MAP client with transport
+  const client = new MAPClient(transport)
+ 
+  // 4. Connect using standard MAP protocol
+  const session = await client.connect({
+    participantType: 'client',
+    name: 'My Dashboard',
+    capabilities: {
+      observation: { canObserve: true, canQuery: true },
+    },
+  })
+ 
+  console.log('Connected:', session.sessionId)
+ 
+  // 5. Use MAP SDK normally
+  const agents = await client.request('map/agents.list', {})
+  console.log('Agents:', agents)
+ 
+  // 6. Subscribe to events
+  const subscription = await client.request('map/subscribe', {
+    filter: { eventTypes: ['agent_registered', 'agent_state_changed'] },
+  })
+ 
+  // 7. Disconnect when done
+  await client.disconnect()
+}
+ 
+main().catch(console.error)
+```
+ 
+---
+ 
+## Key Code Pointers
+ 
+### agentic-mesh Source Files
+ 
+| What | File | Line |
+|------|------|------|
+| NDJSON framing | [`src/map/stream/tunnel-stream.ts`](../src/map/stream/tunnel-stream.ts) | 16-67 |
+| TunnelStream class | [`src/map/stream/tunnel-stream.ts`](../src/map/stream/tunnel-stream.ts) | 90-200 |
+| MapFrame types | [`src/map/types.ts`](../src/map/types.ts) | 682-702 |
+| JSON-RPC handling | [`src/map/connection/base.ts`](../src/map/connection/base.ts) | 1-150 |
+| TransportAdapter interface | [`src/transports/types.ts`](../src/transports/types.ts) | 1-50 |
+| Nebula transport | [`src/transports/nebula-transport.ts`](../src/transports/nebula-transport.ts) | - |
+| Tailscale transport | [`src/transports/tailscale-transport.ts`](../src/transports/tailscale-transport.ts) | - |
+| PeerConnection (reference) | [`src/map/connection/peer.ts`](../src/map/connection/peer.ts) | - |
+ 
+### Existing Exports
+ 
+agentic-mesh already exports what's needed:
+ 
+```typescript
+// src/map/index.ts
+export * from './stream'      // TunnelStream, createNdjsonFramer
+export * from './types'       // MapFrame, all MAP types
+export * from './connection'  // BaseConnection
+ 
+// src/index.ts
+export * from './map'         // All MAP exports
+```
+ 
+---
+ 
+## Files to Create
+ 
+| File | Purpose |
+|------|---------|
+| `ts-sdk/src/transports/types.ts` | Transport interface definition |
+| `ts-sdk/src/transports/agentic-mesh.ts` | Agentic-mesh transport implementation |
+| `ts-sdk/src/transports/index.ts` | Export all transports |
+ 
+## Files to Modify
+ 
+| File | Change |
+|------|--------|
+| `ts-sdk/src/client.ts` | Accept transport in constructor |
+| `ts-sdk/package.json` | Add `agentic-mesh` as optional peer dependency |
+ 
+---
+ 
+## Testing
+ 
+Create tests for the transport:
+ 
+```typescript
+// ts-sdk/tests/transports/agentic-mesh.test.ts
+ 
+import { describe, it, expect, vi } from 'vitest'
+import { AgenticMeshTransport } from '../../src/transports/agentic-mesh'
+ 
+describe('AgenticMeshTransport', () => {
+  it('should connect via tunnel stream', async () => {
+    const mockTransport = {
+      isRunning: false,
+      start: vi.fn(),
+      connect: vi.fn(),
+    }
+ 
+    const transport = new AgenticMeshTransport({
+      transport: mockTransport as any,
+      peer: { id: 'test-peer', nebulaIp: '10.0.0.1', port: 4242 },
+      localPeerId: 'local',
+    })
+ 
+    await transport.connect()
+    expect(mockTransport.start).toHaveBeenCalled()
+  })
+ 
+  it('should send frames via stream', async () => {
+    // Test frame sending
+  })
+ 
+  it('should receive frames via async iterator', async () => {
+    // Test frame receiving
+  })
+})
+```
+ 
+---
+ 
+## Summary
+ 
+1. **Define transport interface** - Standard interface for all MAP transports
+2. **Implement AgenticMeshTransport** - Wraps TunnelStream for MAP frames
+3. **Export from ts-sdk** - Make transport available to SDK users
+4. **Wire into MAPClient** - Accept transport in constructor
+5. **Use normally** - Standard MAP SDK API over encrypted mesh tunnels

package/docs/git-transport-draft.md

@@ -0,0 +1,251 @@
+# Git Transport Integration Guide
+ 
+This guide explains how git transport is integrated with agentic-mesh and how to use it from the MAP side.
+ 
+## Architecture Overview
+ 
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ MAP Client/Agent                                                 │
+│                                                                  │
+│  Option A: CLI                    Option B: Programmatic         │
+│  ─────────────────                ───────────────────────        │
+│  git fetch mesh://peer-b/         client.sync('peer-b')          │
+│         │                                │                       │
+│         ▼                                ▼                       │
+│  git-remote-mesh helper           GitSyncClient                  │
+│         │                                │                       │
+│         └────────────┬───────────────────┘                       │
+│                      ▼                                           │
+│         GitTransportService (HTTP :3456)                         │
+│                      │                                           │
+│                      ▼                                           │
+│         MeshPeer.sendGitMessage()                                │
+│                      │                                           │
+│                      ▼                                           │
+│         PeerConnection.sendGitMessage()                          │
+└──────────────────────┬───────────────────────────────────────────┘
+                       │ MAP Protocol (NDJSON over transport)
+                       ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ Remote Peer                                                      │
+│                                                                  │
+│         PeerConnection receives 'git/message'                    │
+│                      │                                           │
+│                      ▼                                           │
+│         MeshPeer.git:message event                               │
+│                      │                                           │
+│                      ▼                                           │
+│         GitTransportService.handleRemoteMessage()                │
+│                      │                                           │
+│                      ▼                                           │
+│         GitProtocolHandler (spawns native git)                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+ 
+## Key Integration Points
+ 
+### 1. Enable Git in MeshPeer Config
+ 
+**File:** `src/map/types.ts` (lines 45-52)
+ 
+```typescript
+const peer = createMeshPeer({
+  peerId: 'my-agent',
+  git: {
+    enabled: true,
+    httpPort: 3456,           // Port for git-remote-mesh helper
+    repoPath: '/path/to/repo', // Default repo path
+  },
+})
+```
+ 
+### 2. Git Service Lifecycle
+ 
+**File:** `src/map/mesh-peer.ts`
+ 
+The git service is initialized in the constructor (lines 74-84) and started/stopped with the peer:
+ 
+```typescript
+// Start (line 170-173)
+if (this.gitService) {
+  this.gitService.setPeerSender(this.createGitPeerSender())
+  await this.gitService.start()
+}
+ 
+// Stop (line 195-197)
+if (this.gitService) {
+  await this.gitService.stop()
+}
+```
+ 
+### 3. Message Routing
+ 
+**File:** `src/map/mesh-peer.ts` (lines 225-241)
+ 
+Git messages are sent via `createGitPeerSender()`:
+ 
+```typescript
+private createGitPeerSender(): PeerMessageSender {
+  return {
+    sendToPeer: async (peerId: string, message: AnyGitMessage) => {
+      const conn = this.peerConnections.get(peerId)
+      if (!conn) throw new Error(`No connection to peer ${peerId}`)
+      await conn.sendGitMessage(message)
+    },
+    isConnected: (peerId: string) => this.peerConnections.has(peerId),
+  }
+}
+```
+ 
+### 4. Receiving Git Messages
+ 
+**File:** `src/map/mesh-peer.ts` (lines 354-359)
+ 
+When a peer connection receives a git message, it's forwarded to the git service:
+ 
+```typescript
+conn.on('git:message', (gitMessage) => {
+  if (this.gitService) {
+    this.gitService.handleRemoteMessage(peerId, gitMessage)
+  }
+})
+```
+ 
+### 5. PeerConnection Git Support
+ 
+**File:** `src/map/connection/peer.ts`
+ 
+Git messages use a dedicated method type:
+ 
+```typescript
+const GIT_MESSAGE_METHOD = 'git/message' as const  // line 32
+ 
+// Send (lines 224-232)
+async sendGitMessage(message: AnyGitMessage): Promise<void> {
+  await this.stream.notify(GIT_MESSAGE_METHOD, message)
+}
+ 
+// Receive (line 296)
+this.emit('git:message', message)
+```
+ 
+## Usage from MAP Side
+ 
+### Option A: Using GitSyncClient (Recommended)
+ 
+```typescript
+import { createMeshPeer } from 'agentic-mesh/map'
+ 
+const peer = createMeshPeer({
+  peerId: 'agent-a',
+  git: { enabled: true, repoPath: '/my/repo' },
+})
+ 
+await peer.start()
+await peer.connectToPeer('agent-b', endpoint)
+ 
+// Create sync client
+const client = peer.git!.createSyncClient('/my/repo')
+ 
+// Sync operations
+await client.sync('agent-b', { branch: 'main', bidirectional: true })
+await client.pull('agent-b', 'main')
+await client.push('agent-b', 'feature-branch')
+await client.clone('agent-b', '/new/repo')
+```
+ 
+### Option B: Using Standard Git Commands
+ 
+Requires `git-remote-mesh` in PATH:
+ 
+```bash
+# Install globally
+npm install -g agentic-mesh
+ 
+# Or add to PATH
+export PATH="$PATH:./node_modules/.bin"
+ 
+# Use mesh:// URLs
+git remote add agent-b mesh://agent-b-id/
+git fetch agent-b
+git push agent-b main
+```
+ 
+### Option C: Direct Protocol Access
+ 
+For low-level control:
+ 
+```typescript
+// List refs from remote peer
+const refs = await peer.git!.protocolHandler.listRefs({
+  refPrefix: 'refs/heads/',
+})
+ 
+// Fetch pack data
+const pack = await peer.git!.protocolHandler.uploadPack({
+  wants: ['abc123...'],
+  haves: ['def456...'],
+})
+```
+ 
+## Wire Protocol Messages
+ 
+**File:** `src/git/types.ts`
+ 
+| Message Type | Direction | Purpose |
+|--------------|-----------|---------|
+| `git/list-refs` | Request/Response | List remote refs |
+| `git/upload-pack` | Request/Response | Fetch pack data |
+| `git/receive-pack` | Request/Response | Push pack data |
+| `git/pack-stream` | Notification | Start binary stream |
+| `git/pack-chunk` | Notification | Stream chunk |
+| `git/pack-complete` | Notification | End stream |
+| `git/error` | Response | Error response |
+ 
+## Binary Streaming
+ 
+**File:** `src/git/transport-service.ts` (lines 451-465, 501-545)
+ 
+Large packs (>1MB by default) are automatically streamed:
+ 
+```typescript
+// Config (lines 67-71)
+streaming: {
+  enabled: true,
+  threshold: 1024 * 1024,  // 1MB
+  chunkSize: 64 * 1024,    // 64KB chunks
+}
+```
+ 
+Flow:
+1. Response sent with `streaming: true`, no `packData`
+2. `git/pack-stream` message initiates transfer
+3. `git/pack-chunk` messages send data (base64 encoded)
+4. `git/pack-complete` finalizes with checksum
+ 
+## File Reference
+ 
+| File | Purpose |
+|------|---------|
+| `src/git/types.ts` | Type definitions, message types |
+| `src/git/protocol-handler.ts` | Native git operations |
+| `src/git/transport-service.ts` | HTTP server + peer routing |
+| `src/git/sync-client.ts` | High-level sync API |
+| `src/git/pack-streamer.ts` | Binary streaming |
+| `src/git/git-remote-mesh.ts` | CLI remote helper |
+| `src/map/mesh-peer.ts` | MeshPeer integration |
+| `src/map/connection/peer.ts` | Git message handling |
+ 
+## Testing
+ 
+```bash
+# Unit tests
+npm test -- git-transport
+ 
+# Integration tests (requires git)
+npm test -- tests/integration/git-transport
+ 
+# All tests
+npm test
+```