macro-agent 0.0.14 → 0.0.16

package/references/multi-agent-protocol/docs/02-wire-protocol.md

@@ -0,0 +1,296 @@
+# MAP Wire Protocol & ACP Compatibility Layer
+
+This spec details the wire protocol format for MAP and how it maintains compatibility with ACP.
+
+## Design Goals
+
+1. **JSON-RPC 2.0 base** - Same foundation as ACP for tooling compatibility
+2. **Bidirectional streaming** - Native support, not bolted on
+3. **ACP downgrade path** - Graceful degradation to ACP-only clients
+4. **Transport agnostic** - WebSocket, stdio, HTTP/SSE all viable
+
+---
+
+## Wire Protocol Format
+
+### Message Types
+
+MAP uses four message types over JSON-RPC:
+
+```typescript
+// 1. Request (expects response)
+interface MAPRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+// 2. Response (to a request)
+interface MAPResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: MAPError;
+}
+
+// 3. Notification (no response expected)
+interface MAPNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+  // Note: no 'id' field
+}
+
+// 4. Batch (multiple messages)
+type MAPBatch = Array<MAPRequest | MAPNotification>;
+```
+
+### Method Namespacing
+
+```
+map/                    # Full MAP mode methods
+  ├── initialize
+  ├── agent.*
+  ├── hierarchy.*
+  ├── scope.*
+  ├── send
+  ├── request
+  ├── broadcast
+  ├── inject
+  ├── subscribe
+  ├── task.*
+  ├── role.*
+  ├── env.*
+  └── user.*
+
+_map/                   # ACP-compat mode (via extMethod)
+  ├── agent.list
+  ├── hierarchy.get
+  ├── scope.list
+  ├── send
+  ├── broadcast
+  ├── task.list
+  └── subscribe
+```
+
+---
+
+## Protocol Phases
+
+### Phase 1: Connection Establishment
+
+```
+Client                                    Server
+   │                                         │
+   │─────── Transport Connect ──────────────►│
+   │                                         │
+   │◄────── Transport Accept ───────────────│
+   │                                         │
+```
+
+### Phase 2: Protocol Negotiation
+
+```typescript
+// Client sends initialize request
+{
+  "jsonrpc": "2.0",
+  "id": "req_001",
+  "method": "map/initialize",
+  "params": {
+    "protocolVersion": "2025-01-01",
+    "mode": "full",                    // or "acp-compat"
+    "clientInfo": {
+      "name": "macro-agent",
+      "version": "1.0.0"
+    },
+    "capabilities": {
+      "streaming": true,
+      "scopes": true,
+      "tasks": true,
+      "roles": true,
+      "environments": true,
+      "federation": false
+    }
+  }
+}
+
+// Server responds with negotiated capabilities
+{
+  "jsonrpc": "2.0",
+  "id": "req_001",
+  "result": {
+    "protocolVersion": "2025-01-01",
+    "mode": "full",
+    "serverInfo": {
+      "name": "map-server",
+      "version": "1.0.0"
+    },
+    "capabilities": {
+      "streaming": true,
+      "scopes": true,
+      "tasks": true,
+      "roles": true,
+      "environments": true,
+      "federation": true,
+      "replay": true,
+      "deliverySemantics": ["inject", "interrupt", "queue", "best-effort"],
+      "maxSubscriptions": 100,
+      "maxMessageSize": 1048576
+    },
+    "agentId": "agent_root_001"
+  }
+}
+```
+
+### Phase 3: Graceful Shutdown
+
+```typescript
+// Client initiates shutdown
+{
+  "jsonrpc": "2.0",
+  "id": "req_final",
+  "method": "map/shutdown",
+  "params": {
+    "reason": "user_requested",
+    "timeout": 5000,
+    "cascade": true
+  }
+}
+```
+
+---
+
+## Messaging Wire Format
+
+### Send Message
+
+```typescript
+// Request
+{
+  "jsonrpc": "2.0",
+  "id": "msg_001",
+  "method": "map/send",
+  "params": {
+    "to": { "type": "agent", "id": "agent_worker_001" },
+    "payload": {
+      "type": "task_assignment",
+      "task": {
+        "id": "task_001",
+        "description": "Review PR #123"
+      }
+    },
+    "meta": {
+      "priority": "high",
+      "delivery": "inject",
+      "ttl": 60000,
+      "requireAck": true
+    }
+  }
+}
+
+// Response
+{
+  "jsonrpc": "2.0",
+  "id": "msg_001",
+  "result": {
+    "messageId": "envelope_a1b2c3",
+    "delivered": 1,
+    "receipts": [
+      {
+        "agentId": "agent_worker_001",
+        "status": "delivered",
+        "semantic": "inject",
+        "timestamp": 1706123456789
+      }
+    ]
+  }
+}
+```
+
+---
+
+## ACP Compatibility Layer
+
+### Mode Detection
+
+```typescript
+function detectMode(request: MAPInitializeRequest): "full" | "acp-compat" {
+  if (request.mode === "acp-compat") return "acp-compat";
+  if (!request.capabilities?.streaming) return "acp-compat";
+  if (!request.mode && request.clientCapabilities) return "acp-compat";
+  return "full";
+}
+```
+
+### Feature Degradation Table
+
+| Feature | Full MAP | ACP-compat |
+|---------|----------|------------|
+| Multi-agent context | Native | Session-per-agent |
+| Streaming | Native bidirectional | Via sessionUpdate |
+| Hierarchy queries | Full tree ops | Flat list only |
+| Scopes | Full CRUD | Read-only listing |
+| Delivery semantics | All 4 modes | Best-effort only |
+| Federation | Supported | Not available |
+| Subscriptions | Multiple concurrent | Single per session |
+
+---
+
+## Transport Bindings
+
+### WebSocket
+
+```typescript
+// Primary transport for bidirectional streaming
+// WebSocket frame format: NDJSON (newline-delimited JSON)
+// Each message is a single line of JSON followed by \n
+```
+
+### Stdio (for subprocess agents)
+
+```typescript
+// Same NDJSON format over stdin/stdout
+interface StdioTransport {
+  stdin: WritableStream<MAPMessage>;
+  stdout: ReadableStream<MAPMessage>;
+  stderr: ReadableStream<string>;
+}
+```
+
+### HTTP/SSE (for stateless clients)
+
+```typescript
+// Endpoints:
+// POST /map/rpc          - Single RPC call
+// GET  /map/events       - SSE event stream
+// POST /map/batch        - Batch RPC calls
+```
+
+---
+
+## Protocol Extensions
+
+### Custom Methods
+
+```typescript
+// Vendor-specific extension
+{
+  "jsonrpc": "2.0",
+  "id": "ext_001",
+  "method": "macro/workspace.sync",
+  "params": {
+    "worktree": "/path/to/worktree",
+    "remote": "origin/main"
+  }
+}
+```
+
+---
+
+## Open Questions
+
+1. **Compression**: Should we support message compression (gzip, brotli)?
+2. **Batching**: Should batch responses preserve order or allow reordering?
+3. **Heartbeat**: Explicit ping/pong or rely on transport-level?
+4. **Message size limits**: Hard protocol limit or capability-negotiated?

package/references/multi-agent-protocol/docs/03-streaming-semantics.md

@@ -0,0 +1,252 @@
+# MAP Streaming Semantics
+
+This spec details how MAP handles system-wide event streaming, subscriptions, filtering, and replay.
+
+## Design Goals
+
+1. **System-wide visibility** - See all agent activity, not just one session
+2. **Efficient filtering** - Subscribe only to relevant events
+3. **Replay capability** - Catch up on missed events
+4. **Backpressure handling** - Don't overwhelm slow consumers
+5. **Ordered delivery** - Causal ordering where it matters
+
+---
+
+## Subscription Model
+
+### Creating Subscriptions
+
+```typescript
+// Subscribe to multiple stream types with filtering
+{
+  "jsonrpc": "2.0",
+  "id": "sub_001",
+  "method": "map/subscribe",
+  "params": {
+    "streams": ["messages", "state", "tasks"],
+    "filter": {
+      "agents": ["agent_worker_*"],      // Glob pattern
+      "roles": ["worker", "integrator"],
+      "priorities": ["urgent", "high"],
+      "scopes": ["scope_active"]
+    },
+    "options": {
+      "includeHistory": false,
+      "bufferSize": 1000,
+      "deliveryMode": "at-least-once"
+    }
+  }
+}
+```
+
+### Subscription Lifecycle
+
+```
+   ┌──────────┐    subscribe    ┌──────────┐
+   │ inactive │ ──────────────► │  active  │
+   └──────────┘                 └────┬─────┘
+        ▲                            │
+        │                            │ pause
+        │                            ▼
+        │                       ┌──────────┐
+        │         resume        │  paused  │
+        │ ◄──────────────────── └────┬─────┘
+        │                            │
+        │ unsubscribe               │ unsubscribe
+        │                            ▼
+        └─────────────────────► ┌──────────┐
+                                │  closed  │
+                                └──────────┘
+```
+
+---
+
+## Event Delivery
+
+### Event Envelope
+
+```typescript
+interface MAPStreamEventEnvelope {
+  subscriptionId: string;
+  sequence: number;              // Monotonic within subscription
+  timestamp: number;             // Server timestamp
+  event: MAPStreamEvent;
+
+  // For ordering/dedup
+  eventId: string;               // Globally unique
+  causedBy?: string[];           // Causal predecessors
+}
+```
+
+### Event Types
+
+```typescript
+type MAPStreamEvent =
+  // Messaging events
+  | { type: "message"; envelope: MAPEnvelope; receipts: MAPDeliveryReceipt[] }
+  | { type: "message.ack"; messageId: string; agentId: string }
+  | { type: "message.failed"; messageId: string; error: MAPError }
+
+  // Agent state events
+  | { type: "agent.registered"; agent: MAPAgent }
+  | { type: "agent.unregistered"; agentId: string; reason: string }
+  | { type: "agent.state"; agentId: string; previous: string; current: string }
+  | { type: "agent.updated"; agentId: string; changes: Partial<MAPAgent> }
+
+  // Task events
+  | { type: "task.created"; task: MAPTask }
+  | { type: "task.assigned"; taskId: string; agentId: string }
+  | { type: "task.status"; taskId: string; previous: string; current: string }
+  | { type: "task.completed"; taskId: string; result?: unknown }
+
+  // Scope events
+  | { type: "scope.created"; scope: MAPScope }
+  | { type: "scope.deleted"; scopeId: string }
+  | { type: "scope.member.added"; scopeId: string; agentId: string }
+  | { type: "scope.member.removed"; scopeId: string; agentId: string }
+
+  // System events
+  | { type: "system.heartbeat"; timestamp: number }
+  | { type: "system.capacity"; agents: number; maxAgents: number };
+```
+
+---
+
+## Filtering
+
+### Filter Syntax
+
+```typescript
+interface MAPStreamFilter {
+  // Agent filtering (OR within, AND across fields)
+  agents?: string[];              // Glob patterns
+  roles?: string[];               // Role names
+  scopes?: string[];              // Scope IDs
+  environments?: string[];        // Environment IDs
+
+  // Event filtering
+  eventTypes?: string[];          // e.g., ["message", "task.*"]
+  priorities?: MAPPriority[];     // For message events
+
+  // Hierarchy filtering
+  descendants?: string;           // All descendants of agent
+  ancestors?: string;             // All ancestors of agent
+  subtree?: string;               // Agent and all descendants
+}
+```
+
+---
+
+## Replay
+
+### Replay Request
+
+```typescript
+{
+  "jsonrpc": "2.0",
+  "id": "replay_001",
+  "method": "map/replay",
+  "params": {
+    // Time-based replay
+    "from": 1706120000000,
+    "to": 1706123456789,
+
+    // OR event-based replay
+    "afterEventId": "evt_x1y2z3",
+
+    // Filter
+    "filter": {
+      "agents": ["agent_worker_*"],
+      "eventTypes": ["task.*"]
+    },
+
+    // Options
+    "options": {
+      "limit": 1000,
+      "order": "chronological",
+      "includeSnapshots": true
+    }
+  }
+}
+```
+
+---
+
+## Ordering Guarantees
+
+### Within-Agent Ordering
+
+Events for a single agent are always delivered in causal order:
+
+```
+Agent A: state=idle → state=busy → state=idle
+         (seq 1)      (seq 2)      (seq 3)
+```
+
+### Cross-Agent Ordering
+
+Events across agents may be reordered unless causally related:
+
+```
+Agent A: message sent ────────────────┐
+                                      ▼
+Agent B:                    message received → state=busy
+
+// The "message received" always comes after "message sent"
+// But unrelated events may interleave
+```
+
+### Ordering Modes
+
+```typescript
+interface SubscriptionOptions {
+  ordering:
+    | "none"           // No ordering guarantee (fastest)
+    | "per-agent"      // Ordered within each agent
+    | "causal"         // Full causal ordering (may have latency)
+    | "total";         // Total ordering (highest latency)
+}
+```
+
+---
+
+## Backpressure
+
+### Client Flow Control
+
+```typescript
+// Client acknowledges events (enables flow control)
+{
+  "jsonrpc": "2.0",
+  "method": "map/subscribe.ack",
+  "params": {
+    "subscriptionId": "sub_a1b2c3",
+    "upToSequence": 100
+  }
+}
+```
+
+### Overflow Handling
+
+```typescript
+// Server notifies client of overflow
+{
+  "event": {
+    "type": "subscription.overflow",
+    "eventsDropped": 150,
+    "oldestDropped": "evt_x1y2z3",
+    "newestDropped": "evt_a4b5c6",
+    "recommendation": "reduce_filter_scope"
+  }
+}
+```
+
+---
+
+## Open Questions
+
+1. **Event retention**: How long should servers retain events for replay?
+2. **Compression**: Should event streams be compressible?
+3. **Fan-out limits**: Max subscribers per event type?
+4. **Cross-federation streaming**: How do events propagate across federated systems?
+5. **Snapshot frequency**: How often should state snapshots be created?