macro-agent 0.0.13 → 0.0.15

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

@@ -0,0 +1,259 @@
+# MAP Federation & System-to-System Communication
+
+This spec details how multiple MAP systems can communicate with each other, enabling distributed multi-agent architectures while maintaining internal transparency.
+
+## 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
+
+### Conceptual View
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          Federation                                       │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────┐         ┌─────────────────────────┐        │
+│  │   MAP System "Alpha"    │         │   MAP System "Beta"     │        │
+│  │                         │         │                         │        │
+│  │  Internal agents:       │         │  Internal agents:       │        │
+│  │  ┌───┐ ┌───┐ ┌───┐     │   MAP   │  ┌───┐ ┌───┐ ┌───┐     │        │
+│  │  │ A │ │ B │ │ C │     │ ◄─────► │  │ X │ │ Y │ │ Z │     │        │
+│  │  └─┬─┘ └─┬─┘ └─┬─┘     │         │  └─┬─┘ └─┬─┘ └─┬─┘     │        │
+│  │    └─────┼─────┘       │         │    └─────┼─────┘       │        │
+│  │          │             │         │          │             │        │
+│  │    ┌─────▼─────┐       │         │    ┌─────▼─────┐       │        │
+│  │    │  Gateway  │───────┼─────────┼────│  Gateway  │       │        │
+│  │    └───────────┘       │         │    └───────────┘       │        │
+│  │                         │         │                         │        │
+│  └─────────────────────────┘         └─────────────────────────┘        │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 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 |
+
+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
+
+---
+
+## 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"] }
+    }
+  }
+}
+```
+
+### Cross-System Messaging
+
+```typescript
+{
+  "method": "map/federation/send",
+  "params": {
+    "peerId": "beta",
+    "message": {
+      "from": "agent_a",
+      "to": { "agent": "agent_x" },
+      "payload": {
+        "type": "task_request",
+        "data": { ... }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Addressing in Federation
+
+```typescript
+type MAPFederatedAddress =
+  | { system: string; agent: string }
+  | { system: string; scope: string }
+  | { system: string; role: string }
+  | { federation: true }
+  | { federation: true; systems: string[] }
+  | { gateway: string; target: MAPAddress };
+```
+
+---
+
+## Use Cases
+
+### Use Case 1: Distributed Workload
+
+Alpha handles task coordination, Beta handles execution.
+
+### Use Case 2: Regional Distribution
+
+Each region has its own MAP system, federated for global coordination.
+
+### Use Case 3: Secure Computation
+
+Sensitive computation isolated in secure system, federated for I/O.
+
+---
+
+## Federation vs A2A: When to Use Which
+
+| Scenario | Use | Reason |
+|----------|-----|--------|
+| Internal distributed system | MAP Federation | Need visibility, trust exists |
+| External partner integration | A2A | Opaque peers, no visibility needed |
+| Multi-cloud same org | MAP Federation | Control over both systems |
+| Third-party service | A2A | Don't control peer system |
+| Hierarchical multi-region | MAP Federation | Want structure visibility |
+| Ad-hoc collaboration | A2A | Dynamic peer discovery |
+
+---
+
+## Security Considerations
+
+### Authentication
+
+```typescript
+type MAPFederationAuth =
+  | { method: "mutual-tls"; certificate: string }
+  | { method: "bearer"; token: string }
+  | { method: "api-key"; key: string }
+  | { method: "oauth2"; config: OAuth2Config };
+```
+
+### Message Signing
+
+```typescript
+interface MAPFederationEnvelope {
+  message: MAPMessage;
+  federation: {
+    sourceSystem: string;
+    targetSystem: string;
+    hopCount: number;
+    timestamp: number;
+    signature?: string;
+  };
+}
+```
+
+---
+
+## Failure Handling
+
+### Message Queue During Outage
+
+```typescript
+interface MAPFederationQueueConfig {
+  queueOnDisconnect: boolean;
+  maxQueueDuration: number;
+  maxQueueSize: number;
+  overflowPolicy: "drop-oldest" | "drop-newest" | "reject-new";
+}
+```
+
+---
+
+## Open Questions
+
+1. **Transitive federation**: If A↔B and B↔C, can A route to C via B?
+2. **Federation discovery**: Should there be a discovery mechanism for finding peers?
+3. **Consistency**: How to handle concurrent updates across federated systems?
+4. **Schema versioning**: What if peers have different protocol versions?
+5. **Audit requirements**: What federation activity must be logged?

package/references/multi-agent-protocol/docs/08-macro-agent-migration.md

@@ -0,0 +1,253 @@
+# macro-agent Migration to MAP
+
+This spec provides a concrete example of how the existing macro-agent implementation would migrate to use MAP, demonstrating the protocol's practical application.
+
+## Current Architecture Recap
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   macro-agent Today                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  External Layer                                             │
+│  • ACP (via MacroAgent class)                              │
+│  • REST API (Express server)                               │
+│  • WebSocket server                                         │
+│                                                             │
+│  Communication Layers (3 separate systems)                  │
+│  1. ACP Extensions (_macro/*)                              │
+│  2. MessageRouter (6 channel types)                        │
+│  3. PeerManager (cross-instance)                           │
+│                                                             │
+│  Core Components                                            │
+│  • AgentManager (lifecycle)                                │
+│  • EventStore (persistence)                                │
+│  • TaskManager / TaskBackend                               │
+│  • WorkspaceManager (git worktrees)                        │
+│  • MergeQueue                                              │
+│  • RoleRegistry                                            │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Migration Strategy
+
+### Phase 1: Protocol Adapter Layer
+
+Add MAP as an alternative protocol layer without changing internals.
+
+### Phase 2: Unified Communication
+
+Replace MessageRouter + PeerManager with MAP-native implementation.
+
+### Phase 3: Full MAP Native
+
+All components use MAP primitives.
+
+---
+
+## Component Mapping
+
+| macro-agent Component | MAP Equivalent |
+|----------------------|----------------|
+| `AgentManager.spawn()` | `map/agent.register` |
+| `AgentManager.getHierarchy()` | `map/hierarchy.get` |
+| `MessageRouter.send()` | `map/send` |
+| `MessageRouter.subscribe()` | `map/subscribe` |
+| `Broadcast channels` | `map/broadcast` + Scopes |
+| `Role channels` | Role-based addressing |
+| `PeerManager.sendMessage()` | `map/send` to federated address |
+| `injectContext()` | `map/inject` |
+
+---
+
+## Code Examples
+
+### Before: Spawning an Agent (ACP Extension)
+
+```typescript
+// Current: src/acp/macro-agent.ts
+async handleSpawnAgent(params, sessionId) {
+  const mapping = this.sessionMapper.getMapping(sessionId);
+  const parentId = params.parentId ?? mapping?.agentId;
+
+  // Check role capability
+  if (params.role) {
+    const capability = `agent.spawn.${params.role}`;
+    if (!this.roleRegistry.hasCapability(parentAgent.role, capability)) {
+      throw new ACPError("Cannot spawn this role", "CAPABILITY_DENIED");
+    }
+  }
+
+  const result = await this.agentManager.spawn({ ... });
+  return { agentId: result.agentId, taskId: result.taskId };
+}
+```
+
+### After: Spawning an Agent (MAP)
+
+```typescript
+// New: src/map/handlers/agent.ts
+async handleAgentRegister(params, context) {
+  // Role capability check is now protocol-level
+
+  const agent = await this.registry.registerAgent({
+    id: generateAgentId(),
+    name: params.name,
+    role: params.role,
+    parent: params.parent ?? context.agentId,
+  });
+
+  const process = await this.processManager.spawn({
+    agentId: agent.id,
+    role: params.role,
+  });
+
+  await this.events.emit({ type: "agent.registered", agent });
+
+  return { agentId: agent.id, registered: true };
+}
+```
+
+### Before: Sending a Message
+
+```typescript
+// Current: MessageRouter
+async send(from, channel, message) {
+  const recipients = await this.resolveChannel(channel, from);
+  const wakeAction = this.determineWakeAction(message.priority);
+
+  for (const recipientId of recipients) {
+    // Complex wake/inject/queue logic
+  }
+
+  await this.eventStore.emit({ type: "message_sent", ... });
+}
+```
+
+### After: Sending a Message (MAP)
+
+```typescript
+// New: Using MAP SDK
+await this.map.send({
+  to: { role: "worker", within: "scope_active" },
+  payload: { type: "task_assignment", task: { id: "task_001" } },
+  meta: { priority: "high", delivery: "inject" }
+});
+```
+
+### Before: Context Injection
+
+```typescript
+// Current: src/steering/inject.ts
+export async function injectContext(agentId, content, deps) {
+  const session = await deps.agentManager.getSession(agentId);
+
+  // Try inject → interrupt → message fallback
+  if (session.inject) { ... }
+  if (session.interruptWith) { ... }
+  await deps.messageRouter.send(...);
+}
+```
+
+### After: Context Injection (MAP)
+
+```typescript
+// MAP inject with explicit semantics
+await this.map.inject({
+  to: { agent: agentId },
+  payload: { content },
+  meta: {
+    delivery: "best-effort",  // Try inject → interrupt → queue
+    priority: "high"
+  }
+});
+```
+
+---
+
+## Subscription Migration
+
+### Before: Multiple subscription points
+
+```typescript
+// 1. MessageRouter subscription
+await messageRouter.subscribe(agentId, { type: "subtree", rootId: parentId });
+
+// 2. EventStore subscription
+eventStore.on("task_completed", (event) => { ... });
+
+// 3. PeerManager inbox polling
+const messages = await peerManager.getInbox(agentId);
+
+// 4. Session update callbacks
+session.onUpdate((update) => { ... });
+```
+
+### After: Unified Subscription (MAP)
+
+```typescript
+const subscription = await this.map.subscribe({
+  streams: ["messages", "tasks", "state"],
+  filter: {
+    subtree: myAgentId,
+    eventTypes: ["message", "task.completed", "agent.state"]
+  }
+});
+
+for await (const event of subscription.events) {
+  switch (event.type) {
+    case "message": handleMessage(event.envelope); break;
+    case "task.completed": handleTaskComplete(event.task); break;
+    case "agent.state": handleStateChange(event.agentId, event.current); break;
+  }
+}
+```
+
+---
+
+## Migration Checklist
+
+### Phase 1: Adapter Layer
+- [ ] Add MAP SDK dependency
+- [ ] Create MAPAdapter class wrapping existing components
+- [ ] Implement MAP server alongside existing ACP server
+- [ ] Add feature flag for MAP mode
+- [ ] Write integration tests comparing ACP vs MAP behavior
+
+### Phase 2: Unified Communication
+- [ ] Migrate MessageRouter to use MAP addressing
+- [ ] Migrate PeerManager to MAP federation
+- [ ] Consolidate event subscriptions
+- [ ] Remove duplicate event emission
+- [ ] Update agent spawn to use MAP registration
+
+### Phase 3: Full Native
+- [ ] Migrate TaskManager to MAP tasks (optional)
+- [ ] Migrate RoleRegistry to MAP roles
+- [ ] Remove legacy communication code
+- [ ] Update all clients to MAP
+- [ ] Deprecate ACP extensions (keep compat layer)
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Breaking existing ACP clients | ACP-compat mode as fallback |
+| Performance regression | Benchmark at each phase |
+| Feature parity gaps | Feature flag for gradual rollout |
+| State migration | Snapshot + replay for existing sessions |
+| Federation complexity | Phase federation last |
+
+---
+
+## Open Questions
+
+1. **Task backend**: Keep as separate abstraction or fully integrate?
+2. **Workspace/git**: Should environment concept include workspace management?
+3. **MCP tools**: Should MAP define standard tools or leave to implementation?
+4. **Session persistence**: How to migrate existing ACP sessions to MAP?