macro-agent 0.0.13 → 0.0.15

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

@@ -0,0 +1,136 @@
+---
+title: Home
+layout: home
+nav_order: 1
+description: "Multi-Agent Protocol (MAP) - A JSON-RPC based protocol for observing, coordinating, and routing messages within multi-agent AI systems."
+permalink: /
+---
+
+# Multi-Agent Protocol (MAP)
+{: .fs-9 }
+
+A JSON-RPC based protocol for observing, coordinating, and routing messages within multi-agent AI systems.
+{: .fs-6 .fw-300 }
+
+[Get Started](/multi-agent-protocol/getting-started/){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[View on GitHub](https://github.com/multi-agent-protocol/multi-agent-protocol){: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+## Why MAP?
+
+Unlike protocols designed for single-agent interaction (ACP) or peer-to-peer agent delegation (A2A), MAP provides a **window into** a multi-agent system with visibility into its internal structure, agent relationships, and message flows.
+
+{: .highlight }
+MAP is the protocol for building **observable, coordinated** multi-agent systems.
+
+### Key Features
+
+| Feature | Description |
+|:--------|:------------|
+| **Real-time Streaming** | Subscribe to events with backpressure support |
+| **Auto-reconnection** | Exponential backoff with subscription restoration |
+| **Permission System** | 4-layer access control (system, participant, scope, agent) |
+| **Federation** | Connect multiple MAP systems with envelope-based routing |
+| **Causal Ordering** | Events released in dependency order |
+
+---
+
+## Protocol Landscape
+
+| 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 |
+
+---
+
+## Quick Example
+
+```typescript
+import { MAPServer } from "@multi-agent-protocol/sdk/server";
+import { ClientConnection, AgentConnection } from "@multi-agent-protocol/sdk";
+
+// Create a MAP server
+const server = new MAPServer({ name: "MyServer" });
+
+// Register an agent
+const agent = new AgentConnection(stream, {
+  name: "Worker",
+  role: "processor"
+});
+await agent.connect();
+
+// Subscribe to events from a client
+const client = new ClientConnection(stream, { name: "Dashboard" });
+await client.connect();
+
+const subscription = await client.subscribe({
+  eventTypes: ["agent.*"]
+});
+
+for await (const event of subscription) {
+  console.log(event.type, event.data);
+}
+```
+
+---
+
+## Three Participant Types
+
+```mermaid
+flowchart TB
+    subgraph Server["MAP Server"]
+        EventBus["EventBus"]
+        Agents["Agents"]
+        Scopes["Scopes"]
+    end
+
+    Agent1["Agent"] --> Server
+    Client["Client"] --> Server
+    Agent2["Agent"] --> Server
+```
+
+| Type | Role | Capabilities |
+|:-----|:-----|:-------------|
+| **Agent** | Worker that processes tasks | Register, join scopes, send/receive messages |
+| **Client** | Observer and requester | Subscribe to events, query state, send messages |
+| **Gateway** | Federation bridge | Route between MAP systems |
+
+---
+
+## Protocol Methods
+
+The protocol defines **27 methods** across three tiers:
+
+### Core (Required)
+`map/connect`, `map/disconnect`, `map/send`, `map/subscribe`, `map/unsubscribe`, `map/agents/list`, `map/agents/get`
+
+### Structure (Recommended)
+Agent lifecycle (`register`, `spawn`, `unregister`, `update`, `stop`, `suspend`, `resume`), scope management (`scopes/create`, `join`, `leave`), and structure queries
+
+### Extensions (Optional)
+Federation (`federation/connect`, `federation/route`), session management, and steering (`map/inject`)
+
+---
+
+## Getting Started
+
+<div class="code-example" markdown="1">
+**Installation**
+```bash
+npm install @multi-agent-protocol/sdk
+```
+</div>
+
+Ready to build? Check out the [Getting Started Guide](/multi-agent-protocol/getting-started/) to run your first MAP server in 5 minutes.
+
+---
+
+## About
+
+Multi-Agent Protocol is open source and available under the [MIT License](https://github.com/multi-agent-protocol/multi-agent-protocol/blob/main/LICENSE).
+
+Created and maintained by the [sudocode](https://github.com/sudocode-ai) team.

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

@@ -0,0 +1,391 @@
+---
+title: Authentication
+parent: Protocol
+nav_order: 6
+description: "Authentication methods and flows"
+---
+
+# Authentication
+{: .no_toc }
+
+Authentication methods, negotiation flows, and security considerations.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Design Principles
+
+1. **Pluggable mechanisms** - Support multiple auth methods with a standard negotiation flow
+2. **Sensible defaults** - Built-in support for common methods (bearer tokens, API keys)
+3. **Transport-aware** - Acknowledge that some auth happens at transport layer (mTLS)
+4. **Optional for local** - No auth overhead for trusted local connections (stdio)
+5. **Federation-ready** - Credentials can carry claims for cross-server authentication
+
+---
+
+## Authentication Methods
+
+| Method | Description | Use Case |
+|:-------|:------------|:---------|
+| `none` | No authentication | Local subprocess agents, development |
+| `bearer` | Bearer token (JWT or opaque) | OAuth2, IdP integration, M2M tokens |
+| `api-key` | Simple API key | Simple integrations, internal services |
+| `mtls` | Mutual TLS (transport layer) | High-security service-to-service |
+
+### Extension Methods
+
+Custom authentication methods use the `x-` prefix:
+
+```
+x-custom-auth
+x-kerberos
+x-saml
+```
+
+Servers MUST reject unknown methods without the `x-` prefix.
+
+---
+
+## Wire Protocol
+
+### Server Authentication Capabilities
+
+Servers advertise requirements in the connect response:
+
+```typescript
+interface ServerAuthCapabilities {
+  /** Supported authentication methods (in preference order) */
+  methods: AuthMethod[];
+
+  /** Is authentication required to proceed? */
+  required: boolean;
+
+  /** OAuth2 authorization server metadata URL */
+  oauth2MetadataUrl?: string;
+
+  /** JWKS URL for local JWT verification */
+  jwksUrl?: string;
+
+  /** Realm identifier for this server */
+  realm?: string;
+}
+```
+
+### Client Credentials
+
+```typescript
+interface AuthCredentials {
+  /** The authentication method being used */
+  method: AuthMethod;
+
+  /** The credential value (token, API key, etc.) */
+  credential?: string;
+
+  /** Method-specific additional data */
+  metadata?: Record<string, unknown>;
+}
+```
+
+### Authentication Result
+
+```typescript
+interface AuthResult {
+  success: boolean;
+
+  principal?: {
+    id: string;
+    issuer?: string;
+    claims?: Record<string, unknown>;
+  };
+
+  error?: {
+    code: AuthErrorCode;
+    message: string;
+  };
+}
+
+type AuthErrorCode =
+  | 'invalid_credentials'
+  | 'expired'
+  | 'insufficient_scope'
+  | 'method_not_supported'
+  | 'auth_required';
+```
+
+---
+
+## Connection Flows
+
+### Flow 1: Auth Provided Upfront (Recommended)
+
+When the client knows the server's auth requirements:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+
+    Client->>Server: map/connect {participantType, auth}
+    Server-->>Client: connect response {session, principal}
+```
+
+```typescript
+// Request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "map/connect",
+  "params": {
+    "protocolVersion": 1,
+    "participantType": "client",
+    "name": "my-client",
+    "auth": {
+      "method": "bearer",
+      "credential": "eyJhbGciOiJSUzI1NiIs..."
+    }
+  }
+}
+
+// Response (success)
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "sessionId": "session_01ABC",
+    "participantId": "client_01XYZ",
+    "principal": {
+      "id": "user_123",
+      "issuer": "https://auth.example.com",
+      "claims": { "scope": "read write" }
+    }
+  }
+}
+```
+
+### Flow 2: Auth Negotiation
+
+When the client doesn't know auth requirements:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+
+    Client->>Server: map/connect {participantType}
+    Server-->>Client: auth_required {methods, required}
+    Client->>Server: map/authenticate {method, credential}
+    Server-->>Client: auth result {success, session, principal}
+```
+
+### Flow 3: No Authentication
+
+For trusted local connections:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+
+    Client->>Server: map/connect {participantType}
+    Server-->>Client: connect response {session}
+```
+
+---
+
+## Method-Specific Details
+
+### Bearer Tokens (JWT)
+
+```typescript
+// Standard JWT claims used by MAP
+interface MAPJWTClaims {
+  sub: string;           // Subject (principal ID)
+  iss: string;           // Issuer
+  aud: string | string[];// Audience (MAP server ID)
+  exp: number;           // Expiration
+  iat: number;           // Issued at
+  nbf?: number;          // Not before
+
+  // MAP-specific claims
+  "map:permissions"?: MAPPermissions;
+  "map:roles"?: string[];
+  "map:scopes"?: string[];
+}
+```
+
+### API Keys
+
+```typescript
+// API key format
+interface MAPApiKey {
+  prefix: string;        // e.g., "map_"
+  keyId: string;         // Key identifier
+  secret: string;        // Secret portion
+
+  // Combined format: map_keyId_secret
+}
+
+// Header format
+Authorization: ApiKey map_abc123_secretxyz
+```
+
+### Mutual TLS
+
+Authentication happens at transport layer:
+
+```typescript
+interface MTLSAuth {
+  method: "mtls";
+  metadata: {
+    clientCertificate: {
+      subject: string;
+      issuer: string;
+      fingerprint: string;
+      validFrom: string;
+      validTo: string;
+    };
+  };
+}
+```
+
+---
+
+## Token Refresh
+
+### Proactive Refresh
+
+Client refreshes before expiration:
+
+```typescript
+{
+  "method": "map/authenticate",
+  "params": {
+    "method": "bearer",
+    "credential": "new_access_token",
+    "refresh": true
+  }
+}
+```
+
+### Server-Initiated Refresh
+
+Server can request reauthentication:
+
+```typescript
+// Server notification
+{
+  "method": "map/auth.expiring",
+  "params": {
+    "expiresIn": 300,  // seconds
+    "reason": "token_expiring"
+  }
+}
+
+// Client responds with new credentials
+{
+  "method": "map/authenticate",
+  "params": {
+    "method": "bearer",
+    "credential": "refreshed_token"
+  }
+}
+```
+
+---
+
+## Federation Authentication
+
+### Trust Establishment
+
+```typescript
+interface FederationAuth {
+  // Peer identification
+  peerId: string;
+  peerCertificate?: string;
+
+  // Trust method
+  trustMethod: "mtls" | "signed_tokens" | "shared_secret";
+
+  // Token signing for cross-system calls
+  tokenSigning?: {
+    algorithm: string;
+    keyId: string;
+  };
+}
+```
+
+### Cross-System Token Propagation
+
+```typescript
+// Message with propagated auth context
+{
+  "method": "map/federation/send",
+  "params": {
+    "peerId": "system_beta",
+    "message": { ... },
+    "authContext": {
+      "originalPrincipal": "user_123",
+      "originalIssuer": "system_alpha",
+      "delegationChain": ["system_alpha"],
+      "signature": "..."
+    }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Authentication Errors
+
+| Code | Error | Recovery |
+|:-----|:------|:---------|
+| 1000 | AUTH_REQUIRED | Provide credentials |
+| 1001 | AUTH_FAILED | Check credentials |
+| 1002 | AUTH_EXPIRED | Refresh token |
+| 1003 | PERMISSION_DENIED | Request additional scope |
+
+### Error Response
+
+```typescript
+{
+  "error": {
+    "code": 1001,
+    "message": "Authentication failed",
+    "data": {
+      "category": "auth",
+      "reason": "invalid_signature",
+      "hint": "Token signature verification failed"
+    }
+  }
+}
+```
+
+---
+
+## Security Considerations
+
+{: .warning }
+> Always use TLS in production environments. Never transmit credentials over unencrypted connections.
+
+### Best Practices
+
+1. **Short-lived tokens** - Use access tokens with short expiration
+2. **Secure storage** - Never log or store credentials in plain text
+3. **Scope limitation** - Request minimum necessary permissions
+4. **Token rotation** - Rotate API keys and refresh tokens regularly
+5. **Audit logging** - Log authentication events for security monitoring
+
+---
+
+## Next Steps
+
+- [Permissions](./permissions.html) - 4-layer permission model
+- [Federation](./federation.html) - Cross-system authentication