macro-agent 0.0.14 → 0.0.16

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

@@ -0,0 +1,360 @@
+---
+title: Server Setup
+parent: Guides
+grand_parent: SDK
+nav_order: 1
+description: "Create and configure a MAP server"
+---
+
+# Server Setup
+{: .no_toc }
+
+Create MAP-compliant servers with MAPServer.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+`MAPServer` is the recommended way to create MAP-compliant servers. It wires together all building blocks with sensible defaults while providing access to everything for advanced use cases.
+
+---
+
+## Basic Usage
+
+```typescript
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+
+const server = new MAPServer({
+  name: "MyServer",
+  version: "1.0.0",
+});
+```
+
+That's it! The server now has:
+- EventBus for event dispatching
+- AgentRegistry for agent lifecycle
+- SessionManager for connection tracking
+- ScopeManager for logical groupings
+- SubscriptionManager for event filtering
+- MessageRouter for message delivery
+- All standard protocol handlers
+
+---
+
+## Accepting Connections
+
+Use `accept()` to handle incoming connections:
+
+```typescript
+import { createStreamPair } from "@multi-agent-protocol/sdk/stream";
+
+// For testing with in-memory streams
+const [clientStream, serverStream] = createStreamPair();
+const router = server.accept(serverStream);
+router.start();
+
+// For WebSocket
+wss.on("connection", (ws) => {
+  const stream = websocketToStream(ws);
+  const router = server.accept(stream);
+  router.start();
+});
+
+// With options
+server.accept(stream, {
+  role: "agent",        // "client" | "agent" | "gateway"
+  name: "WorkerAgent",  // Session name
+  resumeToken: token,   // For reconnection
+});
+```
+
+---
+
+## Configuration Options
+
+### Server Identity
+
+```typescript
+const server = new MAPServer({
+  name: "ProductionServer",     // Shown in connect response
+  version: "2.1.0",             // Shown in connect response
+  capabilities: {               // Advertised capabilities
+    subscriptions: { maxActive: 100 },
+    streaming: { backpressure: true },
+  },
+});
+```
+
+### Custom Handlers
+
+Add your own protocol methods:
+
+```typescript
+const server = new MAPServer({
+  additionalHandlers: {
+    "custom/echo": async (params, ctx) => {
+      return { echo: params };
+    },
+    "custom/stats": async (params, ctx) => {
+      return {
+        agents: server.agents.list().length,
+        sessions: server.sessions.list().length,
+      };
+    },
+  },
+});
+```
+
+### Middleware
+
+Add request/response middleware:
+
+```typescript
+const server = new MAPServer({
+  middleware: [
+    // Logging middleware
+    async (method, params, ctx, next) => {
+      console.log(`[${ctx.requestId}] ${method}`);
+      const start = Date.now();
+      const result = await next();
+      console.log(`[${ctx.requestId}] ${method} took ${Date.now() - start}ms`);
+      return result;
+    },
+
+    // Auth middleware
+    async (method, params, ctx, next) => {
+      if (method.startsWith("admin/") && ctx.session.role !== "admin") {
+        throw new Error("Unauthorized");
+      }
+      return next();
+    },
+  ],
+});
+```
+
+### Event Delivery
+
+Configure how events are delivered to subscriptions:
+
+```typescript
+const server = new MAPServer({
+  eventDelivery: {
+    enabled: true,  // Default: true
+
+    // Custom filter for event delivery
+    filter: (event, subscription) => {
+      // Don't deliver internal events to clients
+      if (event.type.startsWith("internal.")) {
+        return false;
+      }
+      return true;
+    },
+  },
+});
+```
+
+---
+
+## Accessing Building Blocks
+
+All building blocks are accessible for direct manipulation:
+
+```typescript
+// Direct agent registration (bypassing protocol)
+const agent = server.agents.register({
+  name: "SystemAgent",
+  sessionId: "internal",
+  role: "system",
+});
+
+// Direct scope creation
+const scope = server.scopes.create({
+  name: "global",
+  metadata: { description: "Global announcement channel" },
+});
+
+// Direct session management
+const sessions = server.sessions.list({ status: "connected" });
+
+// Direct event emission
+server.emit({
+  type: "system.started",
+  data: { timestamp: Date.now() },
+});
+
+// Event subscription
+server.on("agent.registered", (event) => {
+  console.log(`New agent: ${event.data.agent.name}`);
+});
+```
+
+---
+
+## Custom Storage
+
+Use custom stores for persistence:
+
+```typescript
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+
+const server = new MAPServer({
+  stores: {
+    events: new RedisEventStore(redis),
+    agents: new PostgresAgentStore(db),
+    sessions: new RedisSessionStore(redis),
+    scopes: new PostgresScopeStore(db),
+    subscriptions: new InMemorySubscriptionStore(),
+    messages: new RabbitMQMessageStore(channel),
+  },
+});
+```
+
+### Store Interfaces
+
+```typescript
+interface EventStore {
+  append(event: MAPEvent): void;
+  getAfter(afterId: string, limit?: number): MAPEvent[];
+  getByType(type: string, limit?: number): MAPEvent[];
+  clear(): void;
+}
+
+interface AgentStore {
+  save(agent: RegisteredAgent): void;
+  get(id: string): RegisteredAgent | undefined;
+  list(filter?: AgentFilter): RegisteredAgent[];
+  delete(id: string): boolean;
+  clear(): void;
+}
+```
+
+---
+
+## Replacing Building Blocks
+
+For full control, replace entire building blocks:
+
+```typescript
+import {
+  MAPServer,
+  EventBusImpl,
+  AgentRegistryImpl,
+} from "@multi-agent-protocol/sdk/server";
+
+// Custom EventBus with special behavior
+const customEventBus = new EventBusImpl({
+  store: new RedisEventStore(redis),
+});
+
+// Custom AgentRegistry
+const customAgents = new AgentRegistryImpl({
+  eventBus: customEventBus,
+  store: new PostgresAgentStore(db),
+});
+
+const server = new MAPServer({
+  eventBus: customEventBus,
+  agents: customAgents,
+  // Other blocks will use the custom eventBus
+});
+```
+
+---
+
+## Graceful Shutdown
+
+```typescript
+// Graceful shutdown (default 5s timeout)
+await server.close();
+
+// Custom timeout
+await server.close({ timeout: 10000 });
+
+// Force close (no waiting)
+await server.close({ force: true });
+```
+
+---
+
+## Complete Example
+
+```typescript
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { WebSocketServer } from "ws";
+
+// Create server with common configuration
+const server = new MAPServer({
+  name: "ProductionServer",
+  version: "1.0.0",
+
+  // Add custom methods
+  additionalHandlers: {
+    "stats/overview": async () => ({
+      agents: server.agents.list().length,
+      scopes: server.scopes.list().length,
+      connections: server.connections.size,
+    }),
+  },
+
+  // Add logging
+  middleware: [
+    async (method, params, ctx, next) => {
+      console.log(`${ctx.session.id} -> ${method}`);
+      return next();
+    },
+  ],
+
+  // Configure event delivery
+  eventDelivery: {
+    filter: (event) => !event.type.startsWith("internal."),
+  },
+});
+
+// Listen for system events
+server.on("agent.registered", (event) => {
+  console.log(`Agent registered: ${event.data.agent.name}`);
+});
+
+server.on("session.connected", (event) => {
+  console.log(`Session connected: ${event.data.session.id}`);
+});
+
+// WebSocket server
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", (ws) => {
+  const stream = websocketToStream(ws);
+  const router = server.accept(stream);
+  router.start();
+
+  ws.on("close", () => {
+    console.log("Connection closed");
+  });
+});
+
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  console.log("Shutting down...");
+  await server.close();
+  wss.close();
+  process.exit(0);
+});
+
+console.log("Server listening on ws://localhost:8080");
+```
+
+---
+
+## Next Steps
+
+- [Client Integration](./client.html) - Build monitoring dashboards
+- [Agent Integration](./agent.html) - Build agents that connect
+- [Transports](./transports.html) - Use different transports
+- [Testing](./testing.html) - Test your server