gobby 0.2.5__py3-none-any.whl

gobby/workflows/loader.py

@@ -0,0 +1,333 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .definitions import WorkflowDefinition
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DiscoveredWorkflow:
+    """A discovered workflow with metadata for ordering."""
+
+    name: str
+    definition: WorkflowDefinition
+    priority: int  # Lower = higher priority (runs first)
+    is_project: bool  # True if from project, False if global
+    path: Path
+
+
+class WorkflowLoader:
+    def __init__(self, workflow_dirs: list[Path] | None = None):
+        # Default global workflow directory
+        self.global_dirs = workflow_dirs or [Path.home() / ".gobby" / "workflows"]
+        self._cache: dict[str, WorkflowDefinition] = {}
+        # Cache for discovered workflows per project path
+        self._discovery_cache: dict[str, list[DiscoveredWorkflow]] = {}
+
+    def load_workflow(
+        self,
+        name: str,
+        project_path: Path | str | None = None,
+        _inheritance_chain: list[str] | None = None,
+    ) -> WorkflowDefinition | None:
+        """
+        Load a workflow by name (without extension).
+        Supports inheritance via 'extends' field with cycle detection.
+
+        Args:
+            name: Workflow name (without .yaml extension)
+            project_path: Optional project directory for project-specific workflows.
+                         Searches: 1) {project_path}/.gobby/workflows/  2) ~/.gobby/workflows/
+            _inheritance_chain: Internal parameter for cycle detection. Do not pass directly.
+
+        Raises:
+            ValueError: If circular inheritance is detected.
+        """
+        # Initialize or check inheritance chain for cycle detection
+        if _inheritance_chain is None:
+            _inheritance_chain = []
+
+        if name in _inheritance_chain:
+            cycle_path = " -> ".join(_inheritance_chain + [name])
+            logger.error(f"Circular workflow inheritance detected: {cycle_path}")
+            raise ValueError(f"Circular workflow inheritance detected: {cycle_path}")
+        # Build cache key including project path for project-specific caching
+        cache_key = f"{project_path or 'global'}:{name}"
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        # Build search directories: project-specific first, then global
+        search_dirs = list(self.global_dirs)
+        if project_path:
+            project_dir = Path(project_path) / ".gobby" / "workflows"
+            search_dirs.insert(0, project_dir)
+
+        # 1. Find file
+        path = self._find_workflow_file(name, search_dirs)
+        if not path:
+            logger.warning(f"Workflow '{name}' not found in {search_dirs}")
+            return None
+
+        try:
+            # 2. Parse YAML
+            with open(path) as f:
+                data = yaml.safe_load(f)
+
+            # 3. Handle inheritance with cycle detection
+            if "extends" in data:
+                parent_name = data["extends"]
+                # Add current workflow to chain before loading parent
+                parent = self.load_workflow(
+                    parent_name,
+                    project_path=project_path,
+                    _inheritance_chain=_inheritance_chain + [name],
+                )
+                if parent:
+                    data = self._merge_workflows(parent.model_dump(), data)
+                else:
+                    logger.error(f"Parent workflow '{parent_name}' not found for '{name}'")
+
+            # 4. Validate and create model
+            definition = WorkflowDefinition(**data)
+            self._cache[cache_key] = definition
+            return definition
+
+        except ValueError:
+            # Re-raise ValueError (used for cycle detection)
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load workflow '{name}' from {path}: {e}", exc_info=True)
+            return None
+
+    def _find_workflow_file(self, name: str, search_dirs: list[Path]) -> Path | None:
+        filename = f"{name}.yaml"
+        for d in search_dirs:
+            # Check root directory
+            candidate = d / filename
+            if candidate.exists():
+                return candidate
+            # Check subdirectories (lifecycle/, etc.)
+            for subdir in d.iterdir() if d.exists() else []:
+                if subdir.is_dir():
+                    candidate = subdir / filename
+                    if candidate.exists():
+                        return candidate
+        return None
+
+    def _merge_workflows(self, parent: dict[str, Any], child: dict[str, Any]) -> dict[str, Any]:
+        """
+        Deep merge parent and child workflow dicts.
+        Child overrides parent.
+        """
+        merged = parent.copy()
+
+        for key, value in child.items():
+            if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+                merged[key] = self._merge_workflows(merged[key], value)
+            elif key in ("phases", "steps") and ("phases" in merged or "steps" in merged):
+                # Special handling for steps/phases: merge by name
+                # Support both 'steps' (new) and 'phases' (legacy YAML)
+                parent_list = merged.get("phases") or merged.get("steps", [])
+                merged_key = "phases" if "phases" in merged else "steps"
+                merged[merged_key] = self._merge_steps(parent_list, value)
+            else:
+                merged[key] = value
+
+        return merged
+
+    def _merge_steps(self, parent_steps: list[Any], child_steps: list[Any]) -> list[Any]:
+        """
+        Merge step lists by step name.
+        """
+        # Convert parent list to dict by name, creating copies to avoid mutating originals
+        parent_map: dict[str, dict[str, Any]] = {}
+        for s in parent_steps:
+            if "name" not in s:
+                logger.warning("Skipping parent step without 'name' key")
+                continue
+            # Create a shallow copy to avoid mutating the original
+            parent_map[s["name"]] = dict(s)
+
+        for child_step in child_steps:
+            if "name" not in child_step:
+                logger.warning("Skipping child step without 'name' key")
+                continue
+            name = child_step["name"]
+            if name in parent_map:
+                # Merge existing step by updating the copy with child values
+                parent_map[name].update(child_step)
+            else:
+                # Add new step as a copy
+                parent_map[name] = dict(child_step)
+
+        return list(parent_map.values())
+
+    def discover_lifecycle_workflows(
+        self, project_path: Path | str | None = None
+    ) -> list[DiscoveredWorkflow]:
+        """
+        Discover all lifecycle workflows from project and global directories.
+
+        Returns workflows sorted by:
+        1. Project workflows first (is_project=True), then global
+        2. Within each group: by priority (ascending), then alphabetically by name
+
+        Project workflows shadow global workflows with the same name.
+
+        Args:
+            project_path: Optional project directory. If provided, searches
+                         {project_path}/.gobby/workflows/ first.
+
+        Returns:
+            List of DiscoveredWorkflow objects, sorted and deduplicated.
+        """
+        cache_key = str(project_path) if project_path else "global"
+
+        # Check cache
+        if cache_key in self._discovery_cache:
+            return self._discovery_cache[cache_key]
+
+        discovered: dict[str, DiscoveredWorkflow] = {}  # name -> workflow (for shadowing)
+
+        # 1. Scan global lifecycle directory first (will be shadowed by project)
+        for global_dir in self.global_dirs:
+            self._scan_directory(global_dir / "lifecycle", is_project=False, discovered=discovered)
+
+        # 2. Scan project lifecycle directory (shadows global)
+        if project_path:
+            project_dir = Path(project_path) / ".gobby" / "workflows" / "lifecycle"
+            self._scan_directory(project_dir, is_project=True, discovered=discovered)
+
+        # 3. Filter to lifecycle workflows only
+        lifecycle_workflows = [w for w in discovered.values() if w.definition.type == "lifecycle"]
+
+        # 4. Sort: project first, then by priority (asc), then by name (alpha)
+        sorted_workflows = sorted(
+            lifecycle_workflows,
+            key=lambda w: (
+                0 if w.is_project else 1,  # Project first
+                w.priority,  # Lower priority = runs first
+                w.name,  # Alphabetical
+            ),
+        )
+
+        # Cache and return
+        self._discovery_cache[cache_key] = sorted_workflows
+        return sorted_workflows
+
+    def _scan_directory(
+        self,
+        directory: Path,
+        is_project: bool,
+        discovered: dict[str, DiscoveredWorkflow],
+    ) -> None:
+        """
+        Scan a directory for workflow YAML files and add to discovered dict.
+
+        Args:
+            directory: Directory to scan
+            is_project: Whether this is a project directory (for shadowing)
+            discovered: Dict to update (name -> DiscoveredWorkflow)
+        """
+        if not directory.exists():
+            return
+
+        for yaml_path in directory.glob("*.yaml"):
+            name = yaml_path.stem
+            try:
+                with open(yaml_path) as f:
+                    data = yaml.safe_load(f)
+
+                if not data:
+                    continue
+
+                # Handle inheritance with cycle detection
+                if "extends" in data:
+                    parent_name = data["extends"]
+                    try:
+                        parent = self.load_workflow(
+                            parent_name,
+                            _inheritance_chain=[name],
+                        )
+                        if parent:
+                            data = self._merge_workflows(parent.model_dump(), data)
+                    except ValueError as e:
+                        logger.warning(f"Skipping workflow {name}: {e}")
+                        continue
+
+                definition = WorkflowDefinition(**data)
+
+                # Get priority from workflow settings or default to 100
+                priority = 100
+                if definition.settings and "priority" in definition.settings:
+                    priority = definition.settings["priority"]
+
+                # Project workflows shadow global (overwrite in dict)
+                # Global is scanned first, so project overwrites
+                discovered[name] = DiscoveredWorkflow(
+                    name=name,
+                    definition=definition,
+                    priority=priority,
+                    is_project=is_project,
+                    path=yaml_path,
+                )
+
+            except Exception as e:
+                logger.warning(f"Failed to load workflow from {yaml_path}: {e}")
+
+    def clear_cache(self) -> None:
+        """
+        Clear the workflow definitions and discovery cache.
+        Call when workflows may have changed on disk.
+        """
+        self._cache.clear()
+        self._discovery_cache.clear()
+
+    def clear_discovery_cache(self) -> None:
+        """Clear the discovery cache. Call when workflows may have changed."""
+        # Deprecated: use clear_cache instead to clear everything
+        self.clear_cache()
+
+    def validate_workflow_for_agent(
+        self,
+        workflow_name: str,
+        project_path: Path | str | None = None,
+    ) -> tuple[bool, str | None]:
+        """
+        Validate that a workflow can be used for agent spawning.
+
+        Lifecycle workflows run automatically via hooks and cannot be
+        explicitly activated for agents. Only step workflows are valid.
+
+        Args:
+            workflow_name: Name of the workflow to validate
+            project_path: Optional project path for workflow resolution
+
+        Returns:
+            Tuple of (is_valid, error_message).
+            If valid, returns (True, None).
+            If invalid, returns (False, error_message).
+        """
+        try:
+            workflow = self.load_workflow(workflow_name, project_path=project_path)
+        except ValueError as e:
+            # Circular inheritance or other workflow loading errors
+            return False, f"Failed to load workflow '{workflow_name}': {e}"
+
+        if not workflow:
+            # Workflow not found - let the caller decide if this is an error
+            return True, None
+
+        if workflow.type == "lifecycle":
+            return False, (
+                f"Cannot use lifecycle workflow '{workflow_name}' for agent spawning. "
+                f"Lifecycle workflows run automatically on events. "
+                f"Use a step workflow like 'plan-execute' instead."
+            )
+
+        return True, None

gobby/workflows/mcp_actions.py

@@ -0,0 +1,60 @@
+"""MCP tool invocation workflow actions.
+
+Extracted from actions.py as part of strangler fig decomposition.
+These functions handle MCP tool calls from workflows.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+async def call_mcp_tool(
+    mcp_manager: Any,
+    state: Any,
+    server_name: str | None,
+    tool_name: str | None,
+    arguments: dict[str, Any] | None = None,
+    output_as: str | None = None,
+) -> dict[str, Any]:
+    """Call an MCP tool on a connected server.
+
+    Args:
+        mcp_manager: MCP client manager instance
+        state: WorkflowState object for storing results
+        server_name: Name of the MCP server
+        tool_name: Name of the tool to call
+        arguments: Arguments to pass to the tool
+        output_as: Optional variable name to store result
+
+    Returns:
+        Dict with result and stored_as, or error
+    """
+    if not server_name or not tool_name:
+        return {"error": "Missing server_name or tool_name"}
+
+    if not mcp_manager:
+        logger.warning("call_mcp_tool: MCP manager not available")
+        return {"error": "MCP manager not available"}
+
+    try:
+        # Check connection
+        if server_name not in mcp_manager.connections:
+            return {"error": f"Server {server_name} not connected"}
+
+        # Call tool
+        result = await mcp_manager.call_tool(server_name, tool_name, arguments or {})
+
+        # Store result in workflow variable if 'as' specified
+        if output_as:
+            if state is None:
+                raise ValueError("state must be provided when output_as is specified")
+            if not state.variables:
+                state.variables = {}
+            state.variables[output_as] = result
+
+        return {"result": result, "stored_as": output_as}
+    except Exception as e:
+        logger.error(f"call_mcp_tool: Failed: {e}")
+        return {"error": str(e)}

gobby/workflows/memory_actions.py

@@ -0,0 +1,272 @@
+"""Memory-related workflow actions.
+
+Extracted from actions.py as part of strangler fig decomposition.
+These functions handle memory injection, extraction, saving, and recall.
+"""
+
+import hashlib
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _content_fingerprint(content: str) -> str:
+    """Generate a secure fingerprint of content for logging (avoids PII exposure)."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
+
+
+async def memory_sync_import(memory_sync_manager: Any) -> dict[str, Any]:
+    """Import memories from filesystem.
+
+    Args:
+        memory_sync_manager: The memory sync manager instance
+
+    Returns:
+        Dict with imported count or error
+    """
+    if not memory_sync_manager:
+        return {"error": "Memory Sync Manager not available"}
+
+    count = await memory_sync_manager.import_from_files()
+    logger.info(f"Memory sync import: {count} memories imported")
+    return {"imported": {"memories": count}}
+
+
+async def memory_sync_export(memory_sync_manager: Any) -> dict[str, Any]:
+    """Export memories to filesystem.
+
+    Args:
+        memory_sync_manager: The memory sync manager instance
+
+    Returns:
+        Dict with exported count or error
+    """
+    if not memory_sync_manager:
+        return {"error": "Memory Sync Manager not available"}
+
+    count = await memory_sync_manager.export_to_files()
+    logger.info(f"Memory sync export: {count} memories exported")
+    return {"exported": {"memories": count}}
+
+
+async def memory_save(
+    memory_manager: Any,
+    session_manager: Any,
+    session_id: str,
+    content: str | None = None,
+    memory_type: str = "fact",
+    importance: float = 0.5,
+    tags: list[str] | None = None,
+    project_id: str | None = None,
+) -> dict[str, Any] | None:
+    """Save a memory directly from workflow context.
+
+    Args:
+        memory_manager: The memory manager instance
+        session_manager: The session manager instance
+        session_id: Current session ID
+        content: The memory content to save (required)
+        memory_type: One of 'fact', 'preference', 'pattern', 'context'
+        importance: Float 0.0-1.0
+        tags: List of string tags
+        project_id: Override project ID
+
+    Returns:
+        Dict with saved status and memory_id, or error
+    """
+    if not memory_manager:
+        return {"error": "Memory Manager not available"}
+
+    if not memory_manager.config.enabled:
+        return None
+
+    if not content:
+        return {"error": "Missing required 'content' parameter"}
+
+    # Resolve project_id
+    if not project_id:
+        session = session_manager.get(session_id)
+        if session:
+            project_id = session.project_id
+
+    if not project_id:
+        return {"error": "No project_id found"}
+
+    # Validate memory_type
+    if memory_type not in ("fact", "preference", "pattern", "context"):
+        memory_type = "fact"
+
+    # Validate importance
+    if not isinstance(importance, int | float):
+        importance = 0.5
+    importance = max(0.0, min(1.0, float(importance)))
+
+    # Validate tags
+    if tags is None:
+        tags = []
+    if not isinstance(tags, list):
+        tags = []
+
+    try:
+        if memory_manager.content_exists(content, project_id):
+            logger.debug(f"save_memory: Skipping duplicate: {content[:50]}...")
+            return {"saved": False, "reason": "duplicate"}
+
+        memory = await memory_manager.remember(
+            content=content,
+            memory_type=memory_type,
+            importance=importance,
+            project_id=project_id,
+            source_type="workflow",
+            source_session_id=session_id,
+            tags=tags,
+        )
+
+        logger.info(f"save_memory: Created {memory_type} memory: {content[:50]}...")
+        return {
+            "saved": True,
+            "memory_id": memory.id,
+            "memory_type": memory_type,
+            "importance": importance,
+        }
+
+    except Exception as e:
+        logger.error(f"save_memory: Failed: {e}", exc_info=True)
+        return {"error": str(e)}
+
+
+async def memory_recall_relevant(
+    memory_manager: Any,
+    session_manager: Any,
+    session_id: str,
+    prompt_text: str | None = None,
+    project_id: str | None = None,
+    limit: int = 5,
+    min_importance: float = 0.3,
+    state: Any | None = None,
+) -> dict[str, Any] | None:
+    """Recall memories relevant to the current user prompt.
+
+    Args:
+        memory_manager: The memory manager instance
+        session_manager: The session manager instance
+        session_id: Current session ID
+        prompt_text: The user's prompt text
+        project_id: Override project ID
+        limit: Max memories to retrieve
+        min_importance: Minimum importance threshold
+        state: WorkflowState for tracking injected memory IDs (for deduplication)
+
+    Returns:
+        Dict with inject_context and count, or None if disabled
+    """
+    if not memory_manager:
+        return None
+
+    if not memory_manager.config.enabled:
+        return None
+
+    if not prompt_text:
+        logger.debug("memory_recall_relevant: No prompt_text provided")
+        return None
+
+    # Skip for very short prompts or commands
+    if len(prompt_text.strip()) < 10 or prompt_text.strip().startswith("/"):
+        logger.debug("memory_recall_relevant: Skipping short/command prompt")
+        return None
+
+    # Resolve project_id
+    if not project_id:
+        session = session_manager.get(session_id)
+        if session:
+            project_id = session.project_id
+
+    # Get already-injected memory IDs from state for deduplication
+    injected_ids: set[str] = set()
+    if state is not None:
+        # Access variables dict, defaulting to empty if not set
+        variables = getattr(state, "variables", None) or {}
+        injected_ids = set(variables.get("_injected_memory_ids", []))
+
+    try:
+        memories = memory_manager.recall(
+            query=prompt_text,
+            project_id=project_id,
+            limit=limit,
+            min_importance=min_importance,
+            use_semantic=True,
+        )
+
+        if not memories:
+            logger.debug("memory_recall_relevant: No relevant memories found")
+            return {"injected": False, "count": 0}
+
+        # Filter out memories that have already been injected in this session
+        new_memories = [m for m in memories if m.id not in injected_ids]
+
+        if not new_memories:
+            logger.debug(
+                f"memory_recall_relevant: All {len(memories)} memories already injected, skipping"
+            )
+            return {"injected": False, "count": 0, "skipped": len(memories)}
+
+        from gobby.memory.context import build_memory_context
+
+        memory_context = build_memory_context(new_memories)
+
+        # Track newly injected memory IDs in state
+        if state is not None:
+            new_ids = {m.id for m in new_memories}
+            all_injected = injected_ids | new_ids
+            # Ensure variables dict exists
+            if not hasattr(state, "variables") or state.variables is None:
+                state.variables = {}
+            state.variables["_injected_memory_ids"] = list(all_injected)
+            logger.debug(
+                f"memory_recall_relevant: Tracking {len(new_ids)} new IDs, "
+                f"{len(all_injected)} total injected"
+            )
+
+        logger.info(f"memory_recall_relevant: Injecting {len(new_memories)} relevant memories")
+
+        return {
+            "inject_context": memory_context,
+            "injected": True,
+            "count": len(new_memories),
+        }
+
+    except Exception as e:
+        logger.error(f"memory_recall_relevant: Failed: {e}", exc_info=True)
+        return {"error": str(e)}
+
+
+def reset_memory_injection_tracking(state: Any | None = None) -> dict[str, Any]:
+    """Reset the memory injection tracking, allowing previously injected memories to be recalled again.
+
+    This should be called on pre_compact hook or /clear command so memories can be
+    re-injected after context loss.
+
+    Args:
+        state: WorkflowState containing the injection tracking in variables
+
+    Returns:
+        Dict with cleared count and success status
+    """
+    if state is None:
+        logger.debug("reset_memory_injection_tracking: No state provided")
+        return {"success": False, "cleared": 0, "reason": "no_state"}
+
+    variables = getattr(state, "variables", None)
+    if variables is None:
+        logger.debug("reset_memory_injection_tracking: No variables in state")
+        return {"success": True, "cleared": 0}
+
+    injected_ids = variables.get("_injected_memory_ids", [])
+    cleared_count = len(injected_ids)
+
+    if cleared_count > 0:
+        variables["_injected_memory_ids"] = []
+        logger.info(f"reset_memory_injection_tracking: Cleared {cleared_count} injected memory IDs")
+
+    return {"success": True, "cleared": cleared_count}