jarviscore-framework 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

jarviscore/docs/CUSTOMAGENT_GUIDE.md

@@ -11,16 +11,21 @@ CustomAgent lets you integrate your **existing agent code** with JarvisCore's ne
 
 1. [Prerequisites](#prerequisites)
 2. [Choose Your Mode](#choose-your-mode)
-3. [P2P Mode](#p2p-mode)
-4. [ListenerAgent (v0.3.0)](#listeneragent-v030) - API-first agents without run() loops
-5. [Distributed Mode](#distributed-mode)
-6. [Cognitive Discovery (v0.3.0)](#cognitive-discovery-v030) - Dynamic peer awareness for LLMs
-7. [FastAPI Integration (v0.3.0)](#fastapi-integration-v030) - 3-line setup with JarvisLifespan
+3. [P2P Mode](#p2p-mode) - Handler-based peer communication
+4. [Distributed Mode](#distributed-mode) - Workflow tasks + P2P
+5. [Cognitive Discovery (v0.3.0)](#cognitive-discovery-v030) - Dynamic peer awareness for LLMs
+6. [FastAPI Integration (v0.3.0)](#fastapi-integration-v030) - 3-line setup with JarvisLifespan
+7. [Framework Integration Patterns](#framework-integration-patterns) - aiohttp, Flask, Django
 8. [Cloud Deployment (v0.3.0)](#cloud-deployment-v030) - Self-registration for containers
 9. [API Reference](#api-reference)
 10. [Multi-Node Deployment](#multi-node-deployment)
 11. [Error Handling](#error-handling)
 12. [Troubleshooting](#troubleshooting)
+13. [Session Context Propagation (v0.3.2)](#session-context-propagation-v032) - Request tracking and metadata
+14. [Async Request Pattern (v0.3.2)](#async-request-pattern-v032) - Non-blocking parallel requests
+15. [Load Balancing Strategies (v0.3.2)](#load-balancing-strategies-v032) - Round-robin and random selection
+16. [Mesh Diagnostics (v0.3.2)](#mesh-diagnostics-v032) - Health monitoring and debugging
+17. [Testing with MockMesh (v0.3.2)](#testing-with-mockmesh-v032) - Unit testing patterns
 
 ---
 
@@ -102,7 +107,7 @@ class MyLLMClient:
 
 ### Quick Comparison
 
-| Feature | P2P Mode (CustomAgent) | P2P Mode (ListenerAgent) | Distributed Mode |
+| Feature | P2P Mode (CustomAgent) | P2P Mode (CustomAgent) | Distributed Mode |
 |---------|------------------------|--------------------------|------------------|
 | **Primary method** | `run()` - continuous loop | `on_peer_request()` handlers | `execute_task()` - on-demand |
 | **Communication** | Direct peer messaging | Handler-based (no loop) | Workflow orchestration |
@@ -110,7 +115,7 @@ class MyLLMClient:
 | **Coordination** | Agents self-coordinate | Framework handles loop | Framework coordinates |
 | **Supports workflows** | No | No | Yes |
 
-> **New in v0.3.0**: `ListenerAgent` lets you write P2P agents without managing the `run()` loop yourself. Just implement `on_peer_request()` and `on_peer_notify()` handlers.
+> **CustomAgent** includes built-in P2P handlers - just implement `on_peer_request()` and `on_peer_notify()`. No need to write your own `run()` loop.
 
 ---
 
@@ -118,6 +123,46 @@ class MyLLMClient:
 
 P2P mode is for agents that run continuously and communicate directly with each other.
 
+### v0.3.1 Update: Handler-Based Pattern
+
+**We've simplified P2P agents!** No more manual `run()` loops.
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    OLD vs NEW Pattern                          │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  ❌ OLD (v0.2.x) - Manual Loop                                 │
+│  ┌──────────────────────────────────────────────┐              │
+│  │ async def run(self):                         │              │
+│  │     while not self.shutdown_requested:       │              │
+│  │         msg = await self.peers.receive()     │ ← Polling    │
+│  │         if msg and msg.is_request:           │              │
+│  │             result = self.process(msg)       │              │
+│  │             await self.peers.respond(...)    │ ← Manual     │
+│  │         await asyncio.sleep(0.1)             │              │
+│  └──────────────────────────────────────────────┘              │
+│                                                                │
+│  ✅ NEW (v0.3.0+) - Handler-Based                              │
+│  ┌──────────────────────────────────────────────┐              │
+│  │ async def on_peer_request(self, msg):        │              │
+│  │     result = self.process(msg)               │              │
+│  │     return result                            │ ← Simple!    │
+│  └──────────────────────────────────────────────┘              │
+│         ▲                                                      │
+│         │                                                      │
+│         └─ Framework calls this automatically                 │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- ✅ **Less Code**: No boilerplate loops
+- ✅ **Simpler**: Just return your result
+- ✅ **Automatic**: Framework handles message dispatch
+- ✅ **Error Handling**: Built-in exception capture
+- ✅ **FastAPI Ready**: Works with `JarvisLifespan` out of the box
+
 ### Migration Overview
 
 ```
@@ -163,59 +208,89 @@ if __name__ == "__main__":
 
 ### Step 3: Modify Your Agent Code → `agents.py`
 
-Convert your existing class to inherit from `CustomAgent`:
+**🚨 IMPORTANT CHANGE (v0.3.0+)**: We've moved from `run()` loops to **handler-based** agents!
 
+#### ❌ OLD Pattern (Deprecated)
 ```python
-# agents.py (MODIFIED VERSION OF YOUR CODE)
-import asyncio
+# DON'T DO THIS ANYMORE!
+class ResearcherAgent(CustomAgent):
+    async def run(self):  # ❌ Manual loop
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=0.5)
+            if msg and msg.is_request:
+                result = self.llm.chat(f"Research: {msg.data['question']}")
+                await self.peers.respond(msg, {"response": result})
+            await asyncio.sleep(0.1)
+```
+**Problems**: Manual loops, boilerplate, error-prone
+
+#### ✅ NEW Pattern (Recommended)
+```python
+# agents.py (MODERN VERSION)
 from jarviscore.profiles import CustomAgent
 
 
 class ResearcherAgent(CustomAgent):
-    """Your agent, now framework-integrated."""
+    """Your agent, now framework-integrated with handlers."""
 
-    # NEW: Required class attributes for discovery
+    # Required class attributes for discovery
     role = "researcher"
     capabilities = ["research", "analysis"]
+    description = "Research specialist that gathers and synthesizes information"
 
     async def setup(self):
-        """NEW: Called once on startup. Move your __init__ logic here."""
+        """Called once on startup. Initialize your LLM here."""
         await super().setup()
         self.llm = MyLLMClient()  # Your existing initialization
 
-    async def run(self):
-        """NEW: Main loop - replaces your if __name__ == '__main__' block."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    query = msg.data.get("question", "")
-                    # YOUR EXISTING LOGIC:
-                    result = self.llm.chat(f"Research: {query}")
-                    await self.peers.respond(msg, {"response": result})
-            await asyncio.sleep(0.1)
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from other agents.
+        
+        This is called AUTOMATICALLY when another agent asks you a question.
+        No loops, no polling, no boilerplate!
+        """
+        query = msg.data.get("question", "")
+        
+        # YOUR EXISTING LOGIC:
+        result = self.llm.chat(f"Research: {query}")
+        
+        # Just return the data - framework handles the response
+        return {"response": result}
 
     async def execute_task(self, task: dict) -> dict:
         """
-        Required by base Agent class (@abstractmethod).
-
-        In P2P mode, your main logic lives in run(), not here.
-        This must exist because Python requires all abstract methods
-        to be implemented, or you get TypeError on instantiation.
+        Required by base Agent class for workflow mode.
+        
+        In pure P2P mode, your logic is in on_peer_request().
+        This is used when agent is part of a workflow pipeline.
         """
-        return {"status": "success", "note": "This agent uses run() for P2P mode"}
+        return {"status": "success", "note": "This agent uses handlers for P2P mode"}
 ```
 
 **What changed:**
 
-| Before | After |
-|--------|-------|
-| `class MyResearcher:` | `class ResearcherAgent(CustomAgent):` |
-| `def __init__(self):` | `async def setup(self):` + `await super().setup()` |
-| `if __name__ == "__main__":` | `async def run(self):` loop |
-| Direct method calls | Peer message handling |
+| Before (v0.2.x) | After (v0.3.0+) | Why? |
+|-----------------|-----------------|------|
+| `async def run(self):` with `while` loop | `async def on_peer_request(self, msg):` handler | Automatic dispatch, less boilerplate |
+| Manual `await self.peers.receive()` | Framework calls your handler | No polling needed |
+| Manual `await self.peers.respond(msg, data)` | Just `return data` | Simpler error handling |
+| `asyncio.create_task(agent.run())` | Not needed - handlers run automatically | Cleaner lifecycle |
+
+#### Migration Checklist (v0.2.x → v0.3.0+)
 
-> **Note**: This is a minimal example. For the full pattern with **LLM-driven peer communication** (where your LLM autonomously decides when to call other agents), see the [Complete Example](#complete-example-llm-driven-peer-communication) below.
+If you have existing agents using the `run()` loop pattern:
+
+- [ ] Replace `async def run(self):` with `async def on_peer_request(self, msg):`
+- [ ] Remove `while not self.shutdown_requested:` loop
+- [ ] Remove `msg = await self.peers.receive(timeout=0.5)` polling
+- [ ] Change `await self.peers.respond(msg, data)` to `return data`
+- [ ] Remove manual `asyncio.create_task(agent.run())` calls in main.py
+- [ ] Consider using `JarvisLifespan` for FastAPI integration (see Step 4)
+- [ ] Add `description` class attribute for better cognitive discovery
+- [ ] Use `get_cognitive_context()` instead of hardcoded peer lists
+
+> **Note**: The `run()` method is **still supported** for backward compatibility, but handlers are now the recommended approach. For the full pattern with **LLM-driven peer communication** (where your LLM autonomously decides when to call other agents), see the [Complete Example](#complete-example-llm-driven-peer-communication) below.
 
 ### Step 4: Create New Entry Point → `main.py`
 
@@ -316,22 +391,22 @@ This is the **key pattern** for P2P mode. Your LLM gets peer tools added to its
 **The key insight**: You add peer tools to your LLM's toolset. The LLM decides when to use them.
 
 ```python
-# agents.py
-import asyncio
+# agents.py - UPDATED FOR v0.3.0+
 from jarviscore.profiles import CustomAgent
 
 
 class AnalystAgent(CustomAgent):
     """
-    Analyst agent - specialists in data analysis.
+    Analyst agent - specialist in data analysis.
 
-    This agent:
-    1. Listens for incoming requests from peers
-    2. Processes requests using its own LLM
-    3. Responds with analysis results
+    NEW PATTERN (v0.3.0+):
+    - Uses @on_peer_request HANDLER instead of run() loop
+    - Automatically receives and responds to peer requests
+    - No manual message polling needed!
     """
     role = "analyst"
     capabilities = ["analysis", "data_interpretation", "reporting"]
+    description = "Expert data analyst for statistics and insights"
 
     async def setup(self):
         await super().setup()
@@ -406,19 +481,20 @@ Analyze data thoroughly and provide insights."""
 
         return response.get("content", "Analysis complete.")
 
-    async def run(self):
-        """Listen for incoming requests from peers."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    query = msg.data.get("question", msg.data.get("query", ""))
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from peers.
+        
+        ✅ NEW: This is called automatically when another agent sends a request.
+        ❌ OLD: Manual while loop with receive() polling
+        """
+        query = msg.data.get("question", msg.data.get("query", ""))
 
-                    # Process with LLM
-                    result = await self.process_with_llm(query)
+        # Process with LLM
+        result = await self.process_with_llm(query)
 
-                    await self.peers.respond(msg, {"response": result})
-            await asyncio.sleep(0.1)
+        # Just return the data - framework handles the response!
+        return {"response": result}
 
     async def execute_task(self, task: dict) -> dict:
         """Required by base class."""
@@ -429,13 +505,16 @@ class AssistantAgent(CustomAgent):
     """
     Assistant agent - coordinates with other specialists.
 
-    This agent:
+    NEW PATTERN (v0.3.0+):
     1. Has its own LLM for reasoning
-    2. Has peer tools (ask_peer, broadcast) in its toolset
-    3. LLM AUTONOMOUSLY decides when to ask other agents
+    2. Uses get_cognitive_context() to discover available peers
+    3. Peer tools (ask_peer, broadcast) added to LLM toolset
+    4. LLM AUTONOMOUSLY decides when to ask other agents
+    5. Uses on_peer_request handler instead of run() loop
     """
     role = "assistant"
     capabilities = ["chat", "coordination", "search"]
+    description = "General assistant that delegates specialized tasks to experts"
 
     async def setup(self):
         await super().setup()
@@ -535,16 +614,16 @@ Be concise in your responses."""
 
         return response.get("content", "")
 
-    async def run(self):
-        """Main loop - listen for incoming requests."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    query = msg.data.get("query", "")
-                    result = await self.chat(query)
-                    await self.peers.respond(msg, {"response": result})
-            await asyncio.sleep(0.1)
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from other agents.
+        
+        ✅ NEW: Handler-based - called automatically on request
+        ❌ OLD: Manual while loop with receive() polling
+        """
+        query = msg.data.get("query", "")
+        result = await self.chat(query)
+        return {"response": result}
 
     async def execute_task(self, task: dict) -> dict:
         """Required by base class."""
@@ -552,13 +631,14 @@ Be concise in your responses."""
 ```
 
 ```python
-# main.py
+# main.py - UPDATED FOR v0.3.0+ (Handler-Based Pattern)
 import asyncio
 from jarviscore import Mesh
 from agents import AnalystAgent, AssistantAgent
 
 
 async def main():
+    """Simple P2P mesh without web server."""
     mesh = Mesh(
         mode="p2p",
         config={
@@ -567,17 +647,15 @@ async def main():
         }
     )
 
-    # Add both agents
+    # Add both agents - they'll use handlers automatically
     mesh.add(AnalystAgent)
     assistant = mesh.add(AssistantAgent)
 
     await mesh.start()
 
-    # Start analyst listening in background
-    analyst = mesh.get_agent("analyst")
-    analyst_task = asyncio.create_task(analyst.run())
-
-    # Give time for setup
+    # ✅ NO MORE MANUAL run() TASKS! Handlers are automatic.
+    
+    # Give time for mesh to stabilize
     await asyncio.sleep(0.5)
 
     # User asks a question - LLM will autonomously decide to use ask_peer
@@ -590,8 +668,6 @@ async def main():
     # Output: [{'tool': 'ask_peer', 'args': {'role': 'analyst', 'question': '...'}}]
 
     # Cleanup
-    analyst.request_shutdown()
-    analyst_task.cancel()
     await mesh.stop()
 
 
@@ -599,6 +675,59 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+**Or better yet, use FastAPI + JarvisLifespan:**
+
+```python
+# main.py - PRODUCTION PATTERN (FastAPI + JarvisLifespan)
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from jarviscore.integrations import JarvisLifespan
+from agents import AnalystAgent, AssistantAgent
+import uvicorn
+
+
+# ✅ ONE-LINE MESH SETUP with JarvisLifespan!
+app = FastAPI(lifespan=JarvisLifespan([AnalystAgent, AssistantAgent]))
+
+
+@app.post("/chat")
+async def chat(request: Request):
+    """Chat endpoint - assistant may autonomously delegate to analyst."""
+    data = await request.json()
+    message = data.get("message", "")
+    
+    # Get assistant from mesh (JarvisLifespan manages it)
+    assistant = app.state.mesh.get_agent("assistant")
+    
+    # Chat - LLM autonomously discovers and delegates if needed
+    response = await assistant.chat(message)
+    
+    return JSONResponse(response)
+
+
+@app.get("/agents")
+async def list_agents():
+    """Show what each agent sees (cognitive context)."""
+    mesh = app.state.mesh
+    agents_info = {}
+    
+    for agent in mesh.agents:
+        if agent.peers:
+            context = agent.peers.get_cognitive_context(format="markdown")
+            agents_info[agent.role] = {
+                "role": agent.role,
+                "capabilities": agent.capabilities,
+                "peers_visible": len(agent.peers.get_all_peers()),
+                "cognitive_context": context[:200] + "..."
+            }
+    
+    return JSONResponse(agents_info)
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
 ### Key Concepts for P2P Mode
 
 #### Adding Peer Tools to Your LLM
@@ -666,46 +795,16 @@ async def run(self):
 
 ---
 
-## ListenerAgent (v0.3.0)
-
-**ListenerAgent** is for developers who want P2P communication without writing the `run()` loop themselves.
+## P2P Message Handlers
 
-### The Problem with CustomAgent for P2P
-
-Every P2P CustomAgent needs this boilerplate:
-
-```python
-# BEFORE (CustomAgent) - You write the same loop every time
-class MyAgent(CustomAgent):
-    role = "processor"
-    capabilities = ["processing"]
-
-    async def run(self):
-        """You have to write this loop for every P2P agent."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    # Handle request
-                    result = self.process(msg.data)
-                    await self.peers.respond(msg, {"response": result})
-                elif msg and msg.is_notify:
-                    # Handle notification
-                    self.handle_notify(msg.data)
-            await asyncio.sleep(0.1)
-
-    async def execute_task(self, task):
-        """Still required even though you're using run()."""
-        return {"status": "success"}
-```
+CustomAgent includes built-in handlers for P2P communication - just implement the handlers you need.
 
-### The Solution: ListenerAgent
+### Handler-Based P2P (Recommended)
 
 ```python
-# AFTER (ListenerAgent) - Just implement the handlers
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
-class MyAgent(ListenerAgent):
+class MyAgent(CustomAgent):
     role = "processor"
     capabilities = ["processing"]
 
@@ -718,27 +817,25 @@ class MyAgent(ListenerAgent):
         print(f"Notification received: {msg.data}")
 ```
 
-**What you no longer need:**
-- ❌ `run()` loop with `while not self.shutdown_requested`
-- ❌ `self.peers.receive()` and `self.peers.respond()` boilerplate
-- ❌ `execute_task()` stub method
-- ❌ `asyncio.sleep()` timing
-
 **What the framework handles:**
-- ✅ Message receiving loop
-- ✅ Routing requests to `on_peer_request()`
-- ✅ Routing notifications to `on_peer_notify()`
-- ✅ Automatic response sending
-- ✅ Shutdown handling
+- Message receiving loop (`run()` is built-in)
+- Routing requests to `on_peer_request()`
+- Routing notifications to `on_peer_notify()`
+- Automatic response sending (configurable with `auto_respond`)
+- Shutdown handling
+
+**Configuration:**
+- `listen_timeout` (float): Seconds to wait for messages (default: 1.0)
+- `auto_respond` (bool): Auto-send `on_peer_request()` return value (default: True)
 
-### Complete ListenerAgent Example
+### Complete P2P Example
 
 ```python
 # agents.py
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
-class AnalystAgent(ListenerAgent):
+class AnalystAgent(CustomAgent):
     """A data analyst that responds to peer requests."""
 
     role = "analyst"
@@ -778,7 +875,7 @@ class AnalystAgent(ListenerAgent):
         print(f"[{self.role}] Received notification: {msg.data}")
 
 
-class AssistantAgent(ListenerAgent):
+class AssistantAgent(CustomAgent):
     """An assistant that coordinates with specialists."""
 
     role = "assistant"
@@ -828,18 +925,17 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-### When to Use ListenerAgent vs CustomAgent
+### When to Use Handlers vs Custom run()
 
-| Use ListenerAgent when... | Use CustomAgent when... |
-|---------------------------|-------------------------|
-| You want the simplest P2P agent | You need custom message loop timing |
-| Request/response pattern fits your use case | You need to initiate messages proactively |
-| You're integrating with FastAPI | You need fine-grained control over the loop |
-| You want less boilerplate | You have complex coordination logic |
+| Use handlers (`on_peer_request`) when... | Override `run()` when... |
+|------------------------------------------|--------------------------|
+| Request/response pattern fits your use case | You need custom message loop timing |
+| You're integrating with FastAPI | You need to initiate messages proactively |
+| You want minimal boilerplate | You have complex coordination logic |
 
-### ListenerAgent with FastAPI
+### CustomAgent with FastAPI
 
-ListenerAgent shines with FastAPI integration. See [FastAPI Integration](#fastapi-integration-v030) below.
+CustomAgent works seamlessly with FastAPI. See [FastAPI Integration](#fastapi-integration-v030) below.
 
 ---
 
@@ -1446,11 +1542,11 @@ async def process(data: dict):
 ```python
 # AFTER: 3 lines to integrate
 from fastapi import FastAPI
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 from jarviscore.integrations.fastapi import JarvisLifespan
 
 
-class ProcessorAgent(ListenerAgent):
+class ProcessorAgent(CustomAgent):
     role = "processor"
     capabilities = ["processing"]
 
@@ -1492,7 +1588,7 @@ app = FastAPI(
 # app.py
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 from jarviscore.integrations.fastapi import JarvisLifespan
 
 
@@ -1500,7 +1596,7 @@ class AnalysisRequest(BaseModel):
     data: str
 
 
-class AnalystAgent(ListenerAgent):
+class AnalystAgent(CustomAgent):
     """Agent that handles both API requests and P2P messages."""
 
     role = "analyst"
@@ -1634,11 +1730,11 @@ await mesh.start()
 # Each agent can join any mesh independently
 
 # agent_container.py (runs in Docker/K8s)
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 import os
 
 
-class WorkerAgent(ListenerAgent):
+class WorkerAgent(CustomAgent):
     role = "worker"
     capabilities = ["processing"]
 
@@ -1685,10 +1781,10 @@ CMD ["python", "agent.py"]
 # agent.py
 import asyncio
 import os
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
-class WorkerAgent(ListenerAgent):
+class WorkerAgent(CustomAgent):
     role = "worker"
     capabilities = ["processing"]
 
@@ -1835,6 +1931,346 @@ if agent.peers:
 
 ---
 
+## Session Context Propagation (v0.3.2)
+
+Pass metadata (mission IDs, trace IDs, priorities) through message flows:
+
+### Sending Context
+
+```python
+# All messaging methods accept context parameter
+await self.peers.notify("logger", {"event": "started"},
+                       context={"mission_id": "m-123", "trace_id": "t-abc"})
+
+response = await self.peers.request("analyst", {"query": "..."},
+                                   context={"priority": "high", "user_id": "u-456"})
+
+await self.peers.broadcast({"alert": "ready"},
+                          context={"source": "coordinator"})
+```
+
+### Receiving Context
+
+```python
+async def on_peer_request(self, msg):
+    # Context is available on the message
+    mission_id = msg.context.get("mission_id") if msg.context else None
+    trace_id = msg.context.get("trace_id") if msg.context else None
+
+    self._logger.info(f"Request for mission {mission_id}, trace {trace_id}")
+
+    return {"result": "processed"}
+```
+
+### Auto-Propagation in respond()
+
+Context automatically propagates from request to response:
+
+```python
+async def on_peer_request(self, msg):
+    # msg.context = {"mission_id": "m-123", "trace_id": "t-abc"}
+    result = await self.process(msg.data)
+
+    # Context auto-propagates - original sender receives same context
+    await self.peers.respond(msg, {"result": result})
+
+    # Override if needed
+    await self.peers.respond(msg, {"result": result},
+                            context={"status": "completed", "mission_id": msg.context.get("mission_id")})
+```
+
+---
+
+## Async Request Pattern (v0.3.2)
+
+Fire multiple requests without blocking, collect responses later:
+
+### Fire-and-Collect Pattern
+
+```python
+async def parallel_analysis(self, data_chunks):
+    # Fire off requests to all available analysts
+    analysts = self.peers.discover(role="analyst")
+    request_ids = []
+
+    for i, (analyst, chunk) in enumerate(zip(analysts, data_chunks)):
+        req_id = await self.peers.ask_async(
+            analyst.agent_id,
+            {"chunk_id": i, "data": chunk},
+            context={"batch_id": "batch-001"}
+        )
+        request_ids.append((req_id, analyst.agent_id))
+
+    # Do other work while analysts process
+    await self.update_status("processing")
+
+    # Collect results
+    results = []
+    for req_id, analyst_id in request_ids:
+        response = await self.peers.check_inbox(req_id, timeout=30)
+        if response:
+            results.append(response)
+        else:
+            self._logger.warning(f"Timeout waiting for {analyst_id}")
+
+    return results
+```
+
+### API Methods
+
+```python
+# Fire async request - returns immediately with request_id
+req_id = await self.peers.ask_async(target, message, timeout=120, context=None)
+
+# Check for response
+response = await self.peers.check_inbox(req_id, timeout=0)  # Non-blocking
+response = await self.peers.check_inbox(req_id, timeout=10)  # Wait up to 10s
+
+# Manage pending requests
+pending = self.peers.get_pending_async_requests()
+self.peers.clear_inbox(req_id)  # Clear specific
+self.peers.clear_inbox()        # Clear all
+```
+
+---
+
+## Load Balancing Strategies (v0.3.2)
+
+Distribute work across multiple peers:
+
+### Discovery Strategies
+
+```python
+# Default: first in discovery order (deterministic)
+workers = self.peers.discover(role="worker", strategy="first")
+
+# Random: shuffle for basic distribution
+workers = self.peers.discover(role="worker", strategy="random")
+
+# Round-robin: rotate through workers on each call
+workers = self.peers.discover(role="worker", strategy="round_robin")
+
+# Least-recent: prefer workers not used recently
+workers = self.peers.discover(role="worker", strategy="least_recent")
+```
+
+### discover_one() Convenience
+
+```python
+# Get single peer with strategy applied
+worker = self.peers.discover_one(role="worker", strategy="round_robin")
+if worker:
+    response = await self.peers.request(worker.agent_id, {"task": "..."})
+```
+
+### Tracking Usage for least_recent
+
+```python
+# Track usage to influence least_recent ordering
+worker = self.peers.discover_one(role="worker", strategy="least_recent")
+response = await self.peers.request(worker.agent_id, {"task": "..."})
+self.peers.record_peer_usage(worker.agent_id)  # Update timestamp
+```
+
+### Example: Load-Balanced Task Distribution
+
+```python
+class Coordinator(CustomAgent):
+    role = "coordinator"
+    capabilities = ["coordination"]
+
+    async def distribute_work(self, tasks):
+        results = []
+        for task in tasks:
+            # Round-robin automatically rotates through workers
+            worker = self.peers.discover_one(
+                capability="processing",
+                strategy="round_robin"
+            )
+            if worker:
+                response = await self.peers.request(
+                    worker.agent_id,
+                    {"task": task}
+                )
+                results.append(response)
+        return results
+```
+
+---
+
+## Mesh Diagnostics (v0.3.2)
+
+Monitor mesh health for debugging and operations:
+
+### Getting Diagnostics
+
+```python
+# From mesh
+diag = mesh.get_diagnostics()
+
+# Structure:
+# {
+#     "local_node": {
+#         "mode": "p2p",
+#         "started": True,
+#         "agent_count": 3,
+#         "bind_address": "127.0.0.1:7950"
+#     },
+#     "known_peers": [
+#         {"role": "analyst", "node_id": "10.0.0.2:7950", "status": "alive"}
+#     ],
+#     "local_agents": [
+#         {"role": "coordinator", "agent_id": "...", "capabilities": [...]}
+#     ],
+#     "connectivity_status": "healthy"
+# }
+```
+
+### Connectivity Status
+
+| Status | Meaning |
+|--------|---------|
+| `healthy` | P2P active, peers connected |
+| `isolated` | P2P active, no peers found |
+| `degraded` | Some connectivity issues |
+| `not_started` | Mesh not started yet |
+| `local_only` | Autonomous mode (no P2P) |
+
+### FastAPI Health Endpoint
+
+```python
+from fastapi import FastAPI, Request
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p"))
+
+@app.get("/health")
+async def health(request: Request):
+    mesh = request.app.state.jarvis_mesh
+    diag = mesh.get_diagnostics()
+    return {
+        "status": diag["connectivity_status"],
+        "agents": diag["local_node"]["agent_count"],
+        "peers": len(diag.get("known_peers", []))
+    }
+```
+
+---
+
+## Testing with MockMesh (v0.3.2)
+
+Unit test agents without real P2P infrastructure:
+
+### Basic Test Setup
+
+```python
+import pytest
+from jarviscore.testing import MockMesh, MockPeerClient
+from jarviscore.profiles import CustomAgent
+
+class AnalystAgent(CustomAgent):
+    role = "analyst"
+    capabilities = ["analysis"]
+
+    async def on_peer_request(self, msg):
+        return {"analysis": f"Analyzed: {msg.data.get('query')}"}
+
+@pytest.mark.asyncio
+async def test_analyst_responds():
+    mesh = MockMesh()
+    mesh.add(AnalystAgent)
+    await mesh.start()
+
+    analyst = mesh.get_agent("analyst")
+
+    # Inject a test message
+    from jarviscore.p2p.messages import MessageType
+    analyst.peers.inject_message(
+        sender="tester",
+        message_type=MessageType.REQUEST,
+        data={"query": "test data"},
+        correlation_id="test-123"
+    )
+
+    # Receive and verify
+    msg = await analyst.peers.receive(timeout=1)
+    assert msg is not None
+    assert msg.data["query"] == "test data"
+
+    await mesh.stop()
+```
+
+### Mocking Peer Responses
+
+```python
+@pytest.mark.asyncio
+async def test_coordinator_delegates():
+    class CoordinatorAgent(CustomAgent):
+        role = "coordinator"
+        capabilities = ["coordination"]
+
+        async def on_peer_request(self, msg):
+            # This agent delegates to analyst
+            analysis = await self.peers.request("analyst", {"data": msg.data})
+            return {"coordinated": True, "analysis": analysis}
+
+    mesh = MockMesh()
+    mesh.add(CoordinatorAgent)
+    await mesh.start()
+
+    coordinator = mesh.get_agent("coordinator")
+
+    # Mock the analyst response
+    coordinator.peers.add_mock_peer("analyst", capabilities=["analysis"])
+    coordinator.peers.set_mock_response("analyst", {"result": "mocked analysis"})
+
+    # Test the flow
+    response = await coordinator.peers.request("analyst", {"test": "data"})
+
+    assert response["result"] == "mocked analysis"
+    coordinator.peers.assert_requested("analyst")
+
+    await mesh.stop()
+```
+
+### Assertion Helpers
+
+```python
+# Verify notifications were sent
+agent.peers.assert_notified("target_role")
+agent.peers.assert_notified("target", message_contains={"event": "completed"})
+
+# Verify requests were sent
+agent.peers.assert_requested("analyst")
+agent.peers.assert_requested("analyst", message_contains={"query": "test"})
+
+# Verify broadcasts
+agent.peers.assert_broadcasted()
+agent.peers.assert_broadcasted(message_contains={"alert": "important"})
+
+# Access sent messages for custom assertions
+notifications = agent.peers.get_sent_notifications()
+requests = agent.peers.get_sent_requests()
+broadcasts = agent.peers.get_sent_broadcasts()
+
+# Reset between tests
+agent.peers.reset()
+```
+
+### Custom Response Handler
+
+```python
+async def dynamic_handler(target, message, context):
+    """Return different responses based on message content."""
+    if "urgent" in message.get("query", ""):
+        return {"priority": "high", "result": "fast response"}
+    return {"priority": "normal", "result": "standard response"}
+
+agent.peers.set_request_handler(dynamic_handler)
+```
+
+---
+
 ## API Reference
 
 ### CustomAgent Class Attributes
@@ -1855,20 +2291,22 @@ if agent.peers:
 | `leave_mesh()` | Both | **(v0.3.0)** Gracefully leave the mesh |
 | `serve_forever()` | Both | **(v0.3.0)** Block until shutdown signal |
 
-### ListenerAgent Class (v0.3.0)
+### P2P Message Handlers (v0.3.1)
 
-ListenerAgent extends CustomAgent with handler-based P2P communication.
+CustomAgent includes built-in P2P message handlers for handler-based communication.
 
 | Attribute/Method | Type | Description |
 |------------------|------|-------------|
-| `role` | `str` | Required. Unique identifier for this agent type |
-| `capabilities` | `list[str]` | Required. List of capabilities for discovery |
-| `on_peer_request(msg)` | async method | Handle incoming requests. Return dict to respond |
+| `listen_timeout` | `float` | Seconds to wait for messages in `run()` loop. Default: 1.0 |
+| `auto_respond` | `bool` | Auto-send `on_peer_request` return value. Default: True |
+| `on_peer_request(msg)` | async method | Handle incoming requests. Return value sent as response |
 | `on_peer_notify(msg)` | async method | Handle broadcast notifications. No return needed |
+| `on_error(error, msg)` | async method | Handle errors during message processing |
+| `run()` | async method | Built-in listener loop that dispatches to handlers |
 
-**Note:** ListenerAgent does not require `run()` or `execute_task()` implementations.
+**Note:** Override `on_peer_request()` and `on_peer_notify()` for your business logic. The `run()` method handles the message dispatch automatically.
 
-### Why `execute_task()` is Required in P2P Mode
+### Why `execute_task()` Exists in CustomAgent
 
 You may notice that P2P agents must implement `execute_task()` even though they primarily use `run()`. Here's why:
 
@@ -2172,10 +2610,10 @@ For complete, runnable examples, see:
 
 - `examples/customagent_p2p_example.py` - P2P mode with LLM-driven peer communication
 - `examples/customagent_distributed_example.py` - Distributed mode with workflows
-- `examples/listeneragent_cognitive_discovery_example.py` - ListenerAgent + cognitive discovery (v0.3.0)
+- `examples/customagent_cognitive_discovery_example.py` - CustomAgent + cognitive discovery (v0.3.0)
 - `examples/fastapi_integration_example.py` - FastAPI + JarvisLifespan (v0.3.0)
 - `examples/cloud_deployment_example.py` - Self-registration with join_mesh (v0.3.0)
 
 ---
 
-*CustomAgent Guide - JarvisCore Framework v0.3.0*
+*CustomAgent Guide - JarvisCore Framework v0.3.2*