macro-agent 0.1.1 → 0.1.3

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

@@ -1,353 +0,0 @@
----
-title: Streaming
-parent: Protocol
-nav_order: 3
-description: "Event streaming, subscriptions, filtering, and replay"
----
-
-# Streaming Semantics
-{: .no_toc }
-
-System-wide event streaming, subscriptions, filtering, and replay.
-{: .fs-6 .fw-300 }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
----
-
-## 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
-{
-  "jsonrpc": "2.0",
-  "id": "sub_001",
-  "method": "map/subscribe",
-  "params": {
-    "streams": ["messages", "state", "tasks"],
-    "filter": {
-      "agents": ["agent_worker_*"],      // Glob pattern
-      "roles": ["worker", "integrator"],
-      "scopes": ["scope_active"]
-    },
-    "options": {
-      "includeHistory": false,
-      "bufferSize": 1000,
-      "deliveryMode": "at-least-once"
-    }
-  }
-}
-
-// Response
-{
-  "jsonrpc": "2.0",
-  "id": "sub_001",
-  "result": {
-    "subscriptionId": "sub_a1b2c3",
-    "streams": ["messages", "state", "tasks"],
-    "effectiveFilter": { ... }
-  }
-}
-```
-
-### Subscription Lifecycle
-
-```mermaid
-stateDiagram-v2
-    [*] --> inactive
-    inactive --> active: subscribe
-    active --> paused: pause
-    paused --> active: resume
-    active --> closed: unsubscribe
-    paused --> closed: 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
-
-#### Messaging Events
-
-```typescript
-| { type: "message"; envelope: MAPEnvelope; receipts: MAPDeliveryReceipt[] }
-| { type: "message.ack"; messageId: string; agentId: string }
-| { type: "message.failed"; messageId: string; error: MAPError }
-```
-
-#### Agent State Events
-
-```typescript
-| { 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
-
-```typescript
-| { 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
-
-```typescript
-| { 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
-
-```typescript
-| { 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
-
-  // 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
-}
-```
-
-### Filter Examples
-
-**Single agent focus:**
-```typescript
-{ agents: ["agent_001"] }
-```
-
-**Role-based:**
-```typescript
-{ roles: ["worker"], eventTypes: ["task.*"] }
-```
-
-**Subtree observation:**
-```typescript
-{ subtree: "coordinator_001" }
-```
-
-**High-priority messages only:**
-```typescript
-{ eventTypes: ["message"], priorities: ["urgent", "high"] }
-```
-
----
-
-## 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
-    }
-  }
-}
-```
-
-### Replay Response
-
-```typescript
-{
-  "jsonrpc": "2.0",
-  "id": "replay_001",
-  "result": {
-    "events": [...],
-    "snapshot": { ... },          // Initial state snapshot
-    "hasMore": true,
-    "cursor": "cursor_xyz"        // For pagination
-  }
-}
-```
-
----
-
-## 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
-
-When a client falls behind:
-
-```typescript
-// Server notifies client of overflow
-{
-  "jsonrpc": "2.0",
-  "method": "map/subscription.overflow",
-  "params": {
-    "subscriptionId": "sub_a1b2c3",
-    "eventsDropped": 150,
-    "oldestDropped": "evt_x1y2z3",
-    "newestDropped": "evt_a4b5c6",
-    "recommendation": "reduce_filter_scope"
-  }
-}
-```
-
-### Recovery Options
-
-1. **Narrow filter** - Reduce the scope of events
-2. **Increase buffer** - Request larger server-side buffer
-3. **Replay missed** - Use replay API to catch up
-4. **Accept loss** - Continue from current position
-
----
-
-## Multiple Subscriptions
-
-Clients can maintain multiple concurrent subscriptions:
-
-```typescript
-// Subscription 1: High-priority messages only
-const urgentSub = await client.subscribe({
-  filter: { priorities: ["urgent", "high"] },
-  streams: ["messages"]
-});
-
-// Subscription 2: All state changes
-const stateSub = await client.subscribe({
-  filter: {},
-  streams: ["state"]
-});
-
-// Subscription 3: Specific agent subtree
-const agentSub = await client.subscribe({
-  filter: { subtree: "coordinator_001" },
-  streams: ["messages", "state", "tasks"]
-});
-```
-
----
-
-## Next Steps
-
-- [Connection Model](./connection-model.html) - Connection lifecycle
-- [Error Handling](./error-handling.html) - Handling delivery failures

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

@@ -1,369 +0,0 @@
----
-title: Wire Protocol
-parent: Protocol
-nav_order: 2
-description: "JSON-RPC 2.0 wire format and transport bindings"
----
-
-# Wire Protocol
-{: .no_toc }
-
-JSON-RPC 2.0 message format, method namespacing, and transport bindings.
-{: .fs-6 .fw-300 }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
----
-
-## 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
-
----
-
-## Message Types
-
-MAP uses four message types over JSON-RPC:
-
-### Request
-
-Expects a response:
-
-```typescript
-interface MAPRequest {
-  jsonrpc: "2.0";
-  id: string | number;
-  method: string;
-  params?: unknown;
-}
-```
-
-### Response
-
-Reply to a request:
-
-```typescript
-interface MAPResponse {
-  jsonrpc: "2.0";
-  id: string | number;
-  result?: unknown;
-  error?: MAPError;
-}
-```
-
-### Notification
-
-No response expected:
-
-```typescript
-interface MAPNotification {
-  jsonrpc: "2.0";
-  method: string;
-  params?: unknown;
-  // Note: no 'id' field
-}
-```
-
-### Batch
-
-Multiple messages:
-
-```typescript
-type MAPBatch = Array<MAPRequest | MAPNotification>;
-```
-
----
-
-## Method Namespacing
-
-```
-map/                    # Full MAP mode methods
-  ├── connect
-  ├── disconnect
-  ├── send
-  ├── subscribe
-  ├── unsubscribe
-  ├── agents/*
-  ├── scopes/*
-  ├── federation/*
-  └── ...
-
-_map/                   # ACP-compat mode (via extMethod)
-  ├── agent.list
-  ├── hierarchy.get
-  ├── scope.list
-  └── subscribe
-```
-
----
-
-## Protocol Phases
-
-### Phase 1: Connection Establishment
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Server
-
-    Client->>Server: Transport Connect
-    Server-->>Client: Transport Accept
-```
-
-### Phase 2: Protocol Negotiation
-
-```typescript
-// Client sends connect request
-{
-  "jsonrpc": "2.0",
-  "id": "req_001",
-  "method": "map/connect",
-  "params": {
-    "protocolVersion": "2025-01-01",
-    "participantType": "client",
-    "clientInfo": {
-      "name": "my-dashboard",
-      "version": "1.0.0"
-    },
-    "capabilities": {
-      "streaming": true,
-      "scopes": true,
-      "federation": false
-    }
-  }
-}
-
-// Server responds with negotiated capabilities
-{
-  "jsonrpc": "2.0",
-  "id": "req_001",
-  "result": {
-    "protocolVersion": "2025-01-01",
-    "sessionId": "session_001",
-    "serverInfo": {
-      "name": "map-server",
-      "version": "1.0.0"
-    },
-    "capabilities": {
-      "streaming": true,
-      "scopes": true,
-      "federation": true,
-      "replay": true,
-      "maxSubscriptions": 100,
-      "maxMessageSize": 1048576
-    }
-  }
-}
-```
-
-### Phase 3: Graceful Shutdown
-
-```typescript
-{
-  "jsonrpc": "2.0",
-  "id": "req_final",
-  "method": "map/disconnect",
-  "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": { "agent": "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",
-        "timestamp": 1706123456789
-      }
-    ]
-  }
-}
-```
-
-### Addressing
-
-```typescript
-type MAPAddress =
-  | { agent: string }           // Direct to agent
-  | { scope: string }           // Broadcast to scope
-  | { role: string }            // All agents with role
-  | { agents: string[] }        // Multiple specific agents
-  | { parent: true }            // Sender's parent
-  | { children: true };         // Sender's children
-```
-
----
-
-## ACP Compatibility Layer
-
-### Mode Detection
-
-```typescript
-function detectMode(request: MAPConnectRequest): "full" | "acp-compat" {
-  if (request.mode === "acp-compat") return "acp-compat";
-  if (!request.capabilities?.streaming) 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
-
-Primary transport for bidirectional streaming:
-
-```typescript
-// WebSocket frame format: JSON messages
-// Each message is a complete JSON object
-
-const ws = new WebSocket("wss://map.example.com/v1");
-ws.onmessage = (event) => {
-  const message = JSON.parse(event.data);
-  handleMessage(message);
-};
-```
-
-### Stdio (Subprocess Agents)
-
-NDJSON (newline-delimited JSON) format over stdin/stdout:
-
-```typescript
-interface StdioTransport {
-  stdin: WritableStream<MAPMessage>;
-  stdout: ReadableStream<MAPMessage>;
-  stderr: ReadableStream<string>;
-}
-
-// Each line is a complete JSON message
-// {"jsonrpc":"2.0","method":"map/connect",...}\n
-```
-
-### HTTP/SSE (Stateless Clients)
-
-```typescript
-// Endpoints:
-// POST /map/rpc          - Single RPC call
-// GET  /map/events       - SSE event stream
-// POST /map/batch        - Batch RPC calls
-
-// SSE event format
-event: map.event
-data: {"type":"agent.registered","agent":{...}}
-```
-
----
-
-## Error Format
-
-```typescript
-interface MAPError {
-  code: number;
-  message: string;
-  data?: {
-    category: string;
-    retryable?: boolean;
-    retryAfter?: number;
-    details?: unknown;
-  };
-}
-```
-
-### Standard Error Codes
-
-| Code | Category | Description |
-|:-----|:---------|:------------|
-| -32700 | protocol | Parse error |
-| -32600 | protocol | Invalid request |
-| -32601 | protocol | Method not found |
-| -32602 | protocol | Invalid params |
-| -32603 | protocol | Internal error |
-| 1000-1999 | auth | Authentication errors |
-| 2000-2999 | routing | Message delivery errors |
-| 3000-3999 | agent | Agent lifecycle errors |
-| 4000-4999 | resource | Resource exhaustion |
-| 5000-5999 | federation | Cross-system errors |
-
----
-
-## Protocol Extensions
-
-Custom methods use vendor prefixes:
-
-```typescript
-{
-  "jsonrpc": "2.0",
-  "id": "ext_001",
-  "method": "x-mycompany/workspace.sync",
-  "params": {
-    "worktree": "/path/to/worktree",
-    "remote": "origin/main"
-  }
-}
-```
-
----
-
-## Next Steps
-
-- [Streaming](./streaming.html) - Event subscriptions and filtering
-- [Error Handling](./error-handling.html) - Error taxonomy and recovery