macro-agent 0.0.13 → 0.0.15

package/references/multi-agent-protocol/docs/04-error-handling.md

@@ -0,0 +1,231 @@
+# MAP Error Handling & Failure Modes
+
+This spec details how MAP handles errors, failures, and recovery across single-node and federated deployments.
+
+## Design Goals
+
+1. **Graceful degradation** - Partial failures don't cascade to total failure
+2. **Clear error taxonomy** - Distinct error types with actionable codes
+3. **Recovery semantics** - Well-defined reconnection and replay behavior
+4. **Federation resilience** - Cross-system failures handled gracefully
+5. **Observability** - Errors are traceable and debuggable
+
+---
+
+## Error Taxonomy
+
+### Error Categories
+
+```typescript
+type MAPErrorCategory =
+  | "protocol"      // Wire protocol violations
+  | "auth"          // Authentication/authorization
+  | "routing"       // Message delivery failures
+  | "agent"         // Agent lifecycle errors
+  | "resource"      // Resource exhaustion
+  | "federation"    // Cross-system errors
+  | "internal";     // Server internal errors
+```
+
+### Error Structure
+
+```typescript
+interface MAPError {
+  code: number;                  // Numeric code
+  category: MAPErrorCategory;
+  message: string;               // Human-readable
+
+  details?: {
+    agentId?: string;
+    messageId?: string;
+    method?: string;
+    retryable?: boolean;
+    retryAfter?: number;
+    recoveryHint?: string;
+  };
+
+  traceId?: string;
+  timestamp?: number;
+}
+```
+
+### Error Codes
+
+```typescript
+// Protocol errors (-32xxx range, JSON-RPC compatible)
+PARSE_ERROR: -32700,
+INVALID_REQUEST: -32600,
+METHOD_NOT_FOUND: -32601,
+INVALID_PARAMS: -32602,
+INTERNAL_ERROR: -32603,
+
+// Authentication errors (1xxx)
+AUTH_REQUIRED: 1000,
+AUTH_FAILED: 1001,
+AUTH_EXPIRED: 1002,
+PERMISSION_DENIED: 1003,
+
+// Routing errors (2xxx)
+AGENT_NOT_FOUND: 2000,
+AGENT_STOPPED: 2001,
+AGENT_BUSY: 2002,
+DELIVERY_FAILED: 2006,
+DELIVERY_TIMEOUT: 2007,
+
+// Agent lifecycle errors (3xxx)
+AGENT_EXISTS: 3000,
+INVALID_PARENT: 3001,
+HIERARCHY_CYCLE: 3002,
+MAX_AGENTS_EXCEEDED: 3003,
+
+// Resource errors (4xxx)
+RATE_LIMITED: 4000,
+QUOTA_EXCEEDED: 4001,
+BUFFER_OVERFLOW: 4002,
+
+// Federation errors (5xxx)
+PEER_UNREACHABLE: 5000,
+PEER_TIMEOUT: 5001,
+PEER_REJECTED: 5002,
+```
+
+---
+
+## Agent Failure Modes
+
+```
+1. Graceful Shutdown
+   Agent: sends shutdown intent
+   Server: drains queue, notifies parent, cleans up
+   Recovery: None needed (intentional)
+
+2. Crash (Unexpected Termination)
+   Detection: Heartbeat timeout, process exit
+   Server: Marks stopped, notifies parent, orphan handling
+   Recovery: Restart with same ID or spawn replacement
+
+3. Hang (Unresponsive)
+   Detection: Request timeout, no heartbeat
+   Server: Marks blocked, notifies parent
+   Recovery: Force restart or manual intervention
+
+4. Error Loop (Repeated Failures)
+   Detection: Error rate threshold exceeded
+   Server: Circuit breaker, reduce routing
+   Recovery: Exponential backoff restart
+```
+
+### Orphan Handling Policy
+
+```typescript
+interface OrphanPolicy {
+  tasks: "reassign" | "return_to_parent" | "fail" | "hold";
+  children: "cascade_stop" | "reparent" | "orphan";
+  messages: "drop" | "bounce" | "redirect";
+}
+```
+
+---
+
+## Connection Failures
+
+### Reconnection Protocol
+
+```
+Client                                    Server
+   │                                         │
+   │◄─────── Connection Lost ───────────────│
+   │                                         │
+   │         (backoff: 1s, 2s, 4s, 8s...)   │
+   │                                         │
+   │─────── Reconnect Attempt ─────────────►│
+   │                                         │
+   │◄────── Connection Accept ──────────────│
+   │                                         │
+   │─────── map/reconnect ─────────────────►│
+   │         { lastEventId, subscriptions } │
+   │                                         │
+   │◄────── Reconnect Response ─────────────│
+   │         { missedEvents, newState }     │
+```
+
+---
+
+## Circuit Breakers
+
+### Per-Agent Circuit Breaker
+
+```typescript
+interface CircuitBreakerState {
+  agentId: string;
+  state: "closed" | "open" | "half-open";
+
+  failureThreshold: number;
+  successThreshold: number;
+  timeout: number;
+
+  failureCount: number;
+  successCount: number;
+  lastFailure: number;
+  lastStateChange: number;
+}
+```
+
+---
+
+## Retry Policies
+
+```typescript
+interface RetryPolicy {
+  maxAttempts: number;
+  backoff: {
+    type: "exponential" | "linear" | "constant";
+    initial: number;
+    max: number;
+    multiplier?: number;
+  };
+  retryableErrors: number[];
+  nonRetryableErrors: number[];
+}
+
+// Default policy
+const DEFAULT_RETRY: RetryPolicy = {
+  maxAttempts: 3,
+  backoff: {
+    type: "exponential",
+    initial: 1000,
+    max: 30000,
+    multiplier: 2
+  },
+  retryableErrors: [2002, 2007, 4000, 5001],
+  nonRetryableErrors: [2000, 2001, 1003]
+};
+```
+
+---
+
+## Error Reporting & Observability
+
+### Distributed Tracing Integration
+
+```typescript
+interface MAPTraceContext {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+
+  // W3C Trace Context compatible
+  traceparent?: string;
+  tracestate?: string;
+}
+```
+
+---
+
+## Open Questions
+
+1. **Dead letter queue**: Should undeliverable messages go to a DLQ?
+2. **Error aggregation**: How to prevent error storms from overwhelming monitoring?
+3. **Automatic recovery**: How much should the protocol auto-heal vs require intervention?
+4. **Consistency model**: What consistency guarantees during partition recovery?
+5. **Error budget**: Should there be SLO-style error budgets in the protocol?

