macro-agent 0.0.13 → 0.0.15

package/references/multi-agent-protocol/docs-site/sdk/guides/transports.md

@@ -0,0 +1,363 @@
+---
+title: Transports
+parent: Guides
+grand_parent: SDK
+nav_order: 4
+description: "WebSocket, stdio, and custom transport adapters"
+---
+
+# Transports
+{: .no_toc }
+
+Connect via WebSocket, stdio, or custom transports.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+MAP is transport-agnostic. The SDK provides adapters for common transports and interfaces for building custom ones.
+
+---
+
+## Stream Interface
+
+All transports implement the bidirectional stream interface:
+
+```typescript
+interface Stream {
+  readable: ReadableStream<JSONRPCMessage>;
+  writable: WritableStream<JSONRPCMessage>;
+}
+```
+
+---
+
+## WebSocket Transport
+
+The most common transport for remote connections.
+
+### Server Side
+
+```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();
+});
+
+function websocketToStream(ws: WebSocket): Stream {
+  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();
+      },
+    }),
+  };
+}
+```
+
+### Client Side
+
+```typescript
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+import WebSocket from "ws";
+
+const ws = new WebSocket("ws://localhost:8080");
+await new Promise((resolve) => ws.on("open", resolve));
+
+const stream = websocketToStream(ws);
+const client = new ClientConnection(stream, { name: "Dashboard" });
+await client.connect();
+```
+
+---
+
+## Stdio Transport
+
+For subprocess agents (like Claude Code's Task tool pattern).
+
+### Parent Process (Server)
+
+```typescript
+import { spawn } from "child_process";
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+
+const server = new MAPServer({ name: "ParentServer" });
+
+// Spawn child agent process
+const child = spawn("node", ["agent.js"], {
+  stdio: ["pipe", "pipe", "inherit"],
+});
+
+const stream = stdioToStream(child.stdin, child.stdout);
+server.accept(stream).start();
+
+function stdioToStream(stdin: Writable, stdout: Readable): Stream {
+  let buffer = "";
+
+  return {
+    readable: new ReadableStream({
+      start(controller) {
+        stdout.on("data", (chunk) => {
+          buffer += chunk.toString();
+          const lines = buffer.split("\n");
+          buffer = lines.pop() || "";
+
+          for (const line of lines) {
+            if (line.trim()) {
+              controller.enqueue(JSON.parse(line));
+            }
+          }
+        });
+        stdout.on("end", () => controller.close());
+        stdout.on("error", (err) => controller.error(err));
+      },
+    }),
+    writable: new WritableStream({
+      write(message) {
+        stdin.write(JSON.stringify(message) + "\n");
+      },
+      close() {
+        stdin.end();
+      },
+    }),
+  };
+}
+```
+
+### Child Process (Agent)
+
+```typescript
+// agent.js
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+
+const stream = stdioToStream(process.stdin, process.stdout);
+const agent = new AgentConnection(stream, {
+  name: "ChildAgent",
+  role: "worker",
+});
+
+await agent.connect();
+
+agent.onMessage((message) => {
+  // Process messages from parent
+});
+```
+
+---
+
+## In-Process Transport
+
+For testing or co-located components.
+
+```typescript
+import { createStreamPair } from "@multi-agent-protocol/sdk/stream";
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+
+// Create a connected pair of streams
+const [clientStream, serverStream] = createStreamPair();
+
+// Server uses one end
+const server = new MAPServer({ name: "TestServer" });
+server.accept(serverStream).start();
+
+// Client uses the other end
+const client = new ClientConnection(clientStream, { name: "TestClient" });
+await client.connect();
+```
+
+---
+
+## HTTP + SSE Transport
+
+For stateless clients and environments that don't support WebSockets.
+
+### Server Side
+
+```typescript
+import express from "express";
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+
+const app = express();
+const server = new MAPServer({ name: "HTTPServer" });
+
+// Store active SSE connections
+const sseConnections = new Map<string, Response>();
+
+// RPC endpoint
+app.post("/map/rpc", express.json(), async (req, res) => {
+  const sessionId = req.headers["x-session-id"] as string;
+  const result = await server.handleRequest(req.body, sessionId);
+  res.json(result);
+});
+
+// SSE endpoint for events
+app.get("/map/events", (req, res) => {
+  const sessionId = req.query.sessionId as string;
+
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+
+  sseConnections.set(sessionId, res);
+
+  req.on("close", () => {
+    sseConnections.delete(sessionId);
+  });
+});
+
+// Deliver events via SSE
+server.on("*", (event) => {
+  for (const [sessionId, res] of sseConnections) {
+    res.write(`event: map.event\n`);
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+  }
+});
+
+app.listen(8080);
+```
+
+### Client Side
+
+```typescript
+function httpToStream(baseUrl: string, sessionId: string): Stream {
+  const eventSource = new EventSource(
+    `${baseUrl}/map/events?sessionId=${sessionId}`
+  );
+
+  return {
+    readable: new ReadableStream({
+      start(controller) {
+        eventSource.addEventListener("map.event", (e) => {
+          controller.enqueue(JSON.parse(e.data));
+        });
+        eventSource.onerror = () => controller.close();
+      },
+    }),
+    writable: new WritableStream({
+      async write(message) {
+        await fetch(`${baseUrl}/map/rpc`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Session-Id": sessionId,
+          },
+          body: JSON.stringify(message),
+        });
+      },
+    }),
+  };
+}
+```
+
+---
+
+## Custom Transports
+
+Implement any transport by providing a Stream:
+
+```typescript
+interface CustomTransportOptions {
+  // Your transport-specific options
+}
+
+function createCustomTransport(options: CustomTransportOptions): Stream {
+  return {
+    readable: new ReadableStream({
+      start(controller) {
+        // Set up your transport's incoming message handling
+        // Call controller.enqueue(message) for each message
+        // Call controller.close() when connection ends
+        // Call controller.error(err) on errors
+      },
+    }),
+    writable: new WritableStream({
+      write(message) {
+        // Send message over your transport
+      },
+      close() {
+        // Clean up your transport
+      },
+    }),
+  };
+}
+```
+
+### Example: Redis Pub/Sub Transport
+
+```typescript
+import Redis from "ioredis";
+
+function redisToStream(channelIn: string, channelOut: string): Stream {
+  const subscriber = new Redis();
+  const publisher = new Redis();
+
+  return {
+    readable: new ReadableStream({
+      async start(controller) {
+        await subscriber.subscribe(channelIn);
+        subscriber.on("message", (channel, data) => {
+          if (channel === channelIn) {
+            controller.enqueue(JSON.parse(data));
+          }
+        });
+      },
+      cancel() {
+        subscriber.unsubscribe(channelIn);
+        subscriber.quit();
+      },
+    }),
+    writable: new WritableStream({
+      write(message) {
+        publisher.publish(channelOut, JSON.stringify(message));
+      },
+      close() {
+        publisher.quit();
+      },
+    }),
+  };
+}
+```
+
+---
+
+## Transport Selection Guide
+
+| Transport | Use Case | Pros | Cons |
+|:----------|:---------|:-----|:-----|
+| **WebSocket** | Remote clients, browsers | Bidirectional, real-time | Requires WS support |
+| **stdio** | Subprocess agents | Simple, no network | Local only |
+| **In-process** | Testing, co-located | Zero latency | Same process only |
+| **HTTP + SSE** | Serverless, restricted envs | Works everywhere | Higher latency |
+
+---
+
+## Next Steps
+
+- [Server Setup](./server.html) - Configure your server
+- [Testing](./testing.html) - Use in-process transport for tests

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

@@ -0,0 +1,206 @@
+---
+title: SDK
+nav_order: 4
+has_children: true
+description: "MAP TypeScript SDK documentation"
+---
+
+# TypeScript SDK
+
+The Multi-Agent Protocol TypeScript SDK provides everything you need to build observable, coordinated multi-agent systems.
+{: .fs-6 .fw-300 }
+
+---
+
+## Who This Is For
+
+- **Agent Developers** - Build agents that register with MAP servers, receive messages, and collaborate with other agents
+- **Platform Developers** - Build MAP-compliant servers that orchestrate agents and expose them to clients
+- **Client Developers** - Build applications that observe and interact with multi-agent systems
+
+---
+
+## Installation
+
+```bash
+npm install @multi-agent-protocol/sdk
+```
+
+---
+
+## Quick Navigation
+
+### Guides
+
+| Guide | Description |
+|:------|:------------|
+| [Server Setup](./guides/server.html) | Set up a MAP server with MAPServer |
+| [Client Integration](./guides/client.html) | Connect clients that observe and send messages |
+| [Agent Integration](./guides/agent.html) | Build agents that register and process work |
+| [Transports](./guides/transports.html) | WebSocket, stdio, and custom transports |
+| [Authentication](./guides/authentication.html) | Configure authentication |
+| [Testing](./guides/testing.html) | Test your MAP integrations |
+
+### API Reference
+
+| Reference | Description |
+|:----------|:------------|
+| [Server API](./api/server.html) | MAPServer and building blocks |
+| [Client API](./api/client.html) | ClientConnection methods |
+| [Agent API](./api/agent.html) | AgentConnection methods |
+| [Types](./api/types.html) | TypeScript type definitions |
+
+---
+
+## Package Exports
+
+```typescript
+// Main exports (connections)
+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";
+
+// Stream utilities
+import { createStreamPair } from "@multi-agent-protocol/sdk/stream";
+
+// Type definitions
+import type {
+  Agent,
+  Message,
+  Event,
+  Subscription,
+} from "@multi-agent-protocol/sdk";
+```
+
+---
+
+## Minimal Example
+
+**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();
+});
+```
+
+**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(`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();
+
+// Subscribe to events
+const subscription = await client.subscribe({
+  eventTypes: ["agent.*"]
+});
+
+for await (const event of subscription) {
+  console.log("Event:", event.type);
+}
+```
+
+---
+
+## Progressive Disclosure
+
+The SDK follows a **progressive disclosure** pattern:
+
+### Level 1: Just Works
+
+```typescript
+const server = new MAPServer();
+```
+
+### Level 2: Customize Behavior
+
+```typescript
+const server = new MAPServer({
+  middleware: [loggingMiddleware, authMiddleware],
+  additionalHandlers: { "custom/method": myHandler },
+});
+```
+
+### Level 3: Full Control
+
+```typescript
+const eventBus = new EventBusImpl({
+  store: new RedisEventStore()
+});
+const agents = new AgentRegistryImpl({
+  eventBus,
+  store: new PostgresAgentStore()
+});
+// ... compose your own server
+```
+
+---
+
+## Key Concepts
+
+### Three Participant Types
+
+| Type | Class | Purpose |
+|:-----|:------|:--------|
+| **Agent** | `AgentConnection` | Worker that processes tasks |
+| **Client** | `ClientConnection` | Observer that monitors and sends messages |
+| **Gateway** | `GatewayConnection` | Bridge between federated systems |
+
+### Server Building Blocks
+
+| Component | Purpose |
+|:----------|:--------|
+| **EventBus** | Central event dispatcher |
+| **AgentRegistry** | Tracks registered agents |
+| **ScopeManager** | Manages logical groupings |
+| **SessionManager** | Handles connections |
+| **SubscriptionManager** | Event filtering and delivery |
+| **MessageRouter** | Routes messages |
+
+---
+
+## Next Steps
+
+1. **[Server Setup](./guides/server.html)** - Create your MAP server
+2. **[Agent Integration](./guides/agent.html)** - Build your first agent
+3. **[Client Integration](./guides/client.html)** - Build observability tools