macro-agent 0.0.13 → 0.0.15

package/references/multi-agent-protocol/docs-site/examples/full-integration.md

@@ -0,0 +1,510 @@
+---
+title: Full Integration
+parent: Examples
+nav_order: 3
+description: "Complete end-to-end application"
+---
+
+# Full Integration
+{: .no_toc }
+
+A complete application demonstrating all MAP concepts.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+This example brings together all MAP concepts:
+- Server with authentication
+- Multiple agent types with roles
+- Scopes for collaboration
+- Client dashboard with real-time updates
+- Error handling and reconnection
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Server["MAP Server"]
+        EventBus["EventBus"]
+        Agents["Agents"]
+        Scopes["Scopes"]
+        Subs["Subscriptions"]
+    end
+
+    Dashboard["Dashboard<br/>(Client)"] --> Server
+    Coordinator["Coordinator<br/>(Agent)"] --> Server
+    Workers["Workers<br/>(Agents)"] --> Server
+```
+
+---
+
+## Server with Authentication
+
+```typescript
+// server.ts
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { WebSocketServer } from "ws";
+import jwt from "jsonwebtoken";
+
+const JWT_SECRET = process.env.JWT_SECRET || "development-secret";
+
+const server = new MAPServer({
+  name: "ProductionServer",
+  version: "1.0.0",
+
+  auth: {
+    required: process.env.NODE_ENV === "production",
+    methods: ["bearer", "none"],
+
+    validate: async (credentials) => {
+      if (credentials.method === "none") {
+        return {
+          success: true,
+          principal: { id: "anonymous", claims: { role: "guest" } },
+        };
+      }
+
+      if (credentials.method === "bearer") {
+        try {
+          const payload = jwt.verify(credentials.credential!, JWT_SECRET);
+          return {
+            success: true,
+            principal: {
+              id: payload.sub as string,
+              claims: payload,
+            },
+          };
+        } catch {
+          return {
+            success: false,
+            error: { code: "invalid_credentials", message: "Invalid token" },
+          };
+        }
+      }
+
+      return { success: false, error: { code: "method_not_supported", message: "Unknown method" } };
+    },
+  },
+
+  middleware: [
+    // Logging
+    async (method, params, ctx, next) => {
+      const start = Date.now();
+      console.log(`[${ctx.session.id}] → ${method}`);
+      const result = await next();
+      console.log(`[${ctx.session.id}] ← ${method} (${Date.now() - start}ms)`);
+      return result;
+    },
+  ],
+
+  additionalHandlers: {
+    "stats/overview": async () => ({
+      agents: server.agents.list().length,
+      scopes: server.scopes.list().length,
+      connections: server.connections.size,
+      uptime: process.uptime(),
+    }),
+  },
+});
+
+// Track statistics
+let messagesProcessed = 0;
+server.on("message.sent", () => messagesProcessed++);
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", (ws, req) => {
+  console.log(`New connection from ${req.socket.remoteAddress}`);
+  server.accept(websocketToStream(ws)).start();
+});
+
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  console.log("Shutting down...");
+  await server.close({ timeout: 10000 });
+  wss.close();
+  process.exit(0);
+});
+
+console.log("Server running on ws://localhost:8080");
+```
+
+---
+
+## Coordinator Agent
+
+```typescript
+// coordinator.ts
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+
+interface Task {
+  id: string;
+  type: string;
+  data: unknown;
+  submitter: string;
+  assignedTo?: string;
+  status: "pending" | "assigned" | "completed" | "failed";
+  createdAt: number;
+}
+
+async function main() {
+  const agent = new AgentConnection(await connect(), {
+    name: "Coordinator",
+    role: "coordinator",
+    metadata: {
+      version: "1.0.0",
+      capabilities: ["task-routing", "load-balancing"],
+    },
+    reconnect: { enabled: true },
+  });
+
+  await agent.connect();
+  console.log("Coordinator started");
+
+  // Create work scope
+  const workScope = await agent.createScope({
+    name: "work-queue",
+    metadata: { maxWorkers: 10 },
+  });
+
+  // State
+  const workers = new Map<string, { busy: boolean; tasksCompleted: number }>();
+  const tasks = new Map<string, Task>();
+  const pendingQueue: string[] = [];
+
+  // Subscribe to events
+  const sub = await agent.subscribe({
+    eventTypes: ["scope.joined", "scope.left", "agent.unregistered"],
+  });
+
+  // Event processing
+  (async () => {
+    for await (const event of sub) {
+      handleEvent(event);
+    }
+  })();
+
+  function handleEvent(event: any) {
+    switch (event.type) {
+      case "scope.joined":
+        if (event.data.scopeId === workScope.id && event.data.agentId !== agent.id) {
+          workers.set(event.data.agentId, { busy: false, tasksCompleted: 0 });
+          console.log(`Worker joined: ${event.data.agentId}`);
+          processQueue();
+        }
+        break;
+
+      case "scope.left":
+      case "agent.unregistered":
+        if (workers.has(event.data.agentId)) {
+          workers.delete(event.data.agentId);
+          console.log(`Worker left: ${event.data.agentId}`);
+          // Reassign their tasks
+          reassignTasks(event.data.agentId);
+        }
+        break;
+    }
+  }
+
+  // Message handling
+  agent.onMessage(async (message) => {
+    const { type } = message.payload;
+
+    switch (type) {
+      case "submit-task":
+        handleSubmitTask(message);
+        break;
+
+      case "task-result":
+        handleTaskResult(message);
+        break;
+
+      case "get-status":
+        await sendStatus(message.from);
+        break;
+    }
+  });
+
+  function handleSubmitTask(message: any) {
+    const task: Task = {
+      id: `task-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      type: message.payload.taskType,
+      data: message.payload.data,
+      submitter: message.from,
+      status: "pending",
+      createdAt: Date.now(),
+    };
+
+    tasks.set(task.id, task);
+    pendingQueue.push(task.id);
+    console.log(`Task ${task.id} queued`);
+
+    processQueue();
+  }
+
+  function handleTaskResult(message: any) {
+    const { taskId, success, result, error } = message.payload;
+    const task = tasks.get(taskId);
+
+    if (task) {
+      task.status = success ? "completed" : "failed";
+
+      const worker = workers.get(message.from);
+      if (worker) {
+        worker.busy = false;
+        if (success) worker.tasksCompleted++;
+      }
+
+      // Notify submitter
+      agent.send({
+        to: { agentId: task.submitter },
+        payload: {
+          type: "task-completed",
+          taskId,
+          success,
+          result,
+          error,
+        },
+      });
+
+      console.log(`Task ${taskId}: ${task.status}`);
+      processQueue();
+    }
+  }
+
+  function processQueue() {
+    while (pendingQueue.length > 0) {
+      const availableWorker = [...workers.entries()].find(([, w]) => !w.busy);
+      if (!availableWorker) break;
+
+      const taskId = pendingQueue.shift()!;
+      const task = tasks.get(taskId)!;
+      const [workerId, worker] = availableWorker;
+
+      task.status = "assigned";
+      task.assignedTo = workerId;
+      worker.busy = true;
+
+      agent.send({
+        to: { agentId: workerId },
+        payload: { type: "task", task },
+      });
+
+      console.log(`Task ${taskId} assigned to ${workerId}`);
+    }
+  }
+
+  function reassignTasks(workerId: string) {
+    for (const [taskId, task] of tasks) {
+      if (task.assignedTo === workerId && task.status === "assigned") {
+        task.status = "pending";
+        task.assignedTo = undefined;
+        pendingQueue.unshift(taskId);
+        console.log(`Task ${taskId} requeued`);
+      }
+    }
+    processQueue();
+  }
+
+  async function sendStatus(to: string) {
+    await agent.send({
+      to: { agentId: to },
+      payload: {
+        type: "status",
+        workers: workers.size,
+        pendingTasks: pendingQueue.length,
+        totalTasks: tasks.size,
+      },
+    });
+  }
+
+  console.log(`Work scope created: ${workScope.id}`);
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Worker Agent
+
+```typescript
+// worker.ts
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+
+async function main() {
+  const name = process.argv[2] || `Worker-${Date.now()}`;
+
+  const agent = new AgentConnection(await connect(), {
+    name,
+    role: "worker",
+    metadata: { capabilities: ["compute"] },
+    reconnect: { enabled: true },
+  });
+
+  const { agent: registered } = await agent.connect();
+  console.log(`Worker ${name} started (${registered.id})`);
+
+  // Find and join work scope
+  const { scopes } = await agent.listScopes();
+  const workScope = scopes.find((s) => s.name === "work-queue");
+
+  if (workScope) {
+    await agent.joinScope(workScope.id);
+    console.log("Joined work queue");
+  } else {
+    // Wait for scope to be created
+    const sub = await agent.subscribe({ eventTypes: ["scope.created"] });
+    for await (const event of sub) {
+      if (event.data.scope.name === "work-queue") {
+        await agent.joinScope(event.data.scope.id);
+        console.log("Joined work queue");
+        await sub.unsubscribe();
+        break;
+      }
+    }
+  }
+
+  // Handle tasks
+  agent.onMessage(async (message) => {
+    if (message.payload.type === "task") {
+      const { task } = message.payload;
+      console.log(`Processing: ${task.id} (${task.type})`);
+
+      await agent.update({ state: "busy", metadata: { currentTask: task.id } });
+
+      try {
+        // Simulate work
+        const result = await processTask(task);
+
+        await agent.send({
+          to: { agentId: message.from },
+          payload: { type: "task-result", taskId: task.id, success: true, result },
+        });
+
+        console.log(`Completed: ${task.id}`);
+      } catch (error) {
+        await agent.send({
+          to: { agentId: message.from },
+          payload: { type: "task-result", taskId: task.id, success: false, error: error.message },
+        });
+
+        console.log(`Failed: ${task.id} - ${error.message}`);
+      }
+
+      await agent.update({ state: "running", metadata: { currentTask: null } });
+    }
+  });
+
+  console.log("Ready for work");
+}
+
+async function processTask(task: any) {
+  // Simulate processing time
+  await new Promise((r) => setTimeout(r, 1000 + Math.random() * 2000));
+  return { processed: true, timestamp: Date.now() };
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Dashboard Client
+
+```typescript
+// dashboard.ts
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+
+async function main() {
+  const client = new ClientConnection(await connect(), {
+    name: "Dashboard",
+    reconnect: { enabled: true },
+  });
+
+  client.onStateChange((state) => {
+    console.log(`Connection: ${state}`);
+  });
+
+  const { systemInfo } = await client.connect();
+  console.log(`Connected to ${systemInfo?.name}`);
+
+  // Initial state
+  await refreshState();
+
+  // Subscribe to all events
+  const sub = await client.subscribe({ eventTypes: ["*"] });
+
+  console.log("\nMonitoring events...\n");
+
+  for await (const event of sub) {
+    console.log(`[${new Date().toISOString()}] ${event.type}`);
+
+    if (event.type.startsWith("agent.")) {
+      await refreshState();
+    }
+  }
+
+  async function refreshState() {
+    const { agents } = await client.listAgents();
+    const { scopes } = await client.listScopes();
+
+    console.log("\n--- System State ---");
+    console.log(`Agents: ${agents.length}`);
+    agents.forEach((a) => {
+      console.log(`  ${a.name} (${a.role}) - ${a.state}`);
+    });
+    console.log(`Scopes: ${scopes.length}`);
+    scopes.forEach((s) => {
+      console.log(`  ${s.name}`);
+    });
+    console.log("-------------------\n");
+  }
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Running the Full Example
+
+```bash
+# Terminal 1: Server
+npx ts-node server.ts
+
+# Terminal 2: Coordinator
+npx ts-node coordinator.ts
+
+# Terminal 3-5: Workers
+npx ts-node worker.ts Worker1
+npx ts-node worker.ts Worker2
+npx ts-node worker.ts Worker3
+
+# Terminal 6: Dashboard
+npx ts-node dashboard.ts
+```
+
+---
+
+## Concepts Demonstrated
+
+- **Authentication** with JWT tokens
+- **Middleware** for logging
+- **Custom handlers** for stats
+- **Scopes** for work distribution
+- **Coordinator pattern** with load balancing
+- **Worker pool** with task reassignment
+- **Real-time dashboard** with event subscription
+- **Reconnection** handling
+- **Graceful shutdown**

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

@@ -0,0 +1,138 @@
+---
+title: Examples
+nav_order: 5
+has_children: true
+description: "Complete working examples"
+---
+
+# Examples
+
+Complete working examples demonstrating MAP patterns.
+{: .fs-6 .fw-300 }
+
+---
+
+## Available Examples
+
+| Example | Description | Concepts |
+|:--------|:------------|:---------|
+| [Simple Chat](./simple-chat.html) | Basic agent-to-agent messaging | Agents, messaging |
+| [Task Queue](./task-queue.html) | Work distribution with scopes | Scopes, coordination |
+| [Full Integration](./full-integration.html) | Complete end-to-end application | All concepts |
+
+---
+
+## Running Examples
+
+All examples are available in the SDK repository:
+
+```bash
+git clone https://github.com/multi-agent-protocol/multi-agent-protocol.git
+cd multi-agent-protocol/ts-sdk/examples
+npm install
+```
+
+Each example has its own README with specific instructions.
+
+---
+
+## Example Patterns
+
+### Pattern 1: Hub and Spoke
+
+One coordinator, multiple workers:
+
+```mermaid
+flowchart TB
+    Client["Client"]
+    Coord["Coordinator"]
+    W1["Worker 1"]
+    W2["Worker 2"]
+    W3["Worker 3"]
+
+    Client --> Coord
+    Coord --> W1
+    Coord --> W2
+    Coord --> W3
+```
+
+### Pattern 2: Peer Collaboration
+
+Agents collaborate through shared scopes:
+
+```mermaid
+flowchart TB
+    subgraph ScopeA["Scope A"]
+        A1["Agent 1"]
+        A2["Agent 2"]
+    end
+
+    subgraph ScopeB["Scope B"]
+        A2b["Agent 2"]
+        A3["Agent 3"]
+    end
+
+    A2 -.->|"shared"| A2b
+```
+
+### Pattern 3: Pipeline
+
+Sequential processing through agents:
+
+```mermaid
+flowchart LR
+    Input["Input"] --> Agent1["Agent 1"]
+    Agent1 --> Agent2["Agent 2"]
+    Agent2 --> Agent3["Agent 3"]
+    Agent3 --> Output["Output"]
+```
+
+---
+
+## Quick Start Template
+
+Here's a minimal template to start a new MAP application:
+
+```typescript
+// server.ts
+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) => {
+  server.accept(websocketToStream(ws)).start();
+});
+
+console.log("Server running on ws://localhost:8080");
+```
+
+```typescript
+// agent.ts
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+
+const agent = new AgentConnection(stream, {
+  name: "MyAgent",
+  role: "worker",
+});
+
+await agent.connect();
+
+agent.onMessage(async (message) => {
+  // Handle messages
+});
+```
+
+```typescript
+// client.ts
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+
+const client = new ClientConnection(stream, { name: "MyClient" });
+await client.connect();
+
+const subscription = await client.subscribe({ eventTypes: ["*"] });
+for await (const event of subscription) {
+  // Handle events
+}
+```