macro-agent 0.0.11 → 0.0.12

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

@@ -1,376 +0,0 @@
----
-title: Connection Model
-parent: Protocol
-nav_order: 4
-description: "Connection lifecycle and client patterns"
----
-
-# Connection Model
-{: .no_toc }
-
-How clients connect to MAP systems and the flexibility of subscription patterns.
-{: .fs-6 .fw-300 }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
----
-
-## 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
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant MAP System
-
-    Client->>MAP System: Transport Connect (WebSocket, stdio, etc.)
-    MAP System-->>Client: 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",
-      "credential": "..."
-    }
-  }
-}
-
-// Server responds
-{
-  "result": {
-    "sessionId": "session_abc123",
-    "participantId": "client_001",
-    "serverCapabilities": {
-      "streaming": true,
-      "maxSubscriptions": 100,
-      "federation": true,
-      "replay": true
-    },
-    "systemInfo": {
-      "name": "MAP Server",
-      "version": "1.0.0",
-      "agents": 15
-    }
-  }
-}
-```
-
----
-
-## 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
-
-```typescript
-const client = new ClientConnection(stream, {
-  name: "operator-console",
-  permissions: "operator"
-});
-```
-
-### 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
-
-```typescript
-const client = new ClientConnection(stream, {
-  name: "monitoring-dashboard",
-  permissions: "observer"
-});
-```
-
-### 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)
-
-```typescript
-const agent = new AgentConnection(stream, {
-  name: "worker-agent",
-  role: "processor"
-});
-```
-
----
-
-## Subscription Patterns
-
-### Pattern 1: Single-Agent Focus (ACP-like)
-
-Observe only one agent:
-
-```typescript
-await client.subscribe({
-  filter: { agents: ["agent_001"] },
-  streams: ["messages", "state"]
-});
-```
-
-### Pattern 2: Multi-Agent Dashboard
-
-Observe specific agents:
-
-```typescript
-await client.subscribe({
-  filter: {
-    agents: ["worker_001", "worker_002", "coordinator"]
-  },
-  streams: ["messages", "state"]
-});
-```
-
-### Pattern 3: Role-Based Observation
-
-Observe all agents with specific roles:
-
-```typescript
-await client.subscribe({
-  filter: { roles: ["worker"] },
-  streams: ["messages", "state"]
-});
-```
-
-### Pattern 4: Full System Observation
-
-See everything:
-
-```typescript
-await client.subscribe({
-  filter: {},  // Empty filter = no filtering
-  streams: ["messages", "state", "structure"]
-});
-```
-
-### Pattern 5: Hierarchical Observation
-
-Observe an agent and all its descendants:
-
-```typescript
-await client.subscribe({
-  filter: { subtree: "coordinator_001" },
-  streams: ["messages", "state", "tasks"]
-});
-```
-
----
-
-## Connection State Management
-
-```mermaid
-stateDiagram-v2
-    [*] --> INITIAL
-    INITIAL --> CONNECTING: connect
-    CONNECTING --> ACTIVE: ready
-    CONNECTING --> CLOSED: handshake failure
-    ACTIVE --> CLOSED: disconnect
-    ACTIVE --> RECONNECT: error
-    RECONNECT --> ACTIVE: reconnect success
-    RECONNECT --> CLOSED: max retries exceeded
-    CLOSED --> [*]
-```
-
-### State Transitions
-
-| From | Event | To |
-|:-----|:------|:---|
-| INITIAL | `connect()` | CONNECTING |
-| CONNECTING | handshake success | ACTIVE |
-| CONNECTING | handshake failure | CLOSED |
-| ACTIVE | connection lost | RECONNECT |
-| ACTIVE | `disconnect()` | CLOSED |
-| RECONNECT | reconnect success | ACTIVE |
-| RECONNECT | max retries | CLOSED |
-
----
-
-## Reconnection
-
-### Automatic Reconnection
-
-```typescript
-const client = new ClientConnection(stream, {
-  name: "my-client",
-  reconnect: {
-    enabled: true,
-    maxAttempts: 5,
-    baseDelay: 1000,
-    maxDelay: 30000,
-    backoffMultiplier: 2
-  }
-});
-```
-
-### Reconnection Protocol
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Server
-
-    Server--xClient: Connection Lost
-    Note over Client: Backoff: 1s, 2s, 4s, 8s...
-    Client->>Server: Reconnect Attempt
-    Server-->>Client: Connection Accept
-    Client->>Server: map/reconnect {sessionId, lastEventId}
-    Server-->>Client: Reconnect Response {restored, missedEvents}
-```
-
-### Session Restoration
-
-```typescript
-{
-  "method": "map/reconnect",
-  "params": {
-    "sessionId": "session_abc123",
-    "lastEventId": "evt_xyz789",
-    "subscriptions": ["sub_001", "sub_002"]
-  }
-}
-
-// Response
-{
-  "result": {
-    "restored": true,
-    "sessionId": "session_abc123",
-    "subscriptions": {
-      "sub_001": { "restored": true, "missedEvents": 15 },
-      "sub_002": { "restored": true, "missedEvents": 3 }
-    },
-    "replayAvailable": true
-  }
-}
-```
-
----
-
-## SDK Utilities
-
-### ACP Session Adapter
-
-Convert MAP connection to ACP-compatible session:
-
-```typescript
-// Create ACP-compatible session from MAP connection
-const session = client.createACPSession("agent_001");
-
-// Now use ACP-like API
-await session.prompt("Hello, world");
-for await (const chunk of session.stream()) {
-  console.log(chunk);
-}
-```
-
-### Stream Aggregator
-
-Combine multiple subscriptions:
-
-```typescript
-const aggregated = client.aggregateStreams([sub1, sub2, sub3]);
-
-for await (const event of aggregated) {
-  console.log(event.subscriptionId, event.event);
-}
-```
-
-### Agent Proxy
-
-Create a proxy object for an agent:
-
-```typescript
-const agent = client.createAgentProxy("agent_001");
-
-// Direct method calls become messages
-await agent.send({ type: "task", data: "..." });
-
-// State is automatically updated
-console.log(agent.state);  // "busy"
-
-// Events are surfaced
-agent.on("stateChange", (prev, curr) => {
-  console.log(`State: ${prev} → ${curr}`);
-});
-```
-
----
-
-## Capability Negotiation
-
-Clients and servers negotiate capabilities during connection:
-
-```typescript
-interface CapabilityNegotiation {
-  // Client requests
-  requested: {
-    streaming: boolean;
-    maxSubscriptions: number;
-    federation: boolean;
-    replay: boolean;
-  };
-
-  // Server grants (may be less than requested)
-  granted: {
-    streaming: boolean;
-    maxSubscriptions: number;
-    federation: boolean;
-    replay: boolean;
-  };
-}
-```
-
----
-
-## Next Steps
-
-- [Error Handling](./error-handling.html) - Handling connection failures
-- [Authentication](./authentication.html) - Authentication flows

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

@@ -1,284 +0,0 @@
----
-title: Design
-parent: Protocol
-nav_order: 1
-description: "MAP protocol design philosophy and architecture"
----
-
-# Protocol Design
-{: .no_toc }
-
-Core architecture, design philosophy, and the unified participant model.
-{: .fs-6 .fw-300 }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
----
-
-## Design Philosophy
-
-**Primary Abstraction**: The agent and its relationships to other agents, followed by the messages that flow between them.
-
-**Core Principle**: MAP treats the multi-agent system as a **transparent, observable entity** rather than an opaque black box. Clients connecting via MAP can see (with appropriate permissions) the internal structure and activity of the system.
-
-### Key Design Principles
-
-1. **Topology is configuration, not protocol** - The same protocol supports hierarchical orchestration (like Claude Code's Task agents) and peer collaboration
-2. **Unified messaging with metadata** - One message type with metadata that specializes behavior (task delegation, peer messaging, broadcast)
-3. **Visibility is first-class** - Agents and scopes have explicit visibility settings; "parent-only" visibility enables hidden sub-agents
-4. **Lifecycle is descriptive, not prescriptive** - Protocol records lifecycle metadata; implementations decide how to enforce it
-5. **Extensibility at every layer** - States, lifecycle patterns, visibility levels, and message metadata are all extensible
-6. **Unified participant model** - Agents and clients speak the same protocol; difference is in capabilities and visibility, not in the wire format
-
----
-
-## What MAP Is NOT
-
-- **Not ACP**: ACP is client ↔ single agent. MAP is client ↔ multi-agent system.
-- **Not A2A**: A2A is peer agent ↔ peer agent (opaque). MAP is for internal systems with visibility.
-- **Not a replacement**: MAP complements ACP/A2A. Agents can use ACP for client interaction, A2A for external peers, and MAP for internal coordination.
-
----
-
-## Protocol Landscape
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                        Agent Protocol Ecosystem                              │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│   Protocol    Relationship           Visibility    Primary Use              │
-│   ────────    ────────────           ──────────    ───────────              │
-│   MCP         Agent → Tool           N/A           Tool invocation          │
-│   ACP         Client → Agent         Opaque        Single-agent sessions    │
-│   A2A         Agent → Agent (peer)   Opaque        Cross-org delegation     │
-│   MAP         Client → System        Transparent   Internal orchestration   │
-│               Agent → Agent (internal)                                      │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Integration Patterns
-
-**Pattern 1: MAP + ACP (Hybrid Client)**
-```
-Client uses ACP for single-agent focus, MAP for system awareness.
-The MAP SDK can convert MAP streams into ACP-compatible sessions.
-```
-
-**Pattern 2: MAP + A2A (Federated Systems)**
-```
-Internal coordination via MAP.
-External peer communication via A2A.
-Individual agents can participate in both.
-```
-
-**Pattern 3: MAP-to-MAP (System Federation)**
-```
-Two MAP systems can communicate via their exposed message channels.
-Each system remains internally transparent, externally opaque.
-```
-
----
-
-## Unified Participant Model
-
-A core design principle of MAP is that **agents and clients speak the same protocol**. The difference is not in the wire format, but in:
-
-- **Capabilities**: What actions they can perform
-- **Visibility**: What they can see
-- **Transport**: How they connect
-
-This enables:
-- Consistent semantics across all participants
-- Federation as a natural extension (remote agents are just participants)
-- Hierarchical composition (agents can be servers to their children)
-- Transport optimization without protocol changes
-
-### Participant Types
-
-```typescript
-interface MAPParticipant {
-  id: string;
-  type: "agent" | "client" | "system" | "gateway";
-
-  // What this participant can see
-  visibility: MAPParticipantVisibility;
-
-  // What this participant can do
-  capabilities: MAPParticipantCapabilities;
-
-  // How this participant is connected
-  transport: MAPTransport;
-
-  // Session information
-  session?: MAPSession;
-}
-```
-
-### Capability Matrix
-
-| Capability | Client | Agent | System | Gateway |
-|:-----------|:-------|:------|:-------|:--------|
-| canObserve | ✓ | ✓* | ✓ | ✓* |
-| canQuery | ✓ | ✓* | ✓ | ✓* |
-| canSend | ✓* | ✓ | ✓ | ✓ |
-| canReceive | ✗ | ✓ | ✓ | ✓ |
-| canBroadcast | ✗ | ✓* | ✓ | ✗ |
-| canSpawn | ✗ | ✓ | ✓ | ✗ |
-| canRegister | ✗ | ✓* | ✓ | ✗ |
-| canSteer | ✓* | ✓* | ✓ | ✗ |
-| canCreateScopes | ✗ | ✓* | ✓ | ✗ |
-
-✓ = default yes, ✗ = default no, * = depends on permissions
-{: .fs-2 }
-
----
-
-## Core Objects
-
-### Agent
-
-The fundamental unit in the system:
-
-```typescript
-interface MAPAgent {
-  id: string;
-  name?: string;
-
-  // Relationships
-  parent?: string;                    // Hierarchical parent
-  relationships?: MAPRelationship[];  // Other connections
-
-  // State (extensible)
-  state: MAPAgentState;
-
-  // Classification
-  role?: string;
-  scopes: string[];
-
-  // Visibility
-  visibility?: MAPVisibility;
-
-  // Lifecycle
-  lifecycle?: MAPAgentLifecycle;
-
-  // Metadata
-  metadata?: Record<string, unknown>;
-}
-
-type MAPAgentState =
-  | "registered"    // Known to system, not yet active
-  | "active"        // Running and responsive
-  | "busy"          // Active but processing
-  | "idle"          // Active but waiting
-  | "suspended"     // Paused, can be resumed
-  | "stopping"      // Shutting down gracefully
-  | "stopped"       // Terminated
-  | "failed";       // Error state
-```
-
-### Message
-
-Messages flow between agents:
-
-```typescript
-interface MAPMessage {
-  id: string;
-  from: string;
-  to: MAPAddress;
-  payload: unknown;
-  meta?: {
-    priority?: "low" | "normal" | "high" | "urgent";
-    delivery?: "inject" | "interrupt" | "queue" | "best-effort";
-    ttl?: number;
-    requireAck?: boolean;
-  };
-  timestamp: number;
-}
-```
-
-### Scope
-
-Logical groupings for agents:
-
-```typescript
-interface MAPScope {
-  id: string;
-  name?: string;
-  type: "room" | "topic" | "project" | "custom";
-  members: string[];
-  visibility?: MAPVisibility;
-  permissions?: MAPScopePermissions;
-}
-```
-
----
-
-## Hierarchical Composition
-
-Agents can be both clients (to their parent/system) and servers (to their children):
-
-```mermaid
-flowchart TB
-    Client["External Client<br/>(dashboard)"]
-
-    subgraph System["MAP System"]
-        Coordinator["Coordinator<br/>• Receives from client<br/>• Routes to children"]
-        WorkerA["Worker A<br/>• Participant<br/>• Has children"]
-        WorkerB["Worker B<br/>• Participant"]
-        SubAgent["Sub-agent<br/>• Leaf node<br/>(Claude Code pattern)"]
-    end
-
-    Client -->|"MAP (websocket)"| Coordinator
-    Coordinator -->|"MAP (inprocess)"| WorkerA
-    Coordinator -->|"MAP (inprocess)"| WorkerB
-    WorkerA -->|"MAP (stdio)"| SubAgent
-```
-
----
-
-## Transport Layer
-
-MAP is transport-agnostic. The protocol defines message format and semantics; the transport layer handles delivery.
-
-### Transport Interface
-
-```typescript
-interface MAPTransport {
-  type: string;
-
-  // Send a message or request
-  send(frame: MAPFrame): Promise<void>;
-
-  // Receive messages/events
-  receive(): AsyncIterable<MAPFrame>;
-
-  // Connection lifecycle
-  close(): Promise<void>;
-
-  // Connection state
-  state: "connecting" | "connected" | "disconnected" | "error";
-}
-```
-
-### Built-in Transport Bindings
-
-| Transport | Use Case | Framing |
-|:----------|:---------|:--------|
-| WebSocket | Remote clients, federation | JSON messages |
-| stdio | Subprocess agents (Claude Code) | NDJSON (newline-delimited) |
-| In-process | Co-located agents | Direct object passing |
-| HTTP + SSE | Stateless clients | POST + Server-Sent Events |
-
----
-
-## Next Steps
-
-- [Wire Protocol](./wire-protocol.html) - JSON-RPC message format
-- [Streaming](./streaming.html) - Event subscriptions and filtering
-- [Permissions](./permissions.html) - 4-layer visibility model