package/references/multi-agent-protocol/docs/05-connection-model.md

@@ -0,0 +1,244 @@
+# MAP Connection Model & Client Patterns
+
+This spec details how clients connect to MAP systems, the flexibility of subscription patterns, and how the protocol supports various usage modes.
+
+## Design Principles
+
+1. **Single protocol, multiple patterns**: Same wire protocol supports ACP-like single-agent focus through full system observation
+2. **Subscription-driven visibility**: What you see depends on what you subscribe to
+3. **SDK, not protocol, handles conversion**: Protocol stays simple; SDK provides utilities for common patterns
+4. **Multi-agent system is the endpoint**: Clients connect to the system, not individual agents
+
+---
+
+## Connection Lifecycle
+
+### Phase 1: Transport Connection
+
+```
+Client                                    MAP System
+   │                                          │
+   │─────── Transport Connect ───────────────►│
+   │        (WebSocket, stdio, etc.)          │
+   │                                          │
+   │◄────── Transport Accept ────────────────│
+   │                                          │
+```
+
+### Phase 2: MAP Handshake
+
+```typescript
+// Client sends connect request
+{
+  "method": "map/connect",
+  "params": {
+    "clientId": "client_001",
+    "clientInfo": {
+      "name": "my-dashboard",
+      "version": "1.0.0"
+    },
+    "protocolVersion": "2025-01-01",
+    "requestedCapabilities": {
+      "streaming": true,
+      "maxSubscriptions": 10,
+      "federation": false
+    },
+    "auth": {
+      "method": "bearer",
+      "token": "..."
+    }
+  }
+}
+```
+
+---
+
+## Client Types
+
+### Operator Client
+
+Full control over the system.
+
+**Typical permissions:**
+- Full visibility to all agents, scopes, events
+- Can send messages to any agent
+- Can register/unregister agents
+- Can steer agents (inject context)
+- Can create/delete scopes
+
+### Observer Client
+
+Read-only visibility into the system.
+
+**Typical permissions:**
+- Full or scoped visibility
+- Cannot send messages
+- Cannot modify agents or scopes
+- Useful for dashboards, monitoring
+
+### Agent Client
+
+An agent connecting to participate in the system.
+
+**Typical permissions:**
+- Visibility scoped to hierarchy/relationships
+- Can send messages to permitted agents
+- Receives messages addressed to itself
+- Cannot see full system structure (unless permitted)
+
+---
+
+## Subscription Patterns
+
+### Pattern 1: Single-Agent Focus (ACP-like)
+
+```typescript
+await map.subscribe({
+  filter: { agents: ["agent_001"] },
+  streams: ["messages", "state"]
+});
+```
+
+### Pattern 2: Multi-Agent Dashboard
+
+```typescript
+await map.subscribe({
+  filter: { agents: ["worker_001", "worker_002", "coordinator"] },
+  streams: ["messages", "state"]
+});
+```
+
+### Pattern 3: Role-Based Observation
+
+```typescript
+await map.subscribe({
+  filter: { roles: ["worker"] },
+  streams: ["messages", "state"]
+});
+```
+
+### Pattern 4: Full System Observation
+
+```typescript
+await map.subscribe({
+  filter: {},  // Empty filter = no filtering
+  streams: ["messages", "state", "structure"]
+});
+```
+
+### Pattern 5: Multiple Subscriptions
+
+```typescript
+// Subscription 1: High-priority messages only
+const urgentSub = await map.subscribe({
+  filter: { messagePriorities: ["urgent", "high"] },
+  streams: ["messages"]
+});
+
+// Subscription 2: All state changes
+const stateSub = await map.subscribe({
+  filter: {},
+  streams: ["state"]
+});
+```
+
+---
+
+## SDK Utilities
+
+### ACP Session Adapter
+
+```typescript
+// Create ACP-compatible session from MAP connection
+const session = mapSdk.createACPSession(connection, "agent_001");
+
+// Now use ACP-like API
+await session.prompt("Hello, world");
+```
+
+### Stream Aggregator
+
+```typescript
+// Combine multiple subscriptions into one stream
+const aggregated = mapSdk.aggregateStreams([sub1, sub2, sub3]);
+
+for await (const event of aggregated) {
+  console.log(event.subscriptionId, event.event);
+}
+```
+
+### Agent Proxy
+
+```typescript
+// Create a proxy object for an agent
+const agent = mapSdk.createAgentProxy(connection, "agent_001");
+
+// Direct method calls become messages
+await agent.send({ type: "task", data: "..." });
+
+// State is automatically updated
+console.log(agent.state);  // "busy"
+```
+
+---
+
+## Connection State Management
+
+```
+┌──────────┐  connect   ┌────────────┐  ready    ┌─────────┐
+│ INITIAL  │ ─────────► │ CONNECTING │ ────────► │ ACTIVE  │
+└──────────┘            └────────────┘           └────┬────┘
+                                                      │
+     ┌────────────────────────────────────────────────┤
+     │                                                │
+     │  disconnect                            error   │
+     ▼                                                ▼
+┌──────────┐                                 ┌────────────┐
+│ CLOSED   │ ◄─────────────────────────────  │ RECONNECT  │
+└──────────┘        max retries              └────────────┘
+                    exceeded
+```
+
+---
+
+## Capability Negotiation
+
+### Client Capabilities
+
+```typescript
+interface MAPClientCapabilities {
+  streaming: boolean;
+  maxConcurrentStreams?: number;
+  maxSubscriptions?: number;
+  maxMessageSize?: number;
+  supportedEncodings?: string[];
+  federation?: boolean;
+  replay?: boolean;
+}
+```
+
+### System Capabilities
+
+```typescript
+interface MAPSystemCapabilities {
+  protocolVersions: string[];
+  streaming: boolean;
+  federation: boolean;
+  replay: boolean;
+  replayWindow?: number;
+  maxSubscriptions: number;
+  maxMessageSize: number;
+  maxConcurrentConnections: number;
+  extensions?: string[];
+}
+```
+
+---
+
+## Open Questions
+
+1. **Session affinity**: Should subscriptions be tied to connection or transferable?
+2. **Subscription limits**: Per-connection or per-client (across reconnects)?
+3. **Capability versioning**: How to handle capability changes across protocol versions?
+4. **Auth refresh**: How to handle token expiration during long-lived connections?
+5. **Partial visibility**: Can a client request "all agents I can see" without knowing IDs upfront?

