macro-agent 0.1.1 → 0.1.3

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

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

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

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