feat: token-efficient script/automation tools and YAML helpers

Author: Coolver

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.10.9] - 2026-01-20
+
+### ✨ Token‑efficient access to scripts and automations
+
+**Focused YAML access to save tokens and speed up AI workflows**
+
+- ✅ **Lightweight listing endpoints**: Added support for listing script IDs and automation IDs without returning full YAML bodies, so AI tools can cheaply discover what exists before deciding what to open
+- ✅ **Single‑entity configuration fetch**: New read‑only endpoints return configuration for a single script or automation by its ID, instead of loading entire `scripts.yaml` / `automations.yaml`
+- ✅ **Token and context savings**: Designed specifically to reduce prompt/context size and token usage when working with large YAML files, especially in conversational AI scenarios
+- ✅ **Faster request handling**: By focusing responses on the one script/automation you are currently working with, the agent can answer faster and IDEs can keep conversations narrow and relevant
+
 ## [2.10.8] - 2025-12-18
 
 ### 🔧 Git Versioning: Auto/Manual Mode & Shadow Repository

app/api/addons.py

@@ -495,6 +495,16 @@ async def add_repository(request: RepositoryRequest):
             data={'repository_url': request.repository_url}
         )
     except Exception as e:
+        error_msg = str(e)
+        # Extract more user-friendly error message from Supervisor API response
+        if "git clone" in error_msg or "fatal:" in error_msg:
+            if "could not read Username" in error_msg or "No such device or address" in error_msg:
+                error_msg = f"Repository not found or not accessible: {request.repository_url}. Please check that the repository exists and is publicly accessible."
+            elif "repository not found" in error_msg.lower():
+                error_msg = f"Repository not found: {request.repository_url}. Please verify the repository URL is correct."
+            elif "authentication" in error_msg.lower() or "permission" in error_msg.lower():
+                error_msg = f"Authentication failed for repository: {request.repository_url}. Private repositories are not supported."
+        
         logger.error(f"Error adding repository {request.repository_url}: {e}")
-        return Response(success=False, message=f"Failed to add repository: {str(e)}")
+        return Response(success=False, message=f"Failed to add repository: {error_msg}")
 

app/api/automations.py

@@ -14,28 +14,108 @@
 logger = logging.getLogger('ha_cursor_agent')
 
 @router.get("/list")
-async def list_automations():
+async def list_automations(ids_only: bool = Query(False, description="If true, return only automation IDs without full configurations")):
     """
-    List all automations
+    List all automations from automations.yaml
     
-    Returns automations from automations.yaml
+    **Parameters:**
+    - `ids_only` (optional): If `true`, returns only list of automation IDs. If `false` (default), returns full automation configurations.
+    
+    **Example response (ids_only=false):**
+    ```json
+    {
+      "success": true,
+      "count": 2,
+      "automations": [
+        {"id": "my_automation", "alias": "...", "trigger": [...]},
+        {"id": "another", ...}
+      ]
+    }
+    ```
+    
+    **Example response (ids_only=true):**
+    ```json
+    {
+      "success": true,
+      "count": 2,
+      "automation_ids": ["my_automation", "another"]
+    }
+    ```
     """
     try:
         # Read automations.yaml
         content = await file_manager.read_file('automations.yaml')
         automations = yaml.safe_load(content) or []
 
+        if ids_only:
+            # Extract IDs from automations list
+            automation_ids = [a.get('id') for a in automations if a.get('id')]
+            return {
+                "success": True,
+                "count": len(automation_ids),
+                "automation_ids": automation_ids
+            }
+        
         return {
             "success": True,
             "count": len(automations),
             "automations": automations
         }
     except FileNotFoundError:
+        if ids_only:
+            return {"success": True, "count": 0, "automation_ids": []}
         return {"success": True, "count": 0, "automations": []}
     except Exception as e:
         logger.error(f"Failed to list automations: {e}")
         raise HTTPException(status_code=500, detail=str(e))
 
+
+@router.get("/get/{automation_id}")
+async def get_automation_config(automation_id: str):
+    """
+    Get configuration for a single automation.
+    
+    Returns the YAML configuration object for a specific automation_id from automations.yaml.
+    
+    **Example response:**
+    ```json
+    {
+      "success": true,
+      "automation_id": "my_automation",
+      "config": {
+        "id": "my_automation",
+        "alias": "My Automation",
+        "trigger": [...],
+        "condition": [...],
+        "action": [...],
+        "mode": "single"
+      }
+    }
+    ```
+    """
+    try:
+        # Read automations.yaml
+        content = await file_manager.read_file('automations.yaml')
+        automations = yaml.safe_load(content) or []
+        
+        # Find automation by id
+        for automation in automations:
+            if automation.get('id') == automation_id:
+                return {
+                    "success": True,
+                    "automation_id": automation_id,
+                    "config": automation,
+                }
+        
+        raise HTTPException(status_code=404, detail=f"Automation not found: {automation_id}")
+    except HTTPException:
+        raise
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Automation not found: {automation_id}")
+    except Exception as e:
+        logger.error(f"Failed to get automation {automation_id}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
 @router.post("/create", response_model=Response)
 async def create_automation(automation: AutomationData):
     """

app/api/helpers.py

@@ -15,13 +15,22 @@
 
 CONFIG_FILE = "/config/configuration.yaml"
 
-# Each helper type gets its own file
+# Each helper-type domain gets its own YAML file which is referenced from configuration.yaml via:
+#   <domain>: !include <file>
+# For example:
+#   group: !include groups.yaml
+#   utility_meter: !include utility_meter.yaml
 HELPER_FILES = {
     'input_boolean': '/config/input_boolean.yaml',
     'input_text': '/config/input_text.yaml',
     'input_number': '/config/input_number.yaml',
     'input_datetime': '/config/input_datetime.yaml',
-    'input_select': '/config/input_select.yaml'
+    'input_select': '/config/input_select.yaml',
+    # YAML-based helpers that behave similarly to input_* from AI perspective
+    # These are not "input helpers" in HA UI, but are commonly used as building blocks
+    # and can be safely managed via YAML with the same pattern.
+    'group': '/config/groups.yaml',
+    'utility_meter': '/config/utility_meter.yaml',
 }
 
 
@@ -97,7 +106,7 @@ async def debug_services():
 
         # Extract helper-related services
         helper_services = {}
-        for domain in ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select']:
+        for domain in ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select', 'group', 'utility_meter']:
             if domain in all_services:
                 helper_services[domain] = all_services[domain]
 
@@ -112,14 +121,16 @@ async def debug_services():
 @router.get("/list")
 async def list_helpers():
     """
-    List all input helpers
+    List all helper-like entities
     
-    Returns all entities from helper domains:
+    Returns all entities from helper-related domains:
     - input_boolean
     - input_text
     - input_number
     - input_datetime
     - input_select
+    - group
+    - utility_meter
     
     Example response:
     ```json
@@ -140,8 +151,8 @@ async def list_helpers():
         # Get all entities
         all_states = await ha_client.get_states()
 
-        # Filter helper entities
-        helper_domains = ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select']
+        # Filter helper-like entities
+        helper_domains = ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select', 'group', 'utility_meter']
         helpers = [
             entity for entity in all_states 
             if any(entity['entity_id'].startswith(f"{domain}.") for domain in helper_domains)
@@ -161,16 +172,18 @@ async def list_helpers():
 @router.post("/create", response_model=Response)
 async def create_helper(helper: HelperCreate):
     """
-    Create input helper via YAML configuration
+    Create helper via YAML configuration
     
-    **Method:** Writes to helpers.yaml and reloads the integration
+    **Method:** Writes to dedicated YAML file per domain and reloads the integration
     
-    **Helper types:**
+    **Helper types (YAML-managed):**
     - `input_boolean` - Toggle/switch
     - `input_text` - Text input
     - `input_number` - Number slider
     - `input_datetime` - Date/time picker
     - `input_select` - Dropdown selection
+    - `group` - Entity groups (living_room_lights, etc.)
+    - `utility_meter` - Utility meter tracking (daily_energy, monthly_gas, etc.)
     
     **Example request (Boolean):**
     ```json
@@ -201,11 +214,11 @@ async def create_helper(helper: HelperCreate):
     """
     try:
         # Validate helper type
-        valid_types = ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select']
+        valid_types = ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select', 'group', 'utility_meter']
         if helper.type not in valid_types:
             raise HTTPException(status_code=400, detail=f"Invalid helper type. Must be one of: {', '.join(valid_types)}")
 
-        # Extract name from config (required)
+        # Extract name from config (required for all supported helper-like types)
         if 'name' not in helper.config:
             raise HTTPException(status_code=400, detail="config must include 'name' field")
 
@@ -276,7 +289,7 @@ async def delete_helper(entity_id: str, commit_message: Optional[str] = Query(No
         domain, helper_id = entity_id.split('.', 1)
 
         # Validate domain
-        valid_types = ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select']
+        valid_types = ['input_boolean', 'input_text', 'input_number', 'input_datetime', 'input_select', 'group', 'utility_meter']
         if domain not in valid_types:
             raise HTTPException(status_code=400, detail=f"Invalid helper domain. Must be one of: {', '.join(valid_types)}")
 

app/api/scripts.py

@@ -14,18 +14,53 @@
 logger = logging.getLogger('ha_cursor_agent')
 
 @router.get("/list")
-async def list_scripts():
-    """List all scripts from scripts.yaml"""
+async def list_scripts(ids_only: bool = Query(False, description="If true, return only script IDs without full configurations")):
+    """
+    List all scripts from scripts.yaml
+    
+    **Parameters:**
+    - `ids_only` (optional): If `true`, returns only list of script IDs. If `false` (default), returns full script configurations.
+    
+    **Example response (ids_only=false):**
+    ```json
+    {
+      "success": true,
+      "count": 3,
+      "scripts": {
+        "my_script": {"alias": "...", "sequence": [...]},
+        "another_script": {...}
+      }
+    }
+    ```
+    
+    **Example response (ids_only=true):**
+    ```json
+    {
+      "success": true,
+      "count": 3,
+      "script_ids": ["my_script", "another_script", "third_script"]
+    }
+    ```
+    """
     try:
         content = await file_manager.read_file('scripts.yaml')
         scripts = yaml.safe_load(content) or {}
 
+        if ids_only:
+            return {
+                "success": True,
+                "count": len(scripts),
+                "script_ids": list(scripts.keys())
+            }
+        
         return {
             "success": True,
             "count": len(scripts),
             "scripts": scripts
         }
     except FileNotFoundError:
+        if ids_only:
+            return {"success": True, "count": 0, "script_ids": []}
         return {"success": True, "count": 0, "scripts": {}}
     except Exception as e:
         logger.error(f"Failed to list scripts: {e}")

app/models/schemas.py

@@ -17,7 +17,13 @@ class FileAppend(BaseModel):
 
 class HelperCreate(BaseModel):
     """Helper creation model"""
-    type: str = Field(..., description="Helper type: input_boolean, input_text, input_number, input_datetime, input_select")
+    type: str = Field(
+        ...,
+        description=(
+            "Helper type: input_boolean, input_text, input_number, input_datetime, "
+            "input_select, group, utility_meter"
+        ),
+    )
     config: Dict[str, Any] = Field(..., description="Helper configuration including 'name' and other options")
     commit_message: Optional[str] = Field(None, description="Custom commit message for Git backup (e.g., 'Add helper: climate system enabled switch')")