macro-agent 0.0.13 → 0.0.15

package/references/multi-agent-protocol/docs-site/getting-started/index.md

@@ -0,0 +1,98 @@
+---
+title: Getting Started
+nav_order: 2
+has_children: true
+description: "Get started with the Multi-Agent Protocol SDK"
+---
+
+# Getting Started
+
+Get a MAP server and connected agents running in minutes.
+{: .fs-6 .fw-300 }
+
+---
+
+## What You'll Learn
+
+1. **[Overview](./overview.html)** - Understand what MAP is and when to use it
+2. **[Quickstart](./quickstart.html)** - Run a server, agent, and client in 5 minutes
+3. **[Installation](./installation.html)** - Install and configure the SDK
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** - MAP SDK requires Node.js 18 or later
+- **npm or yarn** - For package management
+- **TypeScript** (recommended) - The SDK is written in TypeScript with full type support
+
+---
+
+## Quick Installation
+
+```bash
+npm install @multi-agent-protocol/sdk
+```
+
+---
+
+## Minimal Example
+
+Here's the simplest possible MAP setup:
+
+**Server:**
+```typescript
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { WebSocketServer } from "ws";
+
+const server = new MAPServer({ name: "MyServer" });
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", (ws) => {
+  const stream = websocketToStream(ws);
+  server.accept(stream).start();
+});
+
+console.log("MAP Server running on ws://localhost:8080");
+```
+
+**Agent:**
+```typescript
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+
+const agent = new AgentConnection(stream, {
+  name: "Worker",
+  role: "processor"
+});
+
+const { agent: registered } = await agent.connect();
+console.log(`Agent registered: ${registered.id}`);
+
+agent.onMessage((message) => {
+  console.log("Received:", message.payload);
+});
+```
+
+**Client:**
+```typescript
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+
+const client = new ClientConnection(stream, { name: "Dashboard" });
+await client.connect();
+
+// List all agents
+const { agents } = await client.listAgents();
+console.log(`Found ${agents.length} agents`);
+
+// Subscribe to events
+const subscription = await client.subscribe({ eventTypes: ["agent.*"] });
+for await (const event of subscription) {
+  console.log("Event:", event.type);
+}
+```
+
+---
+
+## Next Steps
+
+Ready to dive deeper? Start with the [Quickstart Guide](./quickstart.html) to build a complete working example.

package/references/multi-agent-protocol/docs-site/getting-started/installation.md

@@ -0,0 +1,219 @@
+---
+title: Installation
+parent: Getting Started
+nav_order: 3
+description: "Install and configure the MAP SDK"
+---
+
+# Installation
+
+Install the Multi-Agent Protocol SDK in your project.
+{: .fs-6 .fw-300 }
+
+---
+
+## Requirements
+
+- **Node.js 18+** - The SDK uses modern JavaScript features
+- **TypeScript 5.0+** (recommended) - Full type support included
+
+---
+
+## Package Installation
+
+### npm
+
+```bash
+npm install @multi-agent-protocol/sdk
+```
+
+### yarn
+
+```bash
+yarn add @multi-agent-protocol/sdk
+```
+
+### pnpm
+
+```bash
+pnpm add @multi-agent-protocol/sdk
+```
+
+---
+
+## Package Exports
+
+The SDK provides multiple entry points:
+
+```typescript
+// Main exports (connections, types)
+import {
+  ClientConnection,
+  AgentConnection,
+  GatewayConnection
+} from "@multi-agent-protocol/sdk";
+
+// Server components
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+
+// Building blocks for custom servers
+import {
+  EventBusImpl,
+  AgentRegistryImpl,
+  ScopeManagerImpl,
+  SubscriptionManagerImpl,
+} from "@multi-agent-protocol/sdk/server";
+
+// Type definitions
+import type {
+  Agent,
+  Message,
+  Event,
+  Subscription,
+} from "@multi-agent-protocol/sdk";
+```
+
+---
+
+## TypeScript Configuration
+
+For the best experience, use these TypeScript settings:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+---
+
+## Transport Dependencies
+
+The SDK is transport-agnostic. Install additional packages based on your needs:
+
+### WebSocket (Browser & Node.js)
+
+```bash
+npm install ws
+```
+
+```typescript
+import WebSocket from "ws";
+
+const ws = new WebSocket("ws://localhost:8080");
+const stream = websocketToStream(ws);
+```
+
+### HTTP + Server-Sent Events
+
+For HTTP-based transports, no additional dependencies are needed:
+
+```typescript
+// Use fetch + EventSource for HTTP transport
+const stream = httpToStream("http://localhost:8080/map");
+```
+
+### Node.js Streams (stdio)
+
+For stdio-based communication (CLI tools, child processes):
+
+```typescript
+import { stdioToStream } from "@multi-agent-protocol/sdk";
+
+const stream = stdioToStream(process.stdin, process.stdout);
+```
+
+---
+
+## Peer Dependencies
+
+### Optional: agentic-mesh
+
+For mesh networking and peer-to-peer connectivity:
+
+```bash
+npm install agentic-mesh
+```
+
+```typescript
+import { MeshTransport } from "@multi-agent-protocol/sdk/mesh";
+
+const transport = new MeshTransport({
+  networkId: "my-mesh-network"
+});
+```
+
+---
+
+## Environment Configuration
+
+### Server Configuration
+
+```typescript
+const server = new MAPServer({
+  // Server identity
+  name: "MyMAPServer",
+  version: "1.0.0",
+
+  // Optional: custom configuration
+  maxConnections: 1000,
+  heartbeatInterval: 30000,
+});
+```
+
+### Connection Configuration
+
+```typescript
+const client = new ClientConnection(stream, {
+  // Client identity
+  name: "Dashboard",
+
+  // Optional: reconnection settings
+  reconnect: true,
+  reconnectMaxAttempts: 5,
+  reconnectBaseDelay: 1000,
+});
+```
+
+---
+
+## Verifying Installation
+
+Create a simple test file to verify everything works:
+
+```typescript
+// test-install.ts
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { ClientConnection, AgentConnection } from "@multi-agent-protocol/sdk";
+
+console.log("MAP SDK imported successfully!");
+
+// Create a server instance
+const server = new MAPServer({ name: "TestServer" });
+console.log("Server created:", server);
+
+console.log("Installation verified!");
+```
+
+Run it:
+
+```bash
+npx ts-node test-install.ts
+```
+
+---
+
+## Next Steps
+
+Now that you have the SDK installed:
+
+1. **[Quickstart](./quickstart.html)** - Build your first MAP application
+2. **[Server Guide](/multi-agent-protocol/sdk/guides/server.html)** - Configure your server
+3. **[Examples](/multi-agent-protocol/examples/)** - See complete working examples

package/references/multi-agent-protocol/docs-site/getting-started/overview.md

@@ -0,0 +1,172 @@
+---
+title: Overview
+parent: Getting Started
+nav_order: 1
+description: "Understand the Multi-Agent Protocol and when to use it"
+---
+
+# Overview
+
+The Multi-Agent Protocol (MAP) provides a standardized way to observe, coordinate, and route messages within multi-agent AI systems.
+{: .fs-6 .fw-300 }
+
+---
+
+## What is MAP?
+
+MAP is a **JSON-RPC based protocol** designed for multi-agent systems. Unlike protocols designed for single-agent interaction or peer-to-peer agent delegation, MAP provides a **window into** a multi-agent system with visibility into its internal structure, agent relationships, and message flows.
+
+### MAP Provides
+
+- **Observation** - Clients can subscribe to events and watch agent activity
+- **Coordination** - Agents can form hierarchies, join scopes, and collaborate
+- **Routing** - Messages flow through scopes and across federated systems
+- **Transparency** - Full visibility into the system's internal state
+
+---
+
+## Protocol Landscape
+
+Understanding where MAP fits in the AI protocol ecosystem:
+
+| Protocol | Relationship | Visibility | Primary Use |
+|:---------|:-------------|:-----------|:------------|
+| **MCP** | Agent → Tool | N/A | Tool invocation |
+| **ACP** | Client → Agent | Opaque | Single-agent sessions |
+| **A2A** | Agent → Agent (peer) | Opaque | Cross-org delegation |
+| **MAP** | Client → System | **Transparent** | Internal orchestration |
+
+### When to Use MAP
+
+{: .highlight }
+Use MAP when you need **visibility and coordination** across multiple agents working together.
+
+**Good fits for MAP:**
+- Multi-agent orchestration systems
+- Agent dashboards and monitoring
+- Systems requiring audit trails
+- Collaborative AI workflows
+- Agent marketplaces and registries
+
+**Not ideal for MAP:**
+- Simple single-agent chat applications (use ACP)
+- Pure tool invocation (use MCP)
+- Cross-organization agent handoffs (use A2A)
+
+---
+
+## Core Concepts
+
+### Three Participant Types
+
+MAP defines three types of participants:
+
+| Type | Role | Capabilities |
+|:-----|:-----|:-------------|
+| **Agent** | Worker that processes tasks | Register, join scopes, send/receive messages |
+| **Client** | Observer and requester | Subscribe to events, query state, send messages |
+| **Gateway** | Federation bridge | Route between MAP systems |
+
+### Key Components
+
+A MAP server manages these internal components:
+
+- **EventBus** - Central event dispatcher for all system events
+- **AgentRegistry** - Tracks registered agents and their state
+- **ScopeManager** - Manages logical groupings (rooms, topics, projects)
+- **SessionManager** - Handles connections and reconnection
+- **SubscriptionManager** - Event filtering and delivery
+- **MessageRouter** - Routes messages to agents and scopes
+
+### Protocol Methods
+
+The protocol defines **27 methods** across three tiers:
+
+**Core (Required):**
+- `map/connect` - Establish connection
+- `map/disconnect` - Clean shutdown
+- `map/send` - Send messages
+- `map/subscribe` - Subscribe to events
+- `map/unsubscribe` - Cancel subscriptions
+- `map/agents/list` - List registered agents
+- `map/agents/get` - Get agent details
+
+**Structure (Recommended):**
+- Agent lifecycle: `register`, `spawn`, `unregister`, `update`, `stop`, `suspend`, `resume`
+- Scope management: `scopes/create`, `scopes/join`, `scopes/leave`
+- Structure queries: `scopes/list`, `agents/children`
+
+**Extensions (Optional):**
+- Federation: `federation/connect`, `federation/route`
+- Session management: `sessions/list`, `sessions/get`
+- Steering: `map/inject`
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Server["MAP Server"]
+        EventBus["EventBus"]
+        Agents["Agents"]
+        Scopes["Scopes"]
+        Sessions["Sessions"]
+        Subs["Subscriptions"]
+        Messages["Messages"]
+    end
+
+    Agent1["Agent"] --> Server
+    Client["Client"] --> Server
+    Agent2["Agent"] --> Server
+```
+
+---
+
+## Key Features
+
+### Real-time Streaming
+
+Subscribe to events with backpressure support:
+
+```typescript
+const subscription = await client.subscribe({
+  eventTypes: ["agent.*", "message.*"],
+  agents: ["agent-123"]
+});
+
+for await (const event of subscription) {
+  console.log(event.type, event.data);
+}
+```
+
+### 4-Layer Permission System
+
+Control visibility and actions at multiple levels:
+
+1. **System** - Global server configuration
+2. **Participant** - Per-connection permissions
+3. **Scope** - Namespace-level access
+4. **Agent** - Individual agent preferences
+
+### Federation
+
+Connect multiple MAP systems:
+
+```typescript
+// Gateway connects two MAP systems
+const gateway = await GatewayConnection.connect(localServer, {
+  name: "federation-gateway",
+  remoteSystem: "https://remote-map.example.com"
+});
+```
+
+### Causal Ordering
+
+Events are delivered in dependency order, ensuring consistent state across clients.
+
+---
+
+## Next Steps
+
+Ready to start building? Continue to the [Quickstart Guide](./quickstart.html).

package/references/multi-agent-protocol/docs-site/getting-started/quickstart.md

@@ -0,0 +1,237 @@
+---
+title: Quickstart
+parent: Getting Started
+nav_order: 2
+description: "Run a MAP server, agent, and client in 5 minutes"
+---
+
+# Quickstart
+
+Get a MAP server and connected agent running in 5 minutes.
+{: .fs-6 .fw-300 }
+
+---
+
+## Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+---
+
+## Installation
+
+```bash
+npm install @multi-agent-protocol/sdk ws
+```
+
+---
+
+## Step 1: Create a Server
+
+The `MAPServer` class provides a complete MAP-compliant server with sensible defaults.
+
+Create `server.ts`:
+
+```typescript
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { WebSocketServer } from "ws";
+
+// Create the MAP server
+const server = new MAPServer({
+  name: "MyMAPServer",
+  version: "1.0.0",
+});
+
+// Create WebSocket server
+const wss = new WebSocketServer({ port: 8080 });
+
+// Accept connections
+wss.on("connection", (ws) => {
+  console.log("New connection");
+
+  // Convert WebSocket to a bidirectional stream
+  const stream = websocketToStream(ws);
+
+  // Accept and start processing
+  const router = server.accept(stream);
+  router.start();
+});
+
+console.log("MAP Server listening on ws://localhost:8080");
+
+// Helper to convert WebSocket to stream
+function websocketToStream(ws: WebSocket) {
+  return {
+    readable: new ReadableStream({
+      start(controller) {
+        ws.on("message", (data) => {
+          controller.enqueue(JSON.parse(data.toString()));
+        });
+        ws.on("close", () => controller.close());
+        ws.on("error", (err) => controller.error(err));
+      },
+    }),
+    writable: new WritableStream({
+      write(message) {
+        ws.send(JSON.stringify(message));
+      },
+      close() {
+        ws.close();
+      },
+    }),
+  };
+}
+```
+
+---
+
+## Step 2: Create an Agent
+
+Agents are workers that register with the server and process messages.
+
+Create `agent.ts`:
+
+```typescript
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+
+async function main() {
+  // Connect to server
+  const ws = new WebSocket("ws://localhost:8080");
+  await new Promise((resolve) => ws.on("open", resolve));
+
+  const stream = websocketToStream(ws);
+
+  // Create agent connection
+  const agent = new AgentConnection(stream, {
+    name: "WorkerAgent",
+    role: "processor",
+  });
+
+  // Connect and register
+  const { agent: registered } = await agent.connect();
+  console.log(`Agent registered: ${registered.id}`);
+
+  // Handle incoming messages
+  agent.onMessage((message) => {
+    console.log(`Received message from ${message.from}:`);
+    console.log(message.payload);
+  });
+
+  // Keep running
+  console.log("Agent running. Press Ctrl+C to exit.");
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Step 3: Create a Client
+
+Clients observe the system and can send messages to agents.
+
+Create `client.ts`:
+
+```typescript
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+
+async function main() {
+  // Connect to server
+  const ws = new WebSocket("ws://localhost:8080");
+  await new Promise((resolve) => ws.on("open", resolve));
+
+  const stream = websocketToStream(ws);
+
+  // Create client connection
+  const client = new ClientConnection(stream, {
+    name: "Dashboard",
+  });
+
+  // Connect
+  const result = await client.connect();
+  console.log(`Connected to ${result.systemInfo?.name}`);
+
+  // List all agents
+  const { agents } = await client.listAgents();
+  console.log(`Found ${agents.length} agents:`);
+  agents.forEach((a) => console.log(`  - ${a.name} (${a.id})`));
+
+  // Subscribe to agent events
+  const subscription = await client.subscribe({
+    eventTypes: ["agent.registered", "agent.unregistered"],
+  });
+
+  console.log("Watching for agent events...");
+
+  for await (const event of subscription) {
+    console.log(`Event: ${event.type}`);
+  }
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Step 4: Run It
+
+Start each component in a separate terminal:
+
+```bash
+# Terminal 1: Start server
+npx ts-node server.ts
+
+# Terminal 2: Start agent
+npx ts-node agent.ts
+
+# Terminal 3: Start client
+npx ts-node client.ts
+```
+
+You should see:
+
+1. Server starts and listens on port 8080
+2. Agent connects and registers
+3. Client connects, lists the agent, and receives the registration event
+
+---
+
+## What Just Happened?
+
+1. **Server** created building blocks (EventBus, AgentRegistry, etc.) and wired them together
+2. **Agent** connected, sent `map/connect`, then `map/agents/register`
+3. **Server** registered the agent and emitted `agent.registered` event
+4. **Client** connected, queried agents with `map/agents/list`, subscribed to events
+5. **EventBus** delivered the registration event to the client's subscription
+
+---
+
+## Common Issues
+
+### "Connection refused"
+
+Make sure the server is running before starting agents or clients.
+
+### "Method not found"
+
+Check that you're using the correct SDK version on both server and client.
+
+### Events not received
+
+Verify your subscription filter matches the event types being emitted. Use `eventTypes: ["*"]` to receive all events during debugging.
+
+### Agent not appearing in list
+
+The agent must call `connect()` which automatically registers it. Check for connection errors.
+
+---
+
+## Next Steps
+
+- **[Server Quickstart](/multi-agent-protocol/sdk/guides/server.html)** - Learn MAPServer configuration options
+- **[Agent Integration](/multi-agent-protocol/sdk/guides/agent.html)** - Build more sophisticated agents
+- **[Client Integration](/multi-agent-protocol/sdk/guides/client.html)** - Build observability dashboards
+- **[Transports](/multi-agent-protocol/sdk/guides/transports.html)** - Use different transports (stdio, HTTP, custom)