macro-agent 0.1.1 → 0.1.3

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

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

@@ -1,253 +0,0 @@
-# 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?