remdb 0.3.163__py3-none-any.whl → 0.3.200__py3-none-any.whl

rem/api/mcp_router/tools.py

@@ -20,6 +20,7 @@ Available Tools:
 - get_schema: Get detailed schema for a table (columns, types, indexes)
 """
 
+import json
 from functools import wraps
 from typing import Any, Callable, Literal, cast
 
@@ -116,7 +117,8 @@ def mcp_tool_error_handler(func: Callable) -> Callable:
             # Otherwise wrap in success response
             return {"status": "success", **result}
         except Exception as e:
-            logger.error(f"{func.__name__} failed: {e}", exc_info=True)
+            # Use %s format to avoid issues with curly braces in error messages
+            logger.opt(exception=True).error("{} failed: {}", func.__name__, str(e))
             return {
                 "status": "error",
                 "error": str(e),
@@ -127,201 +129,228 @@ def mcp_tool_error_handler(func: Callable) -> Callable:
 
 @mcp_tool_error_handler
 async def search_rem(
-    query_type: Literal["lookup", "fuzzy", "search", "sql", "traverse"],
-    # LOOKUP parameters
-    entity_key: str | None = None,
-    # FUZZY parameters
-    query_text: str | None = None,
-    threshold: float = 0.7,
-    # SEARCH parameters
-    table: str | None = None,
+    query: str,
     limit: int = 20,
-    # SQL parameters
-    sql_query: str | None = None,
-    # TRAVERSE parameters
-    initial_query: str | None = None,
-    edge_types: list[str] | None = None,
-    depth: int = 1,
-    # Optional context override (defaults to authenticated user)
-    user_id: str | None = None,
 ) -> dict[str, Any]:
     """
-    Execute REM queries for entity lookup, semantic search, and graph traversal.
-
-    REM supports multiple query types for different retrieval patterns:
+    Execute a REM query using the REM query dialect.
 
-    **LOOKUP** - O(1) entity resolution by natural language key:
-    - Fast exact match across all tables
-    - Uses indexed label_vector for instant retrieval
-    - Example: LOOKUP "Sarah Chen" returns all entities named "Sarah Chen"
+    **REM Query Syntax:**
 
-    **FUZZY** - Fuzzy text matching with similarity threshold:
-    - Finds partial matches and typos
-    - Example: FUZZY "sara" threshold=0.7 finds "Sarah Chen", "Sara Martinez"
+    LOOKUP <entity_key>
+        Find entity by exact name/key. Searches across all tables.
+        Example: LOOKUP phq-9-procedure
+        Example: LOOKUP sertraline
 
-    **SEARCH** - Semantic vector search (table-specific):
-    - Finds conceptually similar entities
-    - Example: SEARCH "database migration" table=resources returns related documents
+    SEARCH <text> IN <table>
+        Semantic vector search within a specific table.
+        Tables: 'ontologies' (clinical knowledge, procedures, drugs, DSM criteria)
+                'resources' (documents, files, user content)
+        Example: SEARCH depression IN ontologies
+        Example: SEARCH Module F IN ontologies
 
-    **SQL** - Direct SQL queries for structured data:
-    - Full PostgreSQL query power (scoped to table)
-    - Example: SQL "role = 'engineer'" (WHERE clause only)
+    FUZZY <text>
+        Fuzzy text matching for partial matches and typos.
+        Example: FUZZY setraline
 
-    **TRAVERSE** - Graph traversal following relationships:
-    - Explores entity neighborhood via graph edges
-    - Supports depth control and edge type filtering
-    - Example: TRAVERSE "Sarah Chen" edge_types=["manages", "reports_to"] depth=2
+    TRAVERSE <start_entity>
+        Graph traversal from a starting entity.
+        Example: TRAVERSE sarah-chen
 
     Args:
-        query_type: Type of query (lookup, fuzzy, search, sql, traverse)
-        entity_key: Entity key for LOOKUP (e.g., "Sarah Chen")
-        query_text: Search text for FUZZY or SEARCH
-        threshold: Similarity threshold for FUZZY (0.0-1.0)
-        table: Target table for SEARCH (resources, moments, users, etc.)
-        limit: Max results for SEARCH
-        sql_query: SQL WHERE clause for SQL type (e.g. "id = '123'")
-        initial_query: Starting entity for TRAVERSE
-        edge_types: Edge types to follow for TRAVERSE (e.g., ["manages", "reports_to"])
-        depth: Traversal depth for TRAVERSE (0=plan only, 1-5=actual traversal)
-        user_id: Optional user identifier (defaults to authenticated user or "default")
+        query: REM query string (e.g., "LOOKUP phq-9-procedure", "SEARCH depression IN ontologies")
+        limit: Maximum results to return (default: 20)
 
     Returns:
-        Dict with query results, metadata, and execution info
+        Dict with query results and metadata. If no results found, includes
+        'suggestions' with alternative search strategies.
 
     Examples:
-        # Lookup entity (uses authenticated user context)
-        search_rem(
-            query_type="lookup",
-            entity_key="Sarah Chen"
-        )
-
-        # Semantic search
-        search_rem(
-            query_type="search",
-            query_text="database migration",
-            table="resources",
-            limit=10
-        )
-
-        # SQL query (WHERE clause only)
-        search_rem(
-            query_type="sql",
-            table="resources",
-            sql_query="category = 'document'"
-        )
-
-        # Graph traversal
-        search_rem(
-            query_type="traverse",
-            initial_query="Sarah Chen",
-            edge_types=["manages", "reports_to"],
-            depth=2
-        )
+        search_rem("LOOKUP phq-9-procedure")
+        search_rem("SEARCH depression IN ontologies")
+        search_rem("SEARCH anxiety treatment IN ontologies", limit=10)
+        search_rem("FUZZY setraline")
     """
     # Get RemService instance (lazy initialization)
     rem_service = await get_rem_service()
 
-    # Get user_id from context if not provided
-    # TODO: Extract from authenticated session context when auth is enabled
-    user_id = AgentContext.get_user_id_or_default(user_id, source="search_rem")
+    # Get user_id from context
+    user_id = AgentContext.get_user_id_or_default(None, source="search_rem")
+
+    # Parse the REM query string
+    if not query or not query.strip():
+        return {
+            "status": "error",
+            "error": "Empty query. Use REM syntax: LOOKUP <key>, SEARCH <text> IN <table>, FUZZY <text>, or TRAVERSE <entity>",
+        }
+
+    query = query.strip()
+    parts = query.split(None, 1)  # Split on first whitespace
 
-    # Normalize query_type to lowercase for case-insensitive REM dialect
-    query_type = cast(Literal["lookup", "fuzzy", "search", "sql", "traverse"], query_type.lower())
+    if len(parts) < 2:
+        return {
+            "status": "error",
+            "error": f"Invalid query format: '{query}'. Expected: LOOKUP <key>, SEARCH <text> IN <table>, FUZZY <text>, or TRAVERSE <entity>",
+        }
+
+    query_type = parts[0].upper()
+    remainder = parts[1].strip()
 
     # Build RemQuery based on query_type
-    if query_type == "lookup":
-        if not entity_key:
-            return {"status": "error", "error": "entity_key required for LOOKUP"}
+    if query_type == "LOOKUP":
+        if not remainder:
+            return {
+                "status": "error",
+                "error": "LOOKUP requires an entity key. Example: LOOKUP phq-9-procedure",
+            }
 
-        query = RemQuery(
+        rem_query = RemQuery(
             query_type=QueryType.LOOKUP,
             parameters=LookupParameters(
-                key=entity_key,
+                key=remainder,
                 user_id=user_id,
             ),
             user_id=user_id,
         )
+        table = None  # LOOKUP searches all tables
+
+    elif query_type == "SEARCH":
+        # Parse "text IN table" format
+        if " IN " in remainder.upper():
+            # Find the last " IN " to handle cases like "SEARCH pain IN back IN ontologies"
+            in_pos = remainder.upper().rfind(" IN ")
+            search_text = remainder[:in_pos].strip()
+            table = remainder[in_pos + 4:].strip().lower()
+        else:
+            return {
+                "status": "error",
+                "error": f"SEARCH requires table: SEARCH <text> IN <table>. "
+                "Use 'ontologies' for clinical knowledge or 'resources' for documents. "
+                f"Example: SEARCH {remainder} IN ontologies",
+            }
 
-    elif query_type == "fuzzy":
-        if not query_text:
-            return {"status": "error", "error": "query_text required for FUZZY"}
-
-        query = RemQuery(
-            query_type=QueryType.FUZZY,
-            parameters=FuzzyParameters(
-                query_text=query_text,
-                threshold=threshold,
-                limit=limit, # Limit was missing in original logic but likely intended
-            ),
-            user_id=user_id,
-        )
-
-    elif query_type == "search":
-        if not query_text:
-            return {"status": "error", "error": "query_text required for SEARCH"}
-        if not table:
-            return {"status": "error", "error": "table required for SEARCH"}
+        if not search_text:
+            return {
+                "status": "error",
+                "error": "SEARCH requires search text. Example: SEARCH depression IN ontologies",
+            }
 
-        query = RemQuery(
+        rem_query = RemQuery(
             query_type=QueryType.SEARCH,
             parameters=SearchParameters(
-                query_text=query_text,
+                query_text=search_text,
                 table_name=table,
                 limit=limit,
             ),
             user_id=user_id,
         )
 
-    elif query_type == "sql":
-        if not sql_query:
-            return {"status": "error", "error": "sql_query required for SQL"}
-        
-        # SQLParameters requires table_name. If not provided, we cannot execute.
-        # Assuming sql_query is just the WHERE clause based on RemService implementation,
-        # OR if table is provided we use it.
-        if not table:
-             return {"status": "error", "error": "table required for SQL queries (parameter: table)"}
-
-        query = RemQuery(
-            query_type=QueryType.SQL,
-            parameters=SQLParameters(
-                table_name=table,
-                where_clause=sql_query,
+    elif query_type == "FUZZY":
+        if not remainder:
+            return {
+                "status": "error",
+                "error": "FUZZY requires search text. Example: FUZZY setraline",
+            }
+
+        rem_query = RemQuery(
+            query_type=QueryType.FUZZY,
+            parameters=FuzzyParameters(
+                query_text=remainder,
+                threshold=0.3,  # pg_trgm similarity - 0.3 is reasonable for typo correction
                 limit=limit,
             ),
             user_id=user_id,
         )
+        table = None
 
-    elif query_type == "traverse":
-        if not initial_query:
+    elif query_type == "TRAVERSE":
+        if not remainder:
             return {
                 "status": "error",
-                "error": "initial_query required for TRAVERSE",
+                "error": "TRAVERSE requires a starting entity. Example: TRAVERSE sarah-chen",
             }
 
-        query = RemQuery(
+        rem_query = RemQuery(
             query_type=QueryType.TRAVERSE,
             parameters=TraverseParameters(
-                initial_query=initial_query,
-                edge_types=edge_types or [],
-                max_depth=depth,
+                initial_query=remainder,
+                edge_types=[],
+                max_depth=1,
             ),
             user_id=user_id,
         )
+        table = None
 
     else:
-        return {"status": "error", "error": f"Unknown query_type: {query_type}"}
+        return {
+            "status": "error",
+            "error": f"Unknown query type: '{query_type}'. Valid types: LOOKUP, SEARCH, FUZZY, TRAVERSE. "
+            "Examples: LOOKUP phq-9-procedure, SEARCH depression IN ontologies",
+        }
 
     # Execute query (errors handled by decorator)
     logger.info(f"Executing REM query: {query_type} for user {user_id}")
-    result = await rem_service.execute_query(query)
+    result = await rem_service.execute_query(rem_query)
 
     logger.info(f"Query completed successfully: {query_type}")
-    return {
+
+    # Provide helpful guidance when no results found
+    response: dict[str, Any] = {
         "query_type": query_type,
         "results": result,
     }
 
+    # Check if results are empty - handle both list and dict result formats
+    is_empty = False
+    if not result:
+        is_empty = True
+    elif isinstance(result, list) and len(result) == 0:
+        is_empty = True
+    elif isinstance(result, dict):
+        # RemService returns dict with 'results' key containing actual matches
+        inner_results = result.get("results", [])
+        count = result.get("count", len(inner_results) if isinstance(inner_results, list) else 0)
+        is_empty = count == 0 or (isinstance(inner_results, list) and len(inner_results) == 0)
+
+    if is_empty:
+        # Build helpful suggestions based on query type
+        suggestions = []
+
+        if query_type in ("LOOKUP", "FUZZY"):
+            suggestions.append(
+                "LOOKUP/FUZZY searches across ALL tables. If you expected results, "
+                "verify the entity name is spelled correctly."
+            )
+
+        if query_type == "SEARCH":
+            if table == "resources":
+                suggestions.append(
+                    "No results in 'resources' table. Try: SEARCH <text> IN ontologies - "
+                    "clinical procedures, drug info, and diagnostic criteria are stored there."
+                )
+            elif table == "ontologies":
+                suggestions.append(
+                    "No results in 'ontologies' table. Try: SEARCH <text> IN resources - "
+                    "for user-uploaded documents and general content."
+                )
+            else:
+                suggestions.append(
+                    "Try: SEARCH <text> IN ontologies (clinical knowledge, procedures, drugs) "
+                    "or SEARCH <text> IN resources (documents, files)."
+                )
+
+        # Always suggest both tables if no specific table guidance given
+        if not suggestions:
+            suggestions.append(
+                "No results found. Try: SEARCH <text> IN ontologies (clinical procedures, drugs) "
+                "or SEARCH <text> IN resources (documents, files)."
+            )
+
+        response["suggestions"] = suggestions
+        response["hint"] = "0 results returned. See 'suggestions' for alternative search strategies."
+
+    return response
+
 
 @mcp_tool_error_handler
 async def ask_rem_agent(
@@ -372,19 +401,45 @@ async def ask_rem_agent(
             query="Show me Sarah's reporting chain and their recent projects"
         )
     """
-    # Get user_id from context if not provided
-    # TODO: Extract from authenticated session context when auth is enabled
-    user_id = AgentContext.get_user_id_or_default(user_id, source="ask_rem_agent")
-
     from ...agentic import create_agent
+    from ...agentic.context import get_current_context
     from ...utils.schema_loader import load_agent_schema
 
-    # Create agent context
-    context = AgentContext(
-        user_id=user_id,
-        tenant_id=user_id,  # Set tenant_id to user_id for backward compat
-        default_model=settings.llm.default_model,
-    )
+    # Get parent context for multi-agent support
+    # This enables context propagation from parent agent to child agent
+    parent_context = get_current_context()
+
+    # Build child context: inherit from parent if available, otherwise use defaults
+    if parent_context is not None:
+        # Inherit user_id, tenant_id, session_id, is_eval from parent
+        # Allow explicit user_id override if provided
+        effective_user_id = user_id or parent_context.user_id
+        context = parent_context.child_context(agent_schema_uri=agent_schema)
+        if user_id is not None:
+            # Override user_id if explicitly provided
+            context = AgentContext(
+                user_id=user_id,
+                tenant_id=parent_context.tenant_id,
+                session_id=parent_context.session_id,
+                default_model=parent_context.default_model,
+                agent_schema_uri=agent_schema,
+                is_eval=parent_context.is_eval,
+            )
+        logger.debug(
+            f"ask_rem_agent inheriting context from parent: "
+            f"user_id={context.user_id}, session_id={context.session_id}"
+        )
+    else:
+        # No parent context - create fresh context (backwards compatible)
+        effective_user_id = AgentContext.get_user_id_or_default(
+            user_id, source="ask_rem_agent"
+        )
+        context = AgentContext(
+            user_id=effective_user_id,
+            tenant_id=effective_user_id or "default",
+            default_model=settings.llm.default_model,
+            agent_schema_uri=agent_schema,
+        )
 
     # Load agent schema
     try:
@@ -424,15 +479,18 @@ async def ingest_into_rem(
     category: str | None = None,
     tags: list[str] | None = None,
     is_local_server: bool = False,
-    user_id: str | None = None,
     resource_type: str | None = None,
 ) -> dict[str, Any]:
     """
-    Ingest file into REM, creating searchable resources and embeddings.
+    Ingest file into REM, creating searchable PUBLIC resources and embeddings.
+
+    **IMPORTANT: All ingested data is PUBLIC by default.** This is correct for
+    shared knowledge bases (ontologies, procedures, reference data). Private
+    user-scoped data requires different handling via the CLI with --make-private.
 
     This tool provides the complete file ingestion pipeline:
     1. **Read**: File from local/S3/HTTP
-    2. **Store**: To user-scoped internal storage
+    2. **Store**: To internal storage (public namespace)
     3. **Parse**: Extract content, metadata, tables, images
     4. **Chunk**: Semantic chunking for embeddings
     5. **Embed**: Create Resource chunks with vector embeddings
@@ -451,7 +509,6 @@ async def ingest_into_rem(
         category: Optional category (document, code, audio, etc.)
         tags: Optional tags for file
         is_local_server: True if running as local/stdio MCP server
-        user_id: Optional user identifier (defaults to authenticated user or "default")
         resource_type: Optional resource type for storing chunks (case-insensitive).
             Supports flexible naming:
             - "resource", "resources", "Resource" → Resource (default)
@@ -470,10 +527,10 @@ async def ingest_into_rem(
         - message: Human-readable status message
 
     Examples:
-        # Ingest local file (local server only, uses authenticated user context)
+        # Ingest local file (local server only)
         ingest_into_rem(
-            file_uri="/Users/me/contract.pdf",
-            category="legal",
+            file_uri="/Users/me/procedure.pdf",
+            category="medical",
             is_local_server=True
         )
 
@@ -497,15 +554,14 @@ async def ingest_into_rem(
     """
     from ...services.content import ContentService
 
-    # Get user_id from context if not provided
-    # TODO: Extract from authenticated session context when auth is enabled
-    user_id = AgentContext.get_user_id_or_default(user_id, source="ingest_into_rem")
+    # Data is PUBLIC by default (user_id=None)
+    # Private user-scoped data requires CLI with --make-private flag
 
     # Delegate to ContentService for centralized ingestion (errors handled by decorator)
     content_service = ContentService()
     result = await content_service.ingest_file(
         file_uri=file_uri,
-        user_id=user_id,
+        user_id=None,  # PUBLIC - all ingested data is shared/public
         category=category,
         tags=tags,
         is_local_server=is_local_server,
@@ -615,6 +671,8 @@ async def register_metadata(
     recommended_action: str | None = None,
     # Generic extension - any additional key-value pairs
     extra: dict[str, Any] | None = None,
+    # Agent schema (auto-populated from context if not provided)
+    agent_schema: str | None = None,
 ) -> dict[str, Any]:
     """
     Register response metadata to be emitted as an SSE MetadataEvent.
@@ -655,6 +713,8 @@ async def register_metadata(
         extra: Dict of arbitrary additional metadata. Use this for any
             domain-specific fields not covered by the standard parameters.
             Example: {"topics_detected": ["anxiety", "sleep"], "session_count": 5}
+        agent_schema: Optional agent schema name. If not provided, automatically
+            populated from the current agent context (for multi-agent tracing).
 
     Returns:
         Dict with:
@@ -698,10 +758,17 @@ async def register_metadata(
             }
         )
     """
+    # Auto-populate agent_schema from context if not provided
+    if agent_schema is None:
+        from ...agentic.context import get_current_context
+        current_context = get_current_context()
+        if current_context and current_context.agent_schema_uri:
+            agent_schema = current_context.agent_schema_uri
+
     logger.debug(
         f"Registering metadata: confidence={confidence}, "
         f"risk_level={risk_level}, refs={len(references or [])}, "
-        f"sources={len(sources or [])}"
+        f"sources={len(sources or [])}, agent_schema={agent_schema}"
     )
 
     result = {
@@ -711,6 +778,7 @@ async def register_metadata(
         "references": references,
         "sources": sources,
         "flags": flags,
+        "agent_schema": agent_schema,  # Include agent schema for tracing
     }
 
     # Add session name if provided
@@ -1130,3 +1198,256 @@ async def save_agent(
         result["message"] = f"Agent '{name}' saved. Use `/custom-agent {name}` to chat with it."
 
     return result
+
+
+# =============================================================================
+# Multi-Agent Tools
+# =============================================================================
+
+
+@mcp_tool_error_handler
+async def ask_agent(
+    agent_name: str,
+    input_text: str,
+    input_data: dict[str, Any] | None = None,
+    user_id: str | None = None,
+    timeout_seconds: int = 300,
+) -> dict[str, Any]:
+    """
+    Invoke another agent by name and return its response.
+
+    This tool enables multi-agent orchestration by allowing one agent to call
+    another. The child agent inherits the parent's context (user_id, session_id,
+    tenant_id, is_eval) for proper scoping and continuity.
+
+    Use Cases:
+    - Orchestrator agents that delegate to specialized sub-agents
+    - Workflow agents that chain multiple processing steps
+    - Ensemble agents that aggregate responses from multiple specialists
+
+    Args:
+        agent_name: Name of the agent to invoke. Can be:
+            - A user-created agent (saved via save_agent)
+            - A system agent (e.g., "ask_rem", "knowledge-query")
+        input_text: The user message/query to send to the agent
+        input_data: Optional structured input data for the agent
+        user_id: Optional user override (defaults to parent's user_id)
+        timeout_seconds: Maximum execution time (default: 300s)
+
+    Returns:
+        Dict with:
+        - status: "success" or "error"
+        - output: Agent's structured output (if using output schema)
+        - text_response: Agent's text response
+        - agent_schema: Name of the invoked agent
+        - metadata: Any metadata registered by the agent (confidence, etc.)
+
+    Examples:
+        # Simple delegation
+        ask_agent(
+            agent_name="sentiment-analyzer",
+            input_text="I love this product! Best purchase ever."
+        )
+        # Returns: {"status": "success", "output": {"sentiment": "positive"}, ...}
+
+        # Orchestrator pattern
+        ask_agent(
+            agent_name="knowledge-query",
+            input_text="What are the latest Q3 results?"
+        )
+
+        # Chain with structured input
+        ask_agent(
+            agent_name="summarizer",
+            input_text="Summarize this document",
+            input_data={"document_id": "doc-123", "max_length": 500}
+        )
+    """
+    import asyncio
+    from ...agentic import create_agent
+    from ...agentic.context import get_current_context, agent_context_scope
+    from ...agentic.agents.agent_manager import get_agent
+    from ...utils.schema_loader import load_agent_schema
+
+    # Get parent context for inheritance
+    parent_context = get_current_context()
+
+    # Determine effective user_id
+    if parent_context is not None:
+        effective_user_id = user_id or parent_context.user_id
+    else:
+        effective_user_id = AgentContext.get_user_id_or_default(
+            user_id, source="ask_agent"
+        )
+
+    # Build child context
+    if parent_context is not None:
+        child_context = parent_context.child_context(agent_schema_uri=agent_name)
+        if user_id is not None:
+            # Explicit user_id override
+            child_context = AgentContext(
+                user_id=user_id,
+                tenant_id=parent_context.tenant_id,
+                session_id=parent_context.session_id,
+                default_model=parent_context.default_model,
+                agent_schema_uri=agent_name,
+                is_eval=parent_context.is_eval,
+            )
+        logger.debug(
+            f"ask_agent '{agent_name}' inheriting context: "
+            f"user_id={child_context.user_id}, session_id={child_context.session_id}"
+        )
+    else:
+        child_context = AgentContext(
+            user_id=effective_user_id,
+            tenant_id=effective_user_id or "default",
+            default_model=settings.llm.default_model,
+            agent_schema_uri=agent_name,
+        )
+
+    # Try to load agent schema from:
+    # 1. Database (user-created or system agents)
+    # 2. File system (packaged agents)
+    schema = None
+
+    # Try database first
+    if effective_user_id:
+        schema = await get_agent(agent_name, user_id=effective_user_id)
+        if schema:
+            logger.debug(f"Loaded agent '{agent_name}' from database")
+
+    # Fall back to file system
+    if schema is None:
+        try:
+            schema = load_agent_schema(agent_name)
+            logger.debug(f"Loaded agent '{agent_name}' from file system")
+        except FileNotFoundError:
+            pass
+
+    if schema is None:
+        return {
+            "status": "error",
+            "error": f"Agent not found: {agent_name}",
+            "hint": "Use list_agents to see available agents, or save_agent to create one",
+        }
+
+    # Create agent runtime
+    agent_runtime = await create_agent(
+        context=child_context,
+        agent_schema_override=schema,
+    )
+
+    # Build prompt with optional input_data
+    prompt = input_text
+    if input_data:
+        prompt = f"{input_text}\n\nInput data: {json.dumps(input_data)}"
+
+    # Run agent with timeout and context propagation
+    logger.info(f"Invoking agent '{agent_name}' with prompt: {prompt[:100]}...")
+
+    try:
+        # Set child context for nested tool calls
+        with agent_context_scope(child_context):
+            result = await asyncio.wait_for(
+                agent_runtime.run(prompt),
+                timeout=timeout_seconds
+            )
+    except asyncio.TimeoutError:
+        return {
+            "status": "error",
+            "error": f"Agent '{agent_name}' timed out after {timeout_seconds}s",
+            "agent_schema": agent_name,
+        }
+
+    # Serialize output
+    from rem.agentic.serialization import serialize_agent_result
+    output = serialize_agent_result(result.output)
+
+    logger.info(f"Agent '{agent_name}' completed successfully")
+
+    return {
+        "status": "success",
+        "output": output,
+        "text_response": str(result.output),
+        "agent_schema": agent_name,
+        "input_text": input_text,
+    }
+
+
+# =============================================================================
+# Test/Debug Tools (for development only)
+# =============================================================================
+
+@mcp_tool_error_handler
+async def test_error_handling(
+    error_type: Literal["exception", "error_response", "timeout", "success"] = "success",
+    delay_seconds: float = 0,
+    error_message: str = "Test error occurred",
+) -> dict[str, Any]:
+    """
+    Test tool for simulating different error scenarios.
+
+    **FOR DEVELOPMENT/TESTING ONLY** - This tool helps verify that error
+    handling works correctly through the streaming layer.
+
+    Args:
+        error_type: Type of error to simulate:
+            - "success": Returns successful response (default)
+            - "exception": Raises an exception (tests @mcp_tool_error_handler)
+            - "error_response": Returns {"status": "error", ...} dict
+            - "timeout": Delays for 60 seconds (simulates timeout)
+        delay_seconds: Optional delay before responding (0-10 seconds)
+        error_message: Custom error message for error scenarios
+
+    Returns:
+        Dict with test results or error information
+
+    Examples:
+        # Test successful response
+        test_error_handling(error_type="success")
+
+        # Test exception handling
+        test_error_handling(error_type="exception", error_message="Database connection failed")
+
+        # Test error response format
+        test_error_handling(error_type="error_response", error_message="Resource not found")
+
+        # Test with delay
+        test_error_handling(error_type="success", delay_seconds=2)
+    """
+    import asyncio
+
+    logger.info(f"test_error_handling called: type={error_type}, delay={delay_seconds}")
+
+    # Apply delay (capped at 10 seconds for safety)
+    if delay_seconds > 0:
+        await asyncio.sleep(min(delay_seconds, 10))
+
+    if error_type == "exception":
+        # This tests the @mcp_tool_error_handler decorator
+        raise RuntimeError(f"TEST EXCEPTION: {error_message}")
+
+    elif error_type == "error_response":
+        # This tests how the streaming layer handles error status responses
+        return {
+            "status": "error",
+            "error": error_message,
+            "error_code": "TEST_ERROR",
+            "recoverable": True,
+        }
+
+    elif error_type == "timeout":
+        # Simulate a very long operation (for testing client-side timeouts)
+        await asyncio.sleep(60)
+        return {"status": "success", "message": "Timeout test completed (should not reach here)"}
+
+    else:  # success
+        return {
+            "status": "success",
+            "message": "Test completed successfully",
+            "test_data": {
+                "error_type": error_type,
+                "delay_applied": delay_seconds,
+                "timestamp": str(asyncio.get_event_loop().time()),
+            },
+        }