package/references/multi-agent-protocol/docs/06-visibility-permissions.md

@@ -0,0 +1,243 @@
+# MAP Visibility & Permission Model
+
+This spec details how MAP controls visibility and permissions at multiple levels: system, client, scope, and agent.
+
+## Design Principles
+
+1. **Layered control**: Permissions are checked at multiple levels, most restrictive wins
+2. **Explicit over implicit**: Default to restricted, explicitly grant access
+3. **Separation of concerns**: Client permissions vs agent permissions are distinct
+4. **Flexibility**: System implementations can choose how strict to be
+
+---
+
+## Visibility Layers
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Visibility Stack                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  LAYER 4: Agent Permissions                              │   │
+│  │  What can this agent see/do within its allowed scope?   │   │
+│  └────────────────────────────┬────────────────────────────┘   │
+│                               │                                 │
+│  ┌────────────────────────────▼────────────────────────────┐   │
+│  │  LAYER 3: Scope Permissions                              │   │
+│  │  What's visible within this scope? Who can see it?      │   │
+│  └────────────────────────────┬────────────────────────────┘   │
+│                               │                                 │
+│  ┌────────────────────────────▼────────────────────────────┐   │
+│  │  LAYER 2: Client Permissions                             │   │
+│  │  What can this client see/do in the system?             │   │
+│  └────────────────────────────┬────────────────────────────┘   │
+│                               │                                 │
+│  ┌────────────────────────────▼────────────────────────────┐   │
+│  │  LAYER 1: System Configuration                           │   │
+│  │  What does the system expose at all?                    │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+
+Evaluation: Check Layer 1 → Layer 2 → Layer 3 → Layer 4
+Result: Most restrictive wins (all layers must allow)
+```
+
+---
+
+## Layer 1: System Configuration
+
+```typescript
+interface MAPSystemConfig {
+  exposure: {
+    agents: {
+      publicByDefault: boolean;
+      publicAgents: string[];
+      hiddenAgents: string[];
+    };
+    events: {
+      exposedTypes: string[];
+      hiddenTypes: string[];
+    };
+    scopes: {
+      publicByDefault: boolean;
+      publicScopes: string[];
+      hiddenScopes: string[];
+    };
+  };
+  limits: {
+    maxConnections: number;
+    maxConnectionsPerClient: number;
+    maxSubscriptionsPerConnection: number;
+  };
+  anonymousPermissions: MAPClientPermissions;
+}
+```
+
+---
+
+## Layer 2: Client Permissions
+
+```typescript
+interface MAPClientPermissions {
+  visibility: {
+    agents: "all" | "none" | { include: string[] } | { roles: string[] };
+    scopes: "all" | "none" | { include: string[] };
+    events: "all" | "none" | { include: string[] };
+    structure: boolean;
+  };
+
+  actions: {
+    sendMessages: boolean | { to: MAPAddress[]; priorities: string[] };
+    registerAgents: boolean | { roles: string[]; maxAgents: number };
+    unregisterAgents: boolean | { own: boolean; any: boolean };
+    createScopes: boolean;
+    deleteScopes: boolean | { own: boolean };
+    modifyScopes: boolean | { own: boolean; member: boolean };
+    steerAgents: boolean | { agents: string[]; methods: string[] };
+    federationConnect: boolean;
+  };
+
+  limits: {
+    subscriptions: number;
+    messagesPerMinute: number;
+    agentsRegistered: number;
+    scopesCreated: number;
+  };
+}
+```
+
+---
+
+## Layer 3: Scope Permissions
+
+```typescript
+interface MAPScopePermissions {
+  discoverability: "public" | "members" | "owners";
+  messageVisibility: "public" | "members" | "participants";
+  joinPolicy: "open" | "invite" | "owner-invite" | "closed";
+  sendPolicy: "anyone" | "members" | "owners";
+  inheritFrom?: string;
+}
+```
+
+---
+
+## Layer 4: Agent Permissions
+
+```typescript
+interface MAPAgentPermissions {
+  canSee: {
+    agents: "all" | "hierarchy" | "scoped" | "direct" | { include: string[] };
+    scopes: "all" | "member" | { include: string[] };
+    structure: "full" | "local" | "none";
+  };
+
+  canMessage: {
+    agents: "all" | "hierarchy" | "scoped" | { include: string[] };
+    scopes: "all" | "member" | { include: string[] };
+  };
+
+  acceptsFrom: {
+    agents: "all" | "hierarchy" | "scoped" | { include: string[] };
+    clients: "all" | "none" | { include: string[] };
+    systems: "all" | "none" | { include: string[] };
+  };
+
+  capabilities: {
+    registerAgents: boolean;
+    createScopes: boolean;
+    steerAgents: boolean;
+  };
+}
+```
+
+---
+
+## Permission Resolution
+
+```typescript
+function canPerformAction(
+  client: MAPClient,
+  agent: MAPAgent | null,
+  action: MAPAction
+): boolean {
+  // Layer 1: System allows?
+  if (!systemAllows(action)) return false;
+
+  // Layer 2: Client permissions allow?
+  if (!clientAllows(client, action)) return false;
+
+  // Layer 3: Scope permissions allow?
+  if (action.scope && !scopeAllows(action.scope, client, agent, action)) {
+    return false;
+  }
+
+  // Layer 4: Agent permissions allow?
+  if (agent && !agentAllows(agent, action)) {
+    return false;
+  }
+
+  return true;
+}
+```
+
+---
+
+## Dynamic Permissions
+
+Permissions can change during runtime:
+
+```typescript
+// System can update client permissions
+{
+  "method": "map/permissions/update",
+  "params": {
+    "clientId": "client_001",
+    "permissions": {
+      "actions": {
+        "steerAgents": true
+      }
+    }
+  }
+}
+```
+
+---
+
+## Permission Events
+
+```typescript
+type MAPPermissionEvent =
+  | { type: "permissions.client.updated"; clientId: string; changes: ... }
+  | { type: "permissions.agent.updated"; agentId: string; changes: ... }
+  | { type: "permissions.scope.updated"; scopeId: string; changes: ... }
+  | { type: "permissions.denied"; action: string; reason: string };
+```
+
+---
+
+## Security Considerations
+
+### Principle of Least Privilege
+
+- Default to restricted permissions
+- Grant only what's needed
+- Regularly audit permission grants
+
+### Permission Escalation Prevention
+
+- Agents cannot grant permissions they don't have
+- Clients cannot modify their own permissions
+- System enforces capability ceilings
+
+---
+
+## Open Questions
+
+1. **Inheritance**: Should agent permissions inherit from parent by default?
+2. **Temporary grants**: Time-limited permission grants?
+3. **Delegation**: Can agents delegate their permissions to others?
+4. **Groups**: Should there be permission groups/roles for clients?
+5. **Revocation**: Immediate revocation or graceful wind-down?