gobby 0.2.8__py3-none-any.whl → 0.2.9__py3-none-any.whl

gobby/mcp_proxy/tools/workflows/_import.py

@@ -0,0 +1,112 @@
+"""
+Import and cache tools for workflows.
+"""
+
+import logging
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from gobby.utils.project_context import get_workflow_project_path
+from gobby.workflows.loader import WorkflowLoader
+
+logger = logging.getLogger(__name__)
+
+
+def import_workflow(
+    loader: WorkflowLoader,
+    source_path: str,
+    workflow_name: str | None = None,
+    is_global: bool = False,
+    project_path: str | None = None,
+) -> dict[str, Any]:
+    """
+    Import a workflow from a file.
+
+    Args:
+        loader: WorkflowLoader instance
+        source_path: Path to the workflow YAML file
+        workflow_name: Override the workflow name (defaults to name in file)
+        is_global: Install to global ~/.gobby/workflows instead of project
+        project_path: Project directory path. Auto-discovered from cwd if not provided.
+
+    Returns:
+        Success status and destination path
+    """
+    source = Path(source_path)
+    if not source.exists():
+        return {"success": False, "error": f"File not found: {source_path}"}
+
+    if source.suffix != ".yaml":
+        return {"success": False, "error": "Workflow file must have .yaml extension"}
+
+    try:
+        with open(source, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        if not data or "name" not in data:
+            return {"success": False, "error": "Invalid workflow: missing 'name' field"}
+
+    except yaml.YAMLError as e:
+        return {"success": False, "error": f"Invalid YAML: {e}"}
+
+    raw_name = workflow_name or data.get("name", source.stem)
+    # Sanitize name to prevent path traversal: strip path components, allow only safe chars
+    safe_name = Path(raw_name).name  # Strip any path components
+    safe_name = re.sub(r"[^a-zA-Z0-9_\-.]", "_", safe_name)  # Replace unsafe chars
+    safe_name = safe_name.strip("._")  # Remove leading/trailing dots and underscores
+    if not safe_name:
+        safe_name = source.stem  # Fallback to source filename
+    filename = f"{safe_name}.yaml"
+
+    if is_global:
+        dest_dir = Path.home() / ".gobby" / "workflows"
+    else:
+        # Auto-discover project path if not provided
+        if not project_path:
+            discovered = get_workflow_project_path()
+            if discovered:
+                project_path = str(discovered)
+
+        proj = Path(project_path) if project_path else None
+        if not proj:
+            return {
+                "success": False,
+                "error": "project_path required when not using is_global (could not auto-discover)",
+            }
+        dest_dir = proj / ".gobby" / "workflows"
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_path = dest_dir / filename
+
+    shutil.copy(source, dest_path)
+
+    # Clear loader cache so new workflow is discoverable
+    loader.clear_cache()
+
+    return {
+        "success": True,
+        "workflow_name": safe_name,
+        "destination": str(dest_path),
+        "is_global": is_global,
+    }
+
+
+def reload_cache(loader: WorkflowLoader) -> dict[str, Any]:
+    """
+    Clear the workflow loader cache.
+
+    This forces the daemon to re-read workflow YAML files from disk
+    on the next access. Use this when you've modified workflow files
+    and want the changes to take effect immediately without restarting
+    the daemon.
+
+    Returns:
+        Success status
+    """
+    loader.clear_cache()
+    logger.info("Workflow cache cleared via reload_cache tool")
+    return {"message": "Workflow cache cleared"}

gobby/mcp_proxy/tools/workflows/_lifecycle.py

@@ -0,0 +1,321 @@
+"""
+Lifecycle tools for workflows (activate, end, transition).
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from gobby.mcp_proxy.tools.workflows._resolution import (
+    resolve_session_id,
+    resolve_session_task_value,
+)
+from gobby.storage.database import DatabaseProtocol
+from gobby.storage.sessions import LocalSessionManager
+from gobby.utils.project_context import get_workflow_project_path
+from gobby.workflows.definitions import WorkflowState
+from gobby.workflows.loader import WorkflowLoader
+from gobby.workflows.state_manager import WorkflowStateManager
+
+
+def activate_workflow(
+    loader: WorkflowLoader,
+    state_manager: WorkflowStateManager,
+    session_manager: LocalSessionManager,
+    db: DatabaseProtocol,
+    name: str,
+    session_id: str | None = None,
+    initial_step: str | None = None,
+    variables: dict[str, Any] | None = None,
+    project_path: str | None = None,
+) -> dict[str, Any]:
+    """
+    Activate a step-based workflow for the current session.
+
+    Args:
+        loader: WorkflowLoader instance
+        state_manager: WorkflowStateManager instance
+        session_manager: LocalSessionManager instance
+        db: LocalDatabase instance
+        name: Workflow name (e.g., "plan-act-reflect", "auto-task")
+        session_id: Session reference (accepts #N, N, UUID, or prefix) - required to prevent cross-session bleed
+        initial_step: Optional starting step (defaults to first step)
+        variables: Optional initial variables to set (merged with workflow defaults)
+        project_path: Project directory path. Auto-discovered from cwd if not provided.
+
+    Returns:
+        Success status, workflow info, and current step.
+    """
+    # Auto-discover project path if not provided
+    if not project_path:
+        discovered = get_workflow_project_path()
+        if discovered:
+            project_path = str(discovered)
+
+    proj = Path(project_path) if project_path else None
+
+    # Load workflow
+    definition = loader.load_workflow(name, proj)
+    if not definition:
+        return {"success": False, "error": f"Workflow '{name}' not found"}
+
+    if definition.type == "lifecycle":
+        return {
+            "success": False,
+            "error": f"Workflow '{name}' is lifecycle type (auto-runs on events, not manually activated)",
+        }
+
+    # Require explicit session_id to prevent cross-session bleed
+    if not session_id:
+        return {
+            "success": False,
+            "error": "session_id is required. Pass the session ID explicitly to prevent cross-session variable bleed.",
+        }
+
+    # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+    try:
+        resolved_session_id = resolve_session_id(session_manager, session_id)
+    except ValueError as e:
+        return {"success": False, "error": str(e)}
+
+    # Check for existing workflow
+    # Allow if:
+    # - No existing state
+    # - Existing is __lifecycle__ placeholder
+    # - Existing is a lifecycle-type workflow (they run concurrently with step workflows)
+    existing = state_manager.get_state(resolved_session_id)
+    if existing and existing.workflow_name != "__lifecycle__":
+        # Check if existing workflow is a lifecycle type
+        existing_def = loader.load_workflow(existing.workflow_name, proj)
+        # Only allow if we can confirm it's a lifecycle workflow
+        # If definition not found or it's a step workflow, block activation
+        if not existing_def or existing_def.type != "lifecycle":
+            # It's a step workflow (or unknown) - can only have one active
+            return {
+                "success": False,
+                "error": f"Session already has step workflow '{existing.workflow_name}' active. Use end_workflow first.",
+            }
+        # Existing is a lifecycle workflow - allow step workflow to activate alongside it
+
+    # Determine initial step
+    if initial_step:
+        if not any(s.name == initial_step for s in definition.steps):
+            return {
+                "success": False,
+                "error": f"Step '{initial_step}' not found. Available: {[s.name for s in definition.steps]}",
+            }
+        step = initial_step
+    else:
+        if not definition.steps:
+            return {
+                "success": False,
+                "error": f"Workflow '{name}' has no steps defined. Cannot activate a workflow without steps.",
+            }
+        step = definition.steps[0].name
+
+    # Merge variables: preserve existing lifecycle variables, then apply workflow declarations
+    # Priority: existing state < workflow defaults < passed-in variables
+    # This preserves lifecycle variables (like unlocked_tools) that the step workflow doesn't declare
+    merged_variables = dict(existing.variables) if existing else {}
+    merged_variables.update(definition.variables)  # Override with workflow-declared defaults
+    if variables:
+        merged_variables.update(variables)  # Override with passed-in values
+
+    # Resolve session_task references (#N or N) to UUIDs upfront
+    # This prevents repeated resolution failures in condition evaluation
+    if "session_task" in merged_variables:
+        session_task_val = merged_variables["session_task"]
+        if isinstance(session_task_val, str):
+            merged_variables["session_task"] = resolve_session_task_value(
+                session_task_val, resolved_session_id, session_manager, db
+            )
+
+    # Create state
+    state = WorkflowState(
+        session_id=resolved_session_id,
+        workflow_name=name,
+        step=step,
+        step_entered_at=datetime.now(UTC),
+        step_action_count=0,
+        total_action_count=0,
+        artifacts={},
+        observations=[],
+        reflection_pending=False,
+        context_injected=False,
+        variables=merged_variables,
+        task_list=None,
+        current_task_index=0,
+        files_modified_this_task=0,
+    )
+
+    state_manager.save_state(state)
+
+    return {
+        "success": True,
+        "session_id": resolved_session_id,
+        "workflow": name,
+        "step": step,
+        "steps": [s.name for s in definition.steps],
+        "variables": merged_variables,
+    }
+
+
+def end_workflow(
+    loader: WorkflowLoader,
+    state_manager: WorkflowStateManager,
+    session_manager: LocalSessionManager,
+    session_id: str | None = None,
+    reason: str | None = None,
+    project_path: str | None = None,
+) -> dict[str, Any]:
+    """
+    End the currently active step-based workflow.
+
+    Allows starting a different workflow afterward.
+    Does not affect lifecycle workflows (they continue running).
+
+    Args:
+        loader: WorkflowLoader instance
+        state_manager: WorkflowStateManager instance
+        session_manager: LocalSessionManager instance
+        session_id: Session reference (accepts #N, N, UUID, or prefix) - required to prevent cross-session bleed
+        reason: Optional reason for ending
+        project_path: Project directory path. Auto-discovered from cwd if not provided.
+
+    Returns:
+        Success status
+    """
+    # Require explicit session_id to prevent cross-session bleed
+    if not session_id:
+        return {
+            "success": False,
+            "error": "session_id is required. Pass the session ID explicitly to prevent cross-session variable bleed.",
+        }
+
+    # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+    try:
+        resolved_session_id = resolve_session_id(session_manager, session_id)
+    except ValueError as e:
+        return {"success": False, "error": str(e)}
+
+    state = state_manager.get_state(resolved_session_id)
+    if not state:
+        return {"success": False, "error": "No workflow active for session"}
+
+    # Check if this is a lifecycle workflow - those cannot be ended manually
+    # Auto-discover project path if not provided
+    if not project_path:
+        discovered = get_workflow_project_path()
+        if discovered:
+            project_path = str(discovered)
+
+    proj = Path(project_path) if project_path else None
+    definition = loader.load_workflow(state.workflow_name, proj)
+
+    # If definition exists and is lifecycle type, block manual ending
+    if definition and definition.type == "lifecycle":
+        return {
+            "success": False,
+            "error": f"Workflow '{state.workflow_name}' is lifecycle type (auto-runs on events, cannot be manually ended).",
+        }
+
+    state_manager.delete_state(resolved_session_id)
+
+    return {"success": True, "workflow": state.workflow_name, "reason": reason}
+
+
+def request_step_transition(
+    loader: WorkflowLoader,
+    state_manager: WorkflowStateManager,
+    session_manager: LocalSessionManager,
+    to_step: str,
+    reason: str | None = None,
+    session_id: str | None = None,
+    force: bool = False,
+    project_path: str | None = None,
+) -> dict[str, Any]:
+    """
+    Request transition to a different step. May require approval.
+
+    Args:
+        loader: WorkflowLoader instance
+        state_manager: WorkflowStateManager instance
+        session_manager: LocalSessionManager instance
+        to_step: Target step name
+        reason: Reason for transition
+        session_id: Session reference (accepts #N, N, UUID, or prefix) - required to prevent cross-session bleed
+        force: Skip exit condition checks
+        project_path: Project directory path. Auto-discovered from cwd if not provided.
+
+    Returns:
+        Success status and new step info
+    """
+    # Auto-discover project path if not provided
+    if not project_path:
+        discovered = get_workflow_project_path()
+        if discovered:
+            project_path = str(discovered)
+
+    proj = Path(project_path) if project_path else None
+
+    # Require explicit session_id to prevent cross-session bleed
+    if not session_id:
+        return {
+            "success": False,
+            "error": "session_id is required. Pass the session ID explicitly to prevent cross-session variable bleed.",
+        }
+
+    # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+    try:
+        resolved_session_id = resolve_session_id(session_manager, session_id)
+    except ValueError as e:
+        return {"success": False, "error": str(e)}
+
+    state = state_manager.get_state(resolved_session_id)
+    if not state:
+        return {"success": False, "error": "No workflow active for session"}
+
+    # Load workflow to validate step
+    definition = loader.load_workflow(state.workflow_name, proj)
+    if not definition:
+        return {"success": False, "error": f"Workflow '{state.workflow_name}' not found"}
+
+    if not any(s.name == to_step for s in definition.steps):
+        return {
+            "success": False,
+            "error": f"Step '{to_step}' not found. Available: {[s.name for s in definition.steps]}",
+        }
+
+    # Block manual transitions to steps that have conditional auto-transitions
+    # These steps should only be reached when their conditions are met
+    # Skip this check when force=True to allow bypassing workflow guards
+    if not force:
+        current_step_def = next((s for s in definition.steps if s.name == state.step), None)
+        if current_step_def and current_step_def.transitions:
+            for transition in current_step_def.transitions:
+                if transition.to == to_step and transition.when:
+                    # This step has a conditional transition - block manual transition
+                    return {
+                        "success": False,
+                        "error": (
+                            f"Step '{to_step}' has a conditional auto-transition "
+                            f"(when: {transition.when}). Manual transitions to this step "
+                            f"are blocked to prevent workflow circumvention. "
+                            f"The transition will occur automatically when the condition is met."
+                        ),
+                    }
+
+    old_step = state.step
+    state.step = to_step
+    state.step_entered_at = datetime.now(UTC)
+    state.step_action_count = 0
+
+    state_manager.save_state(state)
+
+    return {
+        "success": True,
+        "from_step": old_step,
+        "to_step": to_step,
+        "reason": reason,
+        "forced": force,
+    }

gobby/mcp_proxy/tools/workflows/_query.py

@@ -0,0 +1,207 @@
+"""
+Query tools for workflows.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from gobby.mcp_proxy.tools.workflows._resolution import resolve_session_id
+from gobby.storage.sessions import LocalSessionManager
+from gobby.utils.project_context import get_workflow_project_path
+from gobby.workflows.loader import WorkflowLoader
+from gobby.workflows.state_manager import WorkflowStateManager
+
+logger = logging.getLogger(__name__)
+
+
+def get_workflow(
+    loader: WorkflowLoader,
+    name: str,
+    project_path: str | None = None,
+) -> dict[str, Any]:
+    """
+    Get workflow details including steps, triggers, and settings.
+
+    Args:
+        loader: WorkflowLoader instance
+        name: Workflow name (without .yaml extension)
+        project_path: Project directory path. Auto-discovered from cwd if not provided.
+
+    Returns:
+        Workflow definition details
+    """
+    # Auto-discover project path if not provided
+    if not project_path:
+        discovered = get_workflow_project_path()
+        if discovered:
+            project_path = str(discovered)
+
+    proj = Path(project_path) if project_path else None
+    definition = loader.load_workflow(name, proj)
+
+    if not definition:
+        return {"success": False, "error": f"Workflow '{name}' not found"}
+
+    return {
+        "success": True,
+        "name": definition.name,
+        "type": definition.type,
+        "description": definition.description,
+        "version": definition.version,
+        "steps": (
+            [
+                {
+                    "name": s.name,
+                    "description": s.description,
+                    "allowed_tools": s.allowed_tools,
+                    "blocked_tools": s.blocked_tools,
+                }
+                for s in definition.steps
+            ]
+            if definition.steps
+            else []
+        ),
+        "triggers": (
+            {name: len(actions) for name, actions in definition.triggers.items()}
+            if definition.triggers
+            else {}
+        ),
+        "settings": definition.settings,
+    }
+
+
+def list_workflows(
+    loader: WorkflowLoader,
+    project_path: str | None = None,
+    workflow_type: str | None = None,
+    global_only: bool = False,
+) -> dict[str, Any]:
+    """
+    List available workflows.
+
+    Lists workflows from both project (.gobby/workflows) and global (~/.gobby/workflows)
+    directories. Project workflows shadow global ones with the same name.
+
+    Args:
+        loader: WorkflowLoader instance
+        project_path: Project directory path. Auto-discovered from cwd if not provided.
+        workflow_type: Filter by type ("step" or "lifecycle")
+        global_only: If True, only show global workflows (ignore project)
+
+    Returns:
+        List of workflows with name, type, description, and source
+    """
+
+    # Auto-discover project path if not provided
+    if not project_path:
+        discovered = get_workflow_project_path()
+        if discovered:
+            project_path = str(discovered)
+
+    search_dirs = list(loader.global_dirs)
+    proj = Path(project_path) if project_path else None
+
+    # Include project workflows unless global_only (project searched first to shadow global)
+    if not global_only and proj:
+        project_dir = proj / ".gobby" / "workflows"
+        if project_dir.exists():
+            search_dirs.insert(0, project_dir)
+
+    workflows = []
+    seen_names = set()
+
+    for search_dir in search_dirs:
+        if not search_dir.exists():
+            continue
+
+        is_project = proj and search_dir == (proj / ".gobby" / "workflows")
+
+        for yaml_path in search_dir.glob("*.yaml"):
+            name = yaml_path.stem
+            if name in seen_names:
+                continue
+
+            try:
+                with open(yaml_path, encoding="utf-8") as f:
+                    data = yaml.safe_load(f)
+
+                if not data:
+                    continue
+
+                wf_type = data.get("type", "step")
+
+                if workflow_type and wf_type != workflow_type:
+                    continue
+
+                workflows.append(
+                    {
+                        "name": name,
+                        "type": wf_type,
+                        "description": data.get("description", ""),
+                        "source": "project" if is_project else "global",
+                    }
+                )
+                seen_names.add(name)
+
+            except Exception as e:
+                logger.debug(
+                    "Skipping invalid workflow file %s: %s",
+                    yaml_path,
+                    e,
+                    exc_info=True,
+                )  # nosec B110
+
+    return {"workflows": workflows, "count": len(workflows)}
+
+
+def get_workflow_status(
+    state_manager: WorkflowStateManager,
+    session_manager: LocalSessionManager,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Get current workflow step and state.
+
+    Args:
+        state_manager: WorkflowStateManager instance
+        session_manager: LocalSessionManager instance
+        session_id: Session reference (accepts #N, N, UUID, or prefix) - required to prevent cross-session bleed
+
+    Returns:
+        Workflow state including step, action counts, artifacts
+    """
+    # Require explicit session_id to prevent cross-session bleed
+    if not session_id:
+        return {
+            "has_workflow": False,
+            "error": "session_id is required. Pass the session ID explicitly to prevent cross-session variable bleed.",
+        }
+
+    # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+    try:
+        resolved_session_id = resolve_session_id(session_manager, session_id)
+    except ValueError as e:
+        return {"has_workflow": False, "error": str(e)}
+
+    state = state_manager.get_state(resolved_session_id)
+    if not state:
+        return {"has_workflow": False, "session_id": resolved_session_id}
+
+    return {
+        "has_workflow": True,
+        "session_id": resolved_session_id,
+        "workflow_name": state.workflow_name,
+        "step": state.step,
+        "step_action_count": state.step_action_count,
+        "total_action_count": state.total_action_count,
+        "reflection_pending": state.reflection_pending,
+        "artifacts": list(state.artifacts.keys()) if state.artifacts else [],
+        "variables": state.variables,
+        "task_progress": (
+            f"{state.current_task_index + 1}/{len(state.task_list)}" if state.task_list else None
+        ),
+        "updated_at": state.updated_at.isoformat() if state.updated_at else None,
+    }