macro-agent 0.1.1 → 0.1.3

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

@@ -1,98 +0,0 @@
----
-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

@@ -1,219 +0,0 @@
----
-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

@@ -1,172 +0,0 @@
----
-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

@@ -1,237 +0,0 @@
----
-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)