macro-agent 0.1.1 → 0.1.3

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

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

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