@jacques-ai/cli 0.0.7-alpha.1

package/hooks/adapters/cursor.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""
+cursor.py - Cursor Native AI Adapter for Jacques
+
+Handles events from Cursor's native AI (sidebar chat).
+
+Field Mappings:
+- session_id: conversation_id
+- project_path: workspace_roots[0]
+- context_metrics: from preCompact event
+
+Hook Events (configured in .cursor/hooks.json):
+- sessionStart → session_start
+- sessionEnd → session_end
+- postToolUse → activity
+- preCompact → context_update (contains context metrics!)
+
+Key Discovery:
+Cursor's preCompact event provides context metrics that allow us to display
+context usage percentage just like Claude Code CLI!
+"""
+import os
+from typing import Optional
+from .base import BaseAdapter
+
+
+class CursorAdapter(BaseAdapter):
+    """
+    Adapter for Cursor Native AI sessions.
+    
+    Cursor provides session data via hooks configured in
+    .cursor/hooks.json (per-project) or global Cursor settings.
+    
+    Note: Cursor uses different field names than Claude Code:
+    - conversation_id instead of session_id
+    - workspace_roots[] instead of workspace.project_dir
+    """
+    
+    @property
+    def source(self) -> str:
+        return 'cursor'
+    
+    def get_session_id(self, input_data: dict) -> Optional[str]:
+        """
+        Extract session ID from Cursor input.
+        
+        Cursor uses 'conversation_id' as the session identifier.
+        """
+        return input_data.get('conversation_id')
+    
+    def get_project_path(self, input_data: dict) -> Optional[str]:
+        """
+        Extract project path from Cursor input.
+        
+        Cursor provides workspace_roots as an array of open workspace paths.
+        We use the first one as the primary project path.
+        """
+        workspace_roots = input_data.get('workspace_roots', [])
+        if workspace_roots and isinstance(workspace_roots, list):
+            return workspace_roots[0]
+        return ''
+    
+    def get_model(self, input_data: dict) -> Optional[str]:
+        """Extract model name from Cursor input."""
+        # Cursor may provide model info in different fields
+        return input_data.get('model') or input_data.get('model_name')
+    
+    # =========================================================================
+    # Session Start Payload
+    # =========================================================================
+    
+    def build_session_start_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for session_start event.
+        
+        Called from sessionStart hook (session-start.py).
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        # Extract project info
+        project_info = self.extract_project_info(input_data)
+        
+        # Cursor doesn't have transcript files like Claude Code
+        # Generate title from project name
+        session_title = self.generate_fallback_title(project_info['project'])
+        
+        # Get terminal identity (useful for identification)
+        terminal = self.get_terminal_identity()
+        terminal_key = self.build_terminal_key(terminal)
+        
+        return self.build_base_payload(
+            event='session_start',
+            session_id=session_id,
+            session_title=session_title,
+            transcript_path=None,  # Cursor doesn't have transcripts
+            cwd=project_info['cwd'],
+            project=project_info['project'],
+            project_dir=project_info['project_path'],
+            model=self.get_model(input_data),
+            hook_source='startup',
+            terminal=terminal,
+            terminal_key=terminal_key,
+            # Cursor-specific fields
+            workspace_roots=input_data.get('workspace_roots', []),
+        )
+    
+    # =========================================================================
+    # Context Estimate Payload (from token estimation)
+    # =========================================================================
+    
+    def build_context_estimate_payload(
+        self, 
+        input_data: dict, 
+        estimated_tokens: int,
+        model: str = None
+    ) -> Optional[dict]:
+        """
+        Build payload for context_update event from token estimation.
+        
+        Used by afterAgentResponse hook to send estimated context metrics.
+        
+        Args:
+            input_data: Hook input data
+            estimated_tokens: Token count estimated from transcript
+            model: Model name (for context window lookup)
+            
+        Returns:
+            context_update payload with is_estimate=True flag.
+        """
+        from . import tokenizer
+        
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        # Get model from input or use provided
+        if not model:
+            model = self.get_model(input_data)
+        
+        # Calculate context metrics
+        metrics = tokenizer.calculate_context_metrics(estimated_tokens, model)
+        
+        # Get project info
+        project_info = self.extract_project_info(input_data)
+        
+        return self.build_base_payload(
+            event='context_update',
+            session_id=session_id,
+            used_percentage=metrics['used_percentage'],
+            remaining_percentage=metrics['remaining_percentage'],
+            context_window_size=metrics['context_window_size'],
+            total_input_tokens=estimated_tokens,
+            total_output_tokens=0,
+            is_estimate=True,  # Flag to indicate this is an estimate
+            cwd=project_info['cwd'],
+            project_dir=project_info['project_path'],
+        )
+    
+    # =========================================================================
+    # Pre-Compact Payload (Context Metrics!)
+    # =========================================================================
+    
+    def build_pre_compact_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for context_update event from preCompact.
+        
+        This is the KEY event for Cursor that provides context metrics!
+        
+        Expected input fields from preCompact:
+        - context_usage_percent: Percentage of context used (0-100)
+        - context_tokens: Current token count
+        - context_window_size: Maximum context window
+        
+        NOTE: The 'model' field in preCompact is the SUMMARIZATION model
+        (typically gemini-2.5-flash), NOT the user's selected chat model.
+        We don't update model here - it should come from sessionStart.
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        # Extract context metrics
+        used_percentage = input_data.get('context_usage_percent', 0)
+        context_tokens = input_data.get('context_tokens', 0)
+        context_window_size = input_data.get('context_window_size', 0)
+        
+        # Calculate remaining percentage
+        remaining_percentage = 100 - used_percentage if used_percentage else 100
+        
+        # Get project info for cwd
+        project_info = self.extract_project_info(input_data)
+        
+        # NOTE: Don't use model from preCompact - it's the summarization model
+        # (gemini-2.5-flash), not the user's chat model. Leave model empty
+        # so it doesn't overwrite the correct model from sessionStart.
+        
+        return self.build_base_payload(
+            event='context_update',
+            session_id=session_id,
+            used_percentage=used_percentage,
+            remaining_percentage=remaining_percentage,
+            context_window_size=context_window_size,
+            total_input_tokens=context_tokens,
+            total_output_tokens=0,  # Cursor doesn't provide this
+            # Don't include model - let sessionStart model persist
+            cwd=project_info['cwd'],
+            project_dir=project_info['project_path'],
+        )
+    
+    # =========================================================================
+    # Activity Payload
+    # =========================================================================
+    
+    def build_activity_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for activity event.
+        
+        Called from postToolUse hook (post-tool-use.py).
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        # Extract project info for session title
+        project_info = self.extract_project_info(input_data)
+        session_title = self.generate_fallback_title(project_info['project'])
+        
+        tool_name = input_data.get('tool_name', 'unknown')
+        
+        return self.build_base_payload(
+            event='activity',
+            session_id=session_id,
+            session_title=session_title,
+            tool_name=tool_name,
+            terminal_pid=os.getppid(),
+        )
+    
+    # =========================================================================
+    # Session End Payload
+    # =========================================================================
+    
+    def build_session_end_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for session_end event.
+        
+        Called from sessionEnd hook (session-end.py).
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        return self.build_base_payload(
+            event='session_end',
+            session_id=session_id,
+            terminal_pid=os.getppid(),
+        )

package/hooks/adapters/skills.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""
+skills.py - Cursor Agent Skills Detection for Jacques
+
+Scans for installed Cursor agent skills and estimates their token overhead.
+
+IMPORTANT: Cursor does NOT inject full SKILL.md files into context!
+It only injects skill METADATA (name, description, path) - about 150-200 tokens per skill.
+
+Skill locations:
+- ~/.cursor/skills-cursor/*/SKILL.md - User-installed Cursor skills
+- ~/.claude/plugins/cache/**/SKILL.md - Claude plugins (superpowers, etc.)
+
+Typical overhead (CORRECTED):
+- 21 skills × ~200 tokens metadata = ~4,200 tokens
+- System prompts: ~2,000 tokens
+- Total: ~6,000-8,000 tokens (~3-4% on 176k context)
+"""
+import os
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+# Known skill directories
+SKILL_DIRECTORIES = [
+    Path.home() / '.cursor' / 'skills-cursor',
+    Path.home() / '.claude' / 'plugins' / 'cache',
+]
+
+# Tokens per skill METADATA (not full content!)
+# Cursor uses dynamic context discovery - only name + short description
+# are included statically. Full skill content loaded on-demand.
+# Estimated: ~5-10 tokens for name + ~30-50 tokens for description
+TOKENS_PER_SKILL_METADATA = 50
+
+# Base system prompt overhead (Cursor's internal prompts, tools, etc.)
+# Includes: tool definitions, system instructions, user rules
+SYSTEM_PROMPT_TOKENS = 2500
+
+# Cache for skill data (computed once per process)
+_skills_cache = None
+
+
+def find_skill_files() -> List[Path]:
+    """
+    Find all SKILL.md files in known locations.
+    
+    Returns:
+        List of paths to skill files.
+    """
+    skill_files = []
+    
+    for skill_dir in SKILL_DIRECTORIES:
+        if not skill_dir.exists():
+            continue
+        
+        # Recursively find all SKILL.md files
+        for skill_file in skill_dir.rglob('SKILL.md'):
+            skill_files.append(skill_file)
+    
+    return skill_files
+
+
+def extract_skill_description(skill_file: Path) -> str:
+    """
+    Extract the description from a SKILL.md file's frontmatter.
+    
+    Returns:
+        Description string, or empty if not found.
+    """
+    try:
+        content = skill_file.read_text(encoding='utf-8')
+        # Look for description in YAML frontmatter
+        match = re.search(r'^---\s*\n.*?description:\s*(.+?)\n.*?^---', content, re.MULTILINE | re.DOTALL)
+        if match:
+            return match.group(1).strip()
+    except Exception:
+        pass
+    return ""
+
+
+def estimate_skill_tokens() -> Tuple[int, int]:
+    """
+    Estimate total token overhead from installed skills.
+    
+    IMPORTANT: Cursor only injects skill METADATA, not full content!
+    Each skill adds ~200 tokens of metadata (name, description, path).
+    
+    Returns:
+        Tuple of (skill_count, estimated_tokens)
+    """
+    global _skills_cache
+    
+    if _skills_cache is not None:
+        return _skills_cache
+    
+    skill_files = find_skill_files()
+    skill_count = len(skill_files)
+    
+    # Cursor injects metadata only, not full skill content
+    # ~200 tokens per skill for the <agent_skill> tag with path and description
+    estimated_tokens = skill_count * TOKENS_PER_SKILL_METADATA
+    
+    _skills_cache = (skill_count, estimated_tokens)
+    return _skills_cache
+
+
+def get_initial_context_estimate(model: str = None) -> dict:
+    """
+    Get initial context estimate including skill metadata overhead.
+    
+    This provides a more accurate starting point than 0%.
+    
+    Args:
+        model: Model name for context window lookup
+        
+    Returns:
+        Dict with skill_count, estimated_tokens, and context metrics.
+    """
+    from . import tokenizer
+    
+    skill_count, skill_tokens = estimate_skill_tokens()
+    
+    # Total = skill metadata + system prompts
+    total_initial_tokens = skill_tokens + SYSTEM_PROMPT_TOKENS
+    
+    # Calculate context metrics
+    context_window = tokenizer.get_context_window(model)
+    used_percentage = tokenizer.calculate_context_percentage(total_initial_tokens, context_window)
+    
+    return {
+        'skill_count': skill_count,
+        'skill_tokens': skill_tokens,
+        'system_prompt_tokens': SYSTEM_PROMPT_TOKENS,
+        'total_initial_tokens': total_initial_tokens,
+        'used_percentage': round(used_percentage, 1),
+        'remaining_percentage': round(100 - used_percentage, 1),
+        'context_window_size': context_window,
+    }
+
+
+def get_skills_summary() -> str:
+    """
+    Get a human-readable summary of installed skills.
+    
+    Returns:
+        Summary string for logging/debugging.
+    """
+    skill_count, estimated_tokens = estimate_skill_tokens()
+    
+    return (
+        f"{skill_count} skills installed, "
+        f"~{estimated_tokens:,} tokens overhead"
+    )
+
+
+def clear_cache() -> None:
+    """Clear the skills cache (useful for testing or when skills change)."""
+    global _skills_cache
+    _skills_cache = None

package/hooks/adapters/template.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""
+template.py - Template Adapter for New Jacques Sources
+
+=============================================================================
+HOW TO ADD A NEW AI TOOL TO JACQUES
+=============================================================================
+
+This template shows how to create an adapter for a new AI tool.
+Follow these steps to add support for a new source:
+
+1. COPY this file and rename it (e.g., 'vscode.py')
+2. UPDATE the class name and source property
+3. IMPLEMENT the required methods:
+   - get_session_id(): Map your tool's session identifier field
+   - get_project_path(): Map your tool's project path field
+4. CREATE hook scripts in hooks/{your-source}/
+5. UPDATE hooks/adapters/__init__.py to export your adapter
+6. ADD installation support in hooks/install.py
+
+=============================================================================
+FIELD MAPPING REFERENCE
+=============================================================================
+
+Different AI tools use different field names. Here's how existing tools map:
+
+| Concept         | Claude Code CLI      | Cursor Native         | Your Tool     |
+|-----------------|---------------------|----------------------|---------------|
+| Session ID      | session_id          | conversation_id      | ???           |
+| Project Path    | workspace.project_dir| workspace_roots[0]  | ???           |
+| Model Name      | model               | model_name           | ???           |
+| Transcript      | transcript_path     | (none)               | ???           |
+| Context %       | statusLine event    | preCompact event     | ???           |
+
+=============================================================================
+"""
+from typing import Optional
+from .base import BaseAdapter
+
+
+class TemplateAdapter(BaseAdapter):
+    """
+    Template adapter for a new AI tool.
+    
+    Replace 'template' with your tool name (e.g., 'vscode', 'windsurf').
+    """
+    
+    @property
+    def source(self) -> str:
+        """
+        REQUIRED: Unique identifier for this source.
+        
+        This appears in the Jacques dashboard and is used for filtering.
+        Examples: 'claude_code', 'cursor', 'vscode', 'windsurf'
+        """
+        return 'template'  # TODO: Change this!
+    
+    def get_session_id(self, input_data: dict) -> Optional[str]:
+        """
+        REQUIRED: Extract session ID from your tool's input format.
+        
+        Find out what field your tool uses for the session/conversation ID
+        and extract it here.
+        
+        Examples:
+        - Claude Code: input_data.get('session_id')
+        - Cursor: input_data.get('conversation_id')
+        """
+        # TODO: Implement for your tool
+        return input_data.get('session_id')
+    
+    def get_project_path(self, input_data: dict) -> Optional[str]:
+        """
+        REQUIRED: Extract project path from your tool's input format.
+        
+        Find out what field your tool uses for the workspace/project path
+        and extract it here.
+        
+        Examples:
+        - Claude Code: input_data.get('workspace', {}).get('project_dir')
+        - Cursor: input_data.get('workspace_roots', [])[0]
+        """
+        # TODO: Implement for your tool
+        return input_data.get('project_path', '')
+    
+    # =========================================================================
+    # HOOK METHODS - Implement based on your tool's available hooks
+    # =========================================================================
+    
+    def build_session_start_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for session_start event.
+        
+        This is called when a new AI session begins.
+        
+        Typical hook names:
+        - Claude Code: SessionStart
+        - Cursor: sessionStart
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        project_info = self.extract_project_info(input_data)
+        
+        # Try to extract session title (if your tool supports transcripts)
+        transcript_path = input_data.get('transcript_path')
+        session_title = self.extract_session_title(transcript_path)
+        if not session_title:
+            session_title = self.generate_fallback_title(project_info['project'])
+        
+        terminal = self.get_terminal_identity()
+        terminal_key = self.build_terminal_key(terminal)
+        
+        return self.build_base_payload(
+            event='session_start',
+            session_id=session_id,
+            session_title=session_title,
+            transcript_path=transcript_path,
+            cwd=project_info['cwd'],
+            project=project_info['project'],
+            project_dir=project_info['project_path'],
+            model=input_data.get('model'),
+            hook_source='startup',
+            terminal=terminal,
+            terminal_key=terminal_key,
+        )
+    
+    def build_activity_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for activity event.
+        
+        This is called when the AI uses a tool or takes an action.
+        
+        Typical hook names:
+        - Claude Code: PostToolUse
+        - Cursor: postToolUse
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        project_info = self.extract_project_info(input_data)
+        session_title = self.generate_fallback_title(project_info['project'])
+        
+        return self.build_base_payload(
+            event='activity',
+            session_id=session_id,
+            session_title=session_title,
+            tool_name=input_data.get('tool_name', 'unknown'),
+            terminal_pid=self.get_terminal_identity()['terminal_pid'],
+        )
+    
+    def build_idle_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for idle event.
+        
+        This is called when the AI is waiting for user input.
+        
+        Typical hook names:
+        - Claude Code: Stop
+        - Cursor: (may not have equivalent)
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        return self.build_base_payload(
+            event='idle',
+            session_id=session_id,
+            terminal_pid=self.get_terminal_identity()['terminal_pid'],
+        )
+    
+    def build_session_end_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for session_end event.
+        
+        This is called when an AI session ends.
+        
+        Typical hook names:
+        - Claude Code: SessionEnd
+        - Cursor: sessionEnd
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        return self.build_base_payload(
+            event='session_end',
+            session_id=session_id,
+            terminal_pid=self.get_terminal_identity()['terminal_pid'],
+        )
+    
+    def build_context_update_payload(self, input_data: dict) -> Optional[dict]:
+        """
+        Build payload for context_update event.
+        
+        OPTIONAL: Only implement if your tool provides context metrics.
+        
+        This provides real-time context window usage data.
+        
+        Typical sources:
+        - Claude Code: statusLine (shell script, not Python hook)
+        - Cursor: preCompact event
+        
+        If your tool doesn't provide context metrics, Jacques will show
+        "N/A" for context percentage, which is fine.
+        """
+        session_id = self.validate_session_id(input_data)
+        if not session_id:
+            return None
+        
+        # TODO: Map your tool's context metric fields
+        # Example fields you might find:
+        # - context_usage_percent / used_percentage
+        # - context_tokens / total_tokens
+        # - context_window_size / max_tokens
+        
+        used_percentage = input_data.get('used_percentage', 0)
+        remaining_percentage = 100 - used_percentage
+        
+        project_info = self.extract_project_info(input_data)
+        
+        return self.build_base_payload(
+            event='context_update',
+            session_id=session_id,
+            used_percentage=used_percentage,
+            remaining_percentage=remaining_percentage,
+            context_window_size=input_data.get('context_window_size', 0),
+            total_input_tokens=input_data.get('total_input_tokens', 0),
+            total_output_tokens=input_data.get('total_output_tokens', 0),
+            model=input_data.get('model', 'unknown'),
+            model_display_name=input_data.get('model_display_name', 'Unknown'),
+            cwd=project_info['cwd'],
+            project_dir=project_info['project_path'],
+        )
+
+
+# =============================================================================
+# EXAMPLE HOOK SCRIPT
+# =============================================================================
+#
+# Create a file in hooks/{your-source}/session-start.py:
+#
+#     #!/usr/bin/env python3
+#     """Session start hook for {YourTool}."""
+#     import sys
+#     sys.path.insert(0, str(Path(__file__).parent.parent))
+#     from adapters.template import TemplateAdapter  # Change to your adapter
+#
+#     def main():
+#         adapter = TemplateAdapter()  # Change to your adapter
+#         input_data = adapter.parse_input()
+#         if not input_data:
+#             sys.exit(0)
+#         
+#         adapter.log_debug(input_data, 'session-start')
+#         payload = adapter.build_session_start_payload(input_data)
+#         if payload:
+#             adapter.send_event(payload, use_fallback=True)
+#
+#     if __name__ == '__main__':
+#         main()
+#
+# =============================================================================
+# TESTING YOUR ADAPTER
+# =============================================================================
+#
+# 1. Start Jacques server:
+#    cd server && npm run start
+#
+# 2. Test with sample input:
+#    echo '{"session_id": "test-123", "project_path": "/my/project"}' | \
+#    python3 hooks/{your-source}/session-start.py
+#
+# 3. Check server logs or dashboard for the session
+#
+# 4. Run unit tests:
+#    python3 -m pytest hooks/adapters/test_adapters.py -v
+#
+# =============================================================================