macro-agent 0.1.2 → 0.1.3

package/references/multi-agent-protocol/docs-site/protocol/federation.md

@@ -1,449 +0,0 @@
----
-title: Federation
-parent: Protocol
-nav_order: 8
-description: "System-to-system communication and distributed architectures"
----
-
-# Federation
-{: .no_toc }
-
-Multi-system communication enabling distributed multi-agent architectures.
-{: .fs-6 .fw-300 }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
----
-
-## Design Principles
-
-1. **Internal transparency, external opacity** - Each system is transparent internally but appears as a single entity externally
-2. **MAP-native federation** - Systems communicate via MAP protocol, not A2A
-3. **Gateway pattern** - Dedicated agents handle inter-system routing
-4. **Selective exposure** - Each system controls what's visible to peers
-
----
-
-## Federation Model
-
-```mermaid
-flowchart LR
-    subgraph Alpha["MAP System 'Alpha'"]
-        A1["Agent A"]
-        A2["Agent B"]
-        A3["Agent C"]
-        GW1["Gateway"]
-        A1 --> GW1
-        A2 --> GW1
-        A3 --> GW1
-    end
-
-    subgraph Beta["MAP System 'Beta'"]
-        B1["Agent X"]
-        B2["Agent Y"]
-        B3["Agent Z"]
-        GW2["Gateway"]
-        B1 --> GW2
-        B2 --> GW2
-        B3 --> GW2
-    end
-
-    GW1 <-->|"MAP Protocol"| GW2
-```
-
----
-
-## Why MAP for Federation (not A2A)?
-
-| Aspect | A2A | MAP Federation |
-|:-------|:----|:---------------|
-| Visibility | Opaque peers | Configurable exposure |
-| Streaming | Task-focused | Full event streams |
-| Structure | Flat | Can expose partial hierarchy |
-| Discovery | Agent Cards | Direct connection |
-| Use case | Cross-org | Same-org distributed |
-
-{: .highlight }
-MAP federation is for **systems that trust each other** and want shared visibility.
-
----
-
-## Federation Configuration
-
-```typescript
-interface MAPFederationConfig {
-  enabled: boolean;
-  systemId: string;
-
-  systemInfo: {
-    name: string;
-    version: string;
-    endpoint: string;
-  };
-
-  peers: MAPPeerConfig[];
-  exposure: MAPFederationExposure;
-  security: MAPFederationSecurity;
-}
-
-interface MAPPeerConfig {
-  systemId: string;
-  endpoint: string;
-
-  connection: {
-    autoConnect: boolean;
-    reconnect: boolean;
-    healthCheckInterval: number;
-  };
-
-  accepts: {
-    messageTypes: string[];
-    maxMessagesPerMinute: number;
-  };
-
-  auth: {
-    method: "mutual-tls" | "bearer" | "api-key";
-    credentials: unknown;
-  };
-}
-
-interface MAPFederationExposure {
-  agents: {
-    expose: "none" | "gateway" | "tagged" | "all";
-    tags?: string[];
-  };
-  scopes: {
-    expose: "none" | "tagged" | "all";
-    tags?: string[];
-  };
-  events: {
-    expose: string[];
-  };
-  structure: boolean;
-}
-```
-
----
-
-## Gateway Agent Pattern
-
-Each system has a gateway agent that:
-
-1. **Handles connections** from peer systems
-2. **Routes messages** between internal agents and peers
-3. **Enforces exposure policies**
-4. **Translates addresses** between systems
-
-```typescript
-interface GatewayAgent {
-  id: string;
-  role: "gateway";
-
-  // Connected peers
-  peers: Map<string, PeerConnection>;
-
-  // Exposure rules
-  exposure: MAPFederationExposure;
-
-  // Message routing
-  routeToRemote(message: MAPMessage, peerId: string): Promise<void>;
-  routeFromRemote(message: MAPMessage, peerId: string): Promise<void>;
-}
-```
-
----
-
-## Federation Protocol
-
-### Connection Establishment
-
-```typescript
-{
-  "method": "map/federation/connect",
-  "params": {
-    "systemId": "alpha",
-    "systemInfo": {
-      "name": "Alpha System",
-      "version": "1.0.0",
-      "endpoint": "wss://alpha.example.com/map"
-    },
-    "protocolVersion": "2025-01-01",
-    "auth": {
-      "method": "mutual-tls",
-      "certificate": "..."
-    },
-    "exposure": {
-      "agents": { "expose": "tagged", "tags": ["public"] },
-      "scopes": { "expose": "tagged", "tags": ["federation"] },
-      "events": { "expose": ["message.sent", "agent.state"] }
-    }
-  }
-}
-
-// Response
-{
-  "result": {
-    "accepted": true,
-    "peerId": "peer_alpha_001",
-    "peerExposure": {
-      "agents": { "expose": "tagged", "tags": ["public"] },
-      "scopes": { "expose": "tagged", "tags": ["shared"] },
-      "events": { "expose": ["message.sent"] }
-    }
-  }
-}
-```
-
-### Cross-System Messaging
-
-```typescript
-{
-  "method": "map/federation/send",
-  "params": {
-    "peerId": "beta",
-    "message": {
-      "from": { "system": "alpha", "agent": "agent_a" },
-      "to": { "system": "beta", "agent": "agent_x" },
-      "payload": {
-        "type": "task_request",
-        "data": { ... }
-      }
-    },
-    "meta": {
-      "ttl": 30000,
-      "requireAck": true
-    }
-  }
-}
-```
-
----
-
-## Federated Addressing
-
-```typescript
-type MAPFederatedAddress =
-  // Specific agent in specific system
-  | { system: string; agent: string }
-
-  // Scope in specific system
-  | { system: string; scope: string }
-
-  // Role in specific system
-  | { system: string; role: string }
-
-  // Broadcast to all federated systems
-  | { federation: true }
-
-  // Broadcast to specific systems
-  | { federation: true; systems: string[] }
-
-  // Route through gateway
-  | { gateway: string; target: MAPAddress };
-```
-
-### Address Resolution
-
-```typescript
-// Local agent
-{ agent: "agent_001" }
-
-// Remote agent
-{ system: "beta", agent: "agent_x" }
-
-// Remote scope
-{ system: "beta", scope: "shared_workspace" }
-
-// All federation peers
-{ federation: true }
-```
-
----
-
-## Use Cases
-
-### Use Case 1: Distributed Workload
-
-Alpha handles task coordination, Beta handles execution:
-
-```mermaid
-flowchart LR
-    subgraph Alpha["Alpha System"]
-        Coord["Coordinator"]
-        GW1["Gateway"]
-        Dash["Dashboard"]
-        Coord --> GW1
-        GW1 --> Dash
-    end
-
-    subgraph Beta["Beta System"]
-        GW2["Gateway"]
-        Ex1["Executor 1"]
-        Ex2["Executor 2"]
-        GW2 --> Ex1
-        GW2 --> Ex2
-    end
-
-    GW1 -->|"tasks"| GW2
-    GW2 -->|"results"| GW1
-```
-
-### Use Case 2: Regional Distribution
-
-Each region has its own MAP system:
-
-```mermaid
-flowchart TB
-    subgraph US["US Region"]
-        USA["Agents"]
-        USGW["Gateway"]
-        USA --> USGW
-    end
-
-    subgraph EU["EU Region"]
-        EUA["Agents"]
-        EUGW["Gateway"]
-        EUA --> EUGW
-    end
-
-    subgraph Asia["Asia Region"]
-        AsiaA["Agents"]
-        AsiaGW["Gateway"]
-        AsiaA --> AsiaGW
-    end
-
-    USGW <--> EUGW
-    EUGW <--> AsiaGW
-    USGW <--> AsiaGW
-
-    Coord["Global Coordination"]
-    USGW -.-> Coord
-    EUGW -.-> Coord
-    AsiaGW -.-> Coord
-```
-
-### Use Case 3: Secure Computation
-
-Sensitive work isolated in secure system:
-
-```mermaid
-flowchart LR
-    subgraph Public["Public System"]
-        User["User Agent"]
-        PGW["Gateway"]
-        Agg["Aggregator"]
-        User --> PGW
-        PGW --> Agg
-    end
-
-    subgraph Secure["Secure System (airgapped)"]
-        SGW["Gateway"]
-        Proc["Processor"]
-        SGW --> Proc
-    end
-
-    PGW -->|"encrypted"| SGW
-    SGW -->|"results"| PGW
-```
-
----
-
-## Security
-
-### Authentication
-
-```typescript
-interface FederationSecurity {
-  // Required auth for peer connections
-  auth: {
-    required: true;
-    methods: ["mutual-tls", "bearer"];
-  };
-
-  // Message signing
-  signing: {
-    enabled: true;
-    algorithm: "RS256";
-    keyRotationInterval: 86400;  // 24 hours
-  };
-
-  // Rate limiting per peer
-  rateLimiting: {
-    messagesPerMinute: 1000;
-    connectionsPerPeer: 5;
-  };
-}
-```
-
-### Message Signing
-
-```typescript
-interface SignedFederationMessage {
-  message: MAPMessage;
-  signature: {
-    algorithm: string;
-    keyId: string;
-    value: string;
-    timestamp: number;
-  };
-}
-```
-
----
-
-## Failure Handling
-
-### Peer Unavailable
-
-```typescript
-// Queue messages for later delivery
-{
-  "method": "map/federation/queue",
-  "params": {
-    "peerId": "beta",
-    "message": { ... },
-    "options": {
-      "maxRetries": 5,
-      "retryDelay": 5000,
-      "expireAfter": 3600000  // 1 hour
-    }
-  }
-}
-```
-
-### Reconnection
-
-```typescript
-// Automatic reconnection with state sync
-{
-  "method": "map/federation/reconnect",
-  "params": {
-    "peerId": "beta",
-    "lastEventId": "evt_abc123",
-    "queuedMessages": 15
-  }
-}
-```
-
----
-
-## Federation vs A2A: When to Use Which
-
-| Scenario | Use | Reason |
-|:---------|:----|:-------|
-| Internal distributed system | MAP Federation | Need visibility, trust exists |
-| Cross-organization work | A2A | Different trust domains |
-| Multi-region deployment | MAP Federation | Same org, need coordination |
-| Partner integration | A2A | Maintain separation |
-| Development/staging sync | MAP Federation | Full visibility needed |
-
----
-
-## Next Steps
-
-- [Design](./design.html) - Overall protocol architecture
-- [Authentication](./authentication.html) - Federation auth details

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

@@ -1,129 +0,0 @@
----
-title: Protocol
-nav_order: 3
-has_children: true
-description: "MAP Protocol Specification"
----
-
-# Protocol Specification
-
-The complete specification for the Multi-Agent Protocol.
-{: .fs-6 .fw-300 }
-
----
-
-## Overview
-
-MAP is a JSON-RPC 2.0 based protocol designed for **observing, coordinating, and routing messages within multi-agent AI systems**. Unlike protocols designed for single-agent interaction (ACP) or peer-to-peer agent delegation (A2A), MAP provides a **window into** a multi-agent system with visibility into its internal structure, agent relationships, and message flows.
-
----
-
-## Core Sections
-
-| Section | Description |
-|:--------|:------------|
-| [Design](./design.html) | Core architecture, philosophy, and participant model |
-| [Wire Protocol](./wire-protocol.html) | JSON-RPC message format and transport bindings |
-| [Streaming](./streaming.html) | Event subscriptions, filtering, and replay |
-| [Connection Model](./connection-model.html) | Connection lifecycle and client patterns |
-| [Error Handling](./error-handling.html) | Error taxonomy and recovery mechanisms |
-| [Authentication](./authentication.html) | Authentication methods and flows |
-| [Permissions](./permissions.html) | 4-layer visibility and permission model |
-| [Federation](./federation.html) | System-to-system communication |
-
----
-
-## Protocol Methods
-
-The protocol defines **27 methods** across three tiers:
-
-### Core (Required)
-
-These methods MUST be implemented by all MAP-compliant servers:
-
-| Method | Description |
-|:-------|:------------|
-| `map/connect` | Establish connection and negotiate capabilities |
-| `map/disconnect` | Clean shutdown with optional cascade |
-| `map/send` | Send message to agents, scopes, or roles |
-| `map/subscribe` | Subscribe to event streams with filtering |
-| `map/unsubscribe` | Cancel active subscriptions |
-| `map/agents/list` | List registered agents |
-| `map/agents/get` | Get details for specific agent |
-
-### Structure (Recommended)
-
-These methods enable full agent lifecycle and scope management:
-
-**Agent Lifecycle:**
-- `map/agents/register` - Register a new agent
-- `map/agents/spawn` - Create child agent
-- `map/agents/unregister` - Remove agent from system
-- `map/agents/update` - Update agent metadata
-- `map/agents/stop` - Request agent termination
-- `map/agents/suspend` - Pause agent processing
-- `map/agents/resume` - Resume suspended agent
-
-**Scope Management:**
-- `map/scopes/create` - Create new scope
-- `map/scopes/join` - Join a scope
-- `map/scopes/leave` - Leave a scope
-- `map/scopes/list` - List available scopes
-
-### Extensions (Optional)
-
-**Federation:**
-- `map/federation/connect` - Establish peer connection
-- `map/federation/route` - Route to remote system
-
-**Session Management:**
-- `map/sessions/list` - List active sessions
-- `map/sessions/get` - Get session details
-
-**Steering:**
-- `map/inject` - Inject context into agent
-
----
-
-## Design Principles
-
-1. **Topology is configuration, not protocol** - Same protocol supports hierarchical orchestration and peer collaboration
-2. **Unified messaging with metadata** - One message type with metadata that specializes behavior
-3. **Visibility is first-class** - Agents and scopes have explicit visibility settings
-4. **Lifecycle is descriptive, not prescriptive** - Protocol records lifecycle metadata; implementations decide enforcement
-5. **Extensibility at every layer** - States, lifecycle patterns, visibility levels are all extensible
-6. **Unified participant model** - Agents and clients speak the same protocol
-
----
-
-## Quick Reference
-
-### Message Types
-
-```typescript
-// Request (expects response)
-{ jsonrpc: "2.0", id: string, method: string, params?: unknown }
-
-// Response
-{ jsonrpc: "2.0", id: string, result?: unknown, error?: MAPError }
-
-// Notification (no response)
-{ jsonrpc: "2.0", method: string, params?: unknown }
-```
-
-### Participant Types
-
-| Type | Role | Capabilities |
-|:-----|:-----|:-------------|
-| **Agent** | Worker | Register, send/receive, join scopes, spawn children |
-| **Client** | Observer | Subscribe, query, send messages (with permission) |
-| **Gateway** | Bridge | Route between federated systems |
-
-### Transport Bindings
-
-| Transport | Use Case | Framing |
-|:----------|:---------|:--------|
-| WebSocket | Remote clients, federation | JSON messages |
-| stdio | Subprocess agents | NDJSON (newline-delimited) |
-| In-process | Co-located agents | Direct object passing |
-| HTTP + SSE | Stateless clients | POST + Server-Sent Events |