macro-agent 0.0.11 → 0.0.12

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

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

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