# From: apps/api/app/agents/tools/core/registry.py:159-283

class ToolRegistry:
    """Central registry for all integrations and their tools."""
    
    # Core integrations (always available)
    _add_category("search", tools=[web_search, fetch_webpages])
    _add_category("documents", tools=[query_file, generate_document])
    _add_category("todos", tools=[...], require_integration=True)
    
    # Provider integrations (OAuth-based)
    async def register_provider_tools(
        toolkit_name: str,    # "gmail", "notion", "github"
        space_name: str,      # Namespace for tool isolation
        specific_tools: list  # Optional: load specific tools only
    ):
        """Load tools from Composio on-demand."""

# From: apps/api/app/agents/tools/core/retrieval.py

async def retrieve_tools(
    query: str,  # "send an email"
    user_id: str,
    limit: int = 5
) -> List[BaseTool]:
    """
    Search for tools using semantic similarity.
    
    Returns tools from connected integrations only.
    """
    
    # Get user's connected integrations
    connected = await get_user_integrations(user_id)
    
    # Semantic search in ChromaDB
    results = await chroma_store.search(
        query=query,
        filter={"integration_id": {"$in": connected}},
        limit=limit
    )
    
    # Load and return actual tool objects
    return [load_tool(r.tool_name) for r in results]

# From: apps/api/app/agents/core/subagents/provider_subagents.py

# Integration categories are mapped to specialized subagents:
INTEGRATION_SUBAGENTS = {
    "gmail": "gmail_agent",           # Gmail subagent
    "googlecalendar": "calendar_agent",
    "notion": "notion_agent",
    "github": "github_agent",
    "slack": "slack_agent",
    "twitter": "twitter_agent",
    "linkedin": "linkedin_agent",
    # ... and more
}

# Main agent hands off to subagent:
handoff(
    subagent_id="gmail_agent",
    task="Search for emails from [email protected]"
)

# From: apps/api/app/agents/core/subagents/base_subagent.py:35-137

class SubAgentFactory:
    @staticmethod
    async def create_provider_subagent(
        provider: str,        # "gmail"
        name: str,            # "gmail_agent"
        llm: LanguageModelLike,
        tool_space: str = "general",
        use_direct_tools: bool = False,
    ):
        """
        Creates specialized subagent with:
        - Scoped tool access (only gmail tools)
        - Provider-specific system prompts
        - Own checkpointer for state management
        - Memory learning capabilities
        """

# From: apps/api/app/config/oauth_config.py

class OAuthIntegration:
    id: str                  # "gmail"
    name: str                # "Gmail"
    description: str
    managed_by: str          # "composio" or "custom"
    
    # Composio configuration
    composio_config: ComposioConfig = {
        "toolkit": "gmail",
        "required_scopes": ["gmail.readonly", "gmail.send"]
    }
    
    # Subagent configuration
    subagent_config: SubagentConfig = {
        "has_subagent": True,
        "agent_name": "gmail_agent",
        "tool_space": "gmail",
        "specific_tools": None  # or list of specific tools
    }

# From: apps/api/app/services/integrations/integration_resolver.py

class IntegrationResolver:
    @staticmethod
    async def resolve_integration(
        integration_id: str,
        user_id: str
    ) -> IntegrationStatus:
        """
        Check if user has connected this integration.
        
        Returns:
        - connected: bool
        - enabled: bool
        - tools_available: int
        - last_synced: datetime
        """

# From: apps/api/app/agents/tools/core/registry.py:371-432

async def load_user_mcp_tools(user_id: str) -> Dict[str, List[BaseTool]]:
    """
    Load MCP tools from user's custom integrations.
    
    MCP servers can be:
    - Self-hosted APIs
    - Custom databases
    - Internal tools
    - Proprietary services
    """
    
    # Connect to each MCP server
    mcp_client = await get_mcp_client(user_id)
    all_tools = await mcp_client.get_all_connected_tools()
    
    # Register in tool registry
    for integration_id, tools in all_tools.items():
        category_name = f"mcp_{integration_id}"
        self._add_category(
            name=category_name,
            tools=tools,
            space=integration_id,
            is_delegated=True  # Can have custom subagent
        )

// From: apps/web/src/features/integrations/hooks/useIntegrations.ts

interface MCPIntegration {
  id: string;
  name: string;
  server_url: string;
  tools_count: number;
  status: "connected" | "disconnected" | "error";
  custom_config: Record<string, any>;
}

// Users can add custom MCP servers via UI
const addMCPServer = async (serverUrl: string, config: any) => {
  // Validates server, discovers tools, registers in registry
};

# From: apps/api/app/services/integrations/user_integrations.py

@cache(ttl=300)  # 5 minute cache
async def get_user_integration_capabilities(user_id: str) -> dict:
    """
    Get cached summary of user's available tools.
    
    Returns:
    {
      "connected_integrations": ["gmail", "notion", "github"],
      "tool_count": 150,
      "tool_names": ["GMAIL_SEND_MESSAGE", ...],
      "categories": ["email", "notes", "development"],
      "has_subagents": ["gmail_agent", "notion_agent"]
    }
    """

# From: apps/api/app/models/workflow_models.py:61-92

class TriggerConfig(BaseModel):
    type: TriggerType.INTEGRATION
    trigger_name: str              # "gmail_new_email_received"
    composio_trigger_ids: List[str]  # ["trigger_abc123"]
    
    trigger_data: dict = {
        "filters": {
          "from": "[email protected]",
          "has_label": "urgent"
        }
    }

# From: apps/api/app/decorators.py

@with_rate_limiting("integration_operations")
async def call_integration_tool(...):
    """
    Rate limits:
    - Gmail: 250 calls/minute
    - Calendar: 100 calls/minute
    - Notion: 50 calls/minute
    - GitHub: 5000 calls/hour
    
    Limits are per user, per integration.
    """

async def execute_with_retry(tool: BaseTool, params: dict):
    """
    Retry logic:
    1. Initial attempt
    2. If rate limited, wait and retry
    3. Exponential backoff: 1s, 2s, 4s, 8s
    4. Max 5 retries
    5. Notify user if all retries fail
    """

# From: apps/api/app/utils/oauth_utils.py

async def store_integration_tokens(
    user_id: str,
    integration_id: str,
    tokens: dict
):
    """
    Tokens are:
    - Encrypted at rest (AES-256)
    - Stored in PostgreSQL
    - Associated with user_id
    - Include refresh tokens for auto-renewal
    """

async def refresh_integration_token(
    user_id: str,
    integration_id: str
):
    """
    Automatic token refresh:
    - Checks expiry before each API call
    - Refreshes if < 5 minutes remaining
    - Updates stored tokens
    - Retries failed call with new token
    """

// Example: Gmail scopes
const GMAIL_SCOPES = [
  "https://www.googleapis.com/auth/gmail.readonly",    // Read emails
  "https://www.googleapis.com/auth/gmail.send",        // Send emails
  "https://www.googleapis.com/auth/gmail.labels",      // Manage labels
  // NOT requesting: gmail.modify, gmail.metadata
];

// From: apps/web/src/features/integrations/components/

interface IntegrationCard {
  id: string;
  name: string;
  logo: string;
  status: "connected" | "disconnected" | "error";
  tools_count: number;
  last_used: string;
  permissions: string[];
  
  actions: {
    connect: () => void;
    disconnect: () => void;
    refresh: () => void;
    configure: () => void;
  };
}

interface IntegrationAnalytics {
  integration_id: string;
  calls_this_month: number;
  most_used_tools: Array<{
    tool_name: string;
    call_count: number;
  }>;
  success_rate: number;
  avg_response_time: number;
}