macro-agent 0.0.14 → 0.0.16

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

@@ -0,0 +1,282 @@
+---
+title: Simple Chat
+parent: Examples
+nav_order: 1
+description: "Basic agent-to-agent messaging example"
+---
+
+# Simple Chat
+{: .no_toc }
+
+A minimal example of agent-to-agent messaging.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+This example demonstrates:
+- Setting up a MAP server
+- Creating chat agents
+- Sending messages between agents
+- Subscribing to events
+
+---
+
+## Server
+
+```typescript
+// server.ts
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { WebSocketServer } from "ws";
+
+const server = new MAPServer({
+  name: "ChatServer",
+  version: "1.0.0",
+});
+
+// Log events
+server.on("agent.registered", (event) => {
+  console.log(`[Server] Agent joined: ${event.data.agent.name}`);
+});
+
+server.on("agent.unregistered", (event) => {
+  console.log(`[Server] Agent left: ${event.data.agentId}`);
+});
+
+server.on("message.sent", (event) => {
+  console.log(`[Server] Message from ${event.data.from} to ${event.data.to}`);
+});
+
+// WebSocket server
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", (ws) => {
+  const stream = websocketToStream(ws);
+  server.accept(stream).start();
+});
+
+console.log("Chat server running on ws://localhost:8080");
+
+// Helper function
+function websocketToStream(ws) {
+  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();
+      },
+    }),
+  };
+}
+```
+
+---
+
+## Chat Agent
+
+```typescript
+// chat-agent.ts
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+import * as readline from "readline";
+
+async function main() {
+  const agentName = process.argv[2] || "Agent";
+
+  // Connect to server
+  const ws = new WebSocket("ws://localhost:8080");
+  await new Promise((resolve) => ws.on("open", resolve));
+
+  const stream = websocketToStream(ws);
+
+  // Create agent
+  const agent = new AgentConnection(stream, {
+    name: agentName,
+    role: "chatter",
+  });
+
+  // Handle incoming messages
+  agent.onMessage((message) => {
+    console.log(`\n[${message.from}]: ${message.payload.text}`);
+    rl.prompt();
+  });
+
+  // Connect
+  const { agent: registered } = await agent.connect();
+  console.log(`Connected as ${registered.name} (${registered.id})`);
+
+  // List other agents
+  const { agents } = await agent.listAgents();
+  const others = agents.filter((a) => a.id !== registered.id);
+
+  if (others.length > 0) {
+    console.log("Other agents online:");
+    others.forEach((a) => console.log(`  - ${a.name} (${a.id})`));
+  } else {
+    console.log("No other agents online yet.");
+  }
+
+  // Set up readline for input
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log('\nType messages to send. Use "@name message" to send to specific agent.');
+  console.log('Type "list" to see online agents, "quit" to exit.\n');
+
+  rl.prompt();
+
+  rl.on("line", async (input) => {
+    const trimmed = input.trim();
+
+    if (trimmed === "quit") {
+      await agent.disconnect();
+      process.exit(0);
+    }
+
+    if (trimmed === "list") {
+      const { agents } = await agent.listAgents();
+      const others = agents.filter((a) => a.id !== registered.id);
+      console.log("Agents online:");
+      others.forEach((a) => console.log(`  - ${a.name} (${a.id})`));
+      rl.prompt();
+      return;
+    }
+
+    // Parse @name message format
+    const match = trimmed.match(/^@(\S+)\s+(.+)$/);
+    if (match) {
+      const [, targetName, text] = match;
+
+      // Find agent by name
+      const { agents } = await agent.listAgents();
+      const target = agents.find(
+        (a) => a.name.toLowerCase() === targetName.toLowerCase()
+      );
+
+      if (target) {
+        await agent.send({
+          to: { agentId: target.id },
+          payload: { text },
+        });
+        console.log(`[You → ${target.name}]: ${text}`);
+      } else {
+        console.log(`Agent "${targetName}" not found.`);
+      }
+    } else if (trimmed) {
+      // Broadcast to all agents
+      const { agents } = await agent.listAgents();
+      const others = agents.filter((a) => a.id !== registered.id);
+
+      for (const other of others) {
+        await agent.send({
+          to: { agentId: other.id },
+          payload: { text: trimmed },
+        });
+      }
+      console.log(`[You → all]: ${trimmed}`);
+    }
+
+    rl.prompt();
+  });
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Running the Example
+
+1. Start the server:
+
+```bash
+npx ts-node server.ts
+```
+
+2. In separate terminals, start multiple chat agents:
+
+```bash
+# Terminal 2
+npx ts-node chat-agent.ts Alice
+
+# Terminal 3
+npx ts-node chat-agent.ts Bob
+```
+
+3. Type messages in each terminal:
+
+```
+# Alice's terminal
+> Hello everyone!
+[You → all]: Hello everyone!
+
+# Bob's terminal
+[Alice]: Hello everyone!
+> @Alice Hi Alice!
+[You → Alice]: Hi Alice!
+```
+
+---
+
+## Key Concepts Demonstrated
+
+### Agent Registration
+
+```typescript
+const agent = new AgentConnection(stream, {
+  name: agentName,
+  role: "chatter",
+});
+
+await agent.connect();
+```
+
+### Message Handling
+
+```typescript
+agent.onMessage((message) => {
+  console.log(`[${message.from}]: ${message.payload.text}`);
+});
+```
+
+### Agent Discovery
+
+```typescript
+const { agents } = await agent.listAgents();
+```
+
+### Direct Messaging
+
+```typescript
+await agent.send({
+  to: { agentId: target.id },
+  payload: { text: "Hello!" },
+});
+```
+
+---
+
+## Next Steps
+
+- [Task Queue](./task-queue.html) - Work distribution with scopes
+- [Full Integration](./full-integration.html) - Complete application

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

@@ -0,0 +1,399 @@
+---
+title: Task Queue
+parent: Examples
+nav_order: 2
+description: "Work distribution with scopes"
+---
+
+# Task Queue
+{: .no_toc }
+
+Distribute work to agents using scopes.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+This example demonstrates:
+- Creating scopes for work distribution
+- Coordinator pattern for task assignment
+- Worker agents processing tasks
+- Client submitting and monitoring work
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    Client["Client<br/>(submits tasks)"]
+    Coord["Coordinator<br/>(assigns to workers)"]
+    W1["Worker 1<br/>(scope)"]
+    W2["Worker 2<br/>(scope)"]
+    W3["Worker 3<br/>(scope)"]
+
+    Client --> Coord
+    Coord --> W1
+    Coord --> W2
+    Coord --> W3
+```
+
+---
+
+## Server
+
+```typescript
+// server.ts
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { WebSocketServer } from "ws";
+
+const server = new MAPServer({
+  name: "TaskQueueServer",
+  version: "1.0.0",
+});
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", (ws) => {
+  server.accept(websocketToStream(ws)).start();
+});
+
+console.log("Task queue server running on ws://localhost:8080");
+```
+
+---
+
+## Coordinator
+
+```typescript
+// coordinator.ts
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+
+async function main() {
+  const ws = new WebSocket("ws://localhost:8080");
+  await new Promise((resolve) => ws.on("open", resolve));
+
+  const agent = new AgentConnection(websocketToStream(ws), {
+    name: "Coordinator",
+    role: "coordinator",
+  });
+
+  const { agent: registered } = await agent.connect();
+  console.log(`Coordinator registered: ${registered.id}`);
+
+  // Create task queue scope
+  const taskQueue = await agent.createScope({
+    name: "task-queue",
+    metadata: { type: "work-distribution" },
+  });
+  console.log(`Created task queue scope: ${taskQueue.id}`);
+
+  // Track workers and their state
+  const workers = new Map<string, { agentId: string; busy: boolean }>();
+  const pendingTasks: any[] = [];
+
+  // Subscribe to worker events
+  const subscription = await agent.subscribe({
+    eventTypes: ["scope.joined", "scope.left", "agent.unregistered"],
+  });
+
+  // Process events in background
+  (async () => {
+    for await (const event of subscription) {
+      if (event.type === "scope.joined" && event.data.scopeId === taskQueue.id) {
+        const { agentId } = event.data;
+        if (agentId !== registered.id) {
+          workers.set(agentId, { agentId, busy: false });
+          console.log(`Worker joined: ${agentId}`);
+          // Try to assign pending tasks
+          assignPendingTasks();
+        }
+      }
+
+      if (event.type === "scope.left" && event.data.scopeId === taskQueue.id) {
+        workers.delete(event.data.agentId);
+        console.log(`Worker left: ${event.data.agentId}`);
+      }
+
+      if (event.type === "agent.unregistered") {
+        workers.delete(event.data.agentId);
+      }
+    }
+  })();
+
+  // Handle incoming messages
+  agent.onMessage(async (message) => {
+    const { type } = message.payload;
+
+    if (type === "submit-task") {
+      const task = {
+        id: `task-${Date.now()}`,
+        ...message.payload.task,
+        submitter: message.from,
+      };
+
+      console.log(`Received task: ${task.id}`);
+
+      // Find available worker
+      const available = [...workers.values()].find((w) => !w.busy);
+
+      if (available) {
+        assignTask(task, available.agentId);
+      } else {
+        pendingTasks.push(task);
+        console.log(`Task ${task.id} queued (${pendingTasks.length} pending)`);
+      }
+    }
+
+    if (type === "task-complete") {
+      const { taskId, result, success } = message.payload;
+      const worker = workers.get(message.from);
+
+      if (worker) {
+        worker.busy = false;
+      }
+
+      console.log(`Task ${taskId} completed: ${success ? "success" : "failed"}`);
+
+      // Notify submitter
+      // ... forward result to original submitter
+
+      // Assign pending tasks
+      assignPendingTasks();
+    }
+  });
+
+  async function assignTask(task: any, workerId: string) {
+    const worker = workers.get(workerId);
+    if (worker) {
+      worker.busy = true;
+    }
+
+    await agent.send({
+      to: { agentId: workerId },
+      payload: {
+        type: "task",
+        task,
+      },
+    });
+
+    console.log(`Assigned task ${task.id} to ${workerId}`);
+  }
+
+  function assignPendingTasks() {
+    while (pendingTasks.length > 0) {
+      const available = [...workers.values()].find((w) => !w.busy);
+      if (!available) break;
+
+      const task = pendingTasks.shift()!;
+      assignTask(task, available.agentId);
+    }
+  }
+
+  console.log("Coordinator ready. Waiting for workers and tasks...");
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Worker
+
+```typescript
+// worker.ts
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+
+async function main() {
+  const workerId = process.argv[2] || `Worker-${Math.random().toString(36).slice(2, 6)}`;
+
+  const ws = new WebSocket("ws://localhost:8080");
+  await new Promise((resolve) => ws.on("open", resolve));
+
+  const agent = new AgentConnection(websocketToStream(ws), {
+    name: workerId,
+    role: "worker",
+  });
+
+  const { agent: registered } = await agent.connect();
+  console.log(`Worker registered: ${registered.id}`);
+
+  // Find and join task queue
+  const { scopes } = await agent.listScopes();
+  const taskQueue = scopes.find((s) => s.name === "task-queue");
+
+  if (taskQueue) {
+    await agent.joinScope(taskQueue.id);
+    console.log("Joined task queue");
+  } else {
+    console.log("Task queue not found. Waiting for coordinator...");
+
+    // Subscribe to scope creation
+    const sub = await agent.subscribe({ eventTypes: ["scope.created"] });
+    for await (const event of sub) {
+      if (event.data.scope.name === "task-queue") {
+        await agent.joinScope(event.data.scope.id);
+        console.log("Joined task queue");
+        await sub.unsubscribe();
+        break;
+      }
+    }
+  }
+
+  // Handle tasks
+  agent.onMessage(async (message) => {
+    if (message.payload.type === "task") {
+      const { task } = message.payload;
+      console.log(`Processing task: ${task.id}`);
+
+      await agent.update({ state: "busy" });
+
+      try {
+        // Simulate work
+        await new Promise((r) => setTimeout(r, 2000 + Math.random() * 3000));
+
+        // Send result
+        await agent.send({
+          to: { agentId: message.from },
+          payload: {
+            type: "task-complete",
+            taskId: task.id,
+            success: true,
+            result: { processed: true },
+          },
+        });
+
+        console.log(`Completed task: ${task.id}`);
+      } catch (error) {
+        await agent.send({
+          to: { agentId: message.from },
+          payload: {
+            type: "task-complete",
+            taskId: task.id,
+            success: false,
+            error: error.message,
+          },
+        });
+      }
+
+      await agent.update({ state: "running" });
+    }
+  });
+
+  console.log("Worker ready. Waiting for tasks...");
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Client
+
+```typescript
+// client.ts
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+
+async function main() {
+  const ws = new WebSocket("ws://localhost:8080");
+  await new Promise((resolve) => ws.on("open", resolve));
+
+  const client = new ClientConnection(websocketToStream(ws), {
+    name: "TaskSubmitter",
+  });
+
+  await client.connect();
+  console.log("Connected to task queue server");
+
+  // Find coordinator
+  const { agents } = await client.listAgents({ role: "coordinator" });
+
+  if (agents.length === 0) {
+    console.log("No coordinator found. Please start the coordinator first.");
+    return;
+  }
+
+  const coordinator = agents[0];
+  console.log(`Found coordinator: ${coordinator.id}`);
+
+  // Submit some tasks
+  for (let i = 1; i <= 5; i++) {
+    await client.send({
+      to: { agentId: coordinator.id },
+      payload: {
+        type: "submit-task",
+        task: {
+          name: `Task ${i}`,
+          data: { value: i * 10 },
+        },
+      },
+    });
+
+    console.log(`Submitted task ${i}`);
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  console.log("All tasks submitted. Monitoring...");
+
+  // Subscribe to events
+  const subscription = await client.subscribe({
+    eventTypes: ["agent.*"],
+  });
+
+  for await (const event of subscription) {
+    console.log(`Event: ${event.type}`);
+  }
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Running the Example
+
+1. Start the server:
+```bash
+npx ts-node server.ts
+```
+
+2. Start the coordinator:
+```bash
+npx ts-node coordinator.ts
+```
+
+3. Start some workers:
+```bash
+npx ts-node worker.ts Worker1
+npx ts-node worker.ts Worker2
+```
+
+4. Submit tasks:
+```bash
+npx ts-node client.ts
+```
+
+---
+
+## Key Concepts Demonstrated
+
+- **Scopes** for grouping related agents
+- **Coordinator pattern** for task distribution
+- **Worker pool** with busy/available tracking
+- **Message passing** for task assignment and completion
+
+---
+
+## Next Steps
+
+- [Full Integration](./full-integration.html) - Complete application with all concepts