gobby 0.2.5__py3-none-any.whl

gobby/workflows/premature_stop.py

@@ -0,0 +1,164 @@
+"""
+Premature stop handling for workflow engine.
+
+Extracted from engine.py to reduce complexity.
+Handles the case when a session tries to stop before the workflow's
+exit condition is satisfied.
+"""
+
+import logging
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any
+
+from gobby.hooks.events import HookEvent, HookResponse
+
+if TYPE_CHECKING:
+    from .evaluator import ConditionEvaluator
+    from .loader import WorkflowLoader
+    from .state_manager import WorkflowStateManager
+    from .templates import TemplateEngine
+
+logger = logging.getLogger(__name__)
+
+
+async def check_premature_stop(
+    event: HookEvent,
+    context_data: dict[str, Any],
+    state_manager: "WorkflowStateManager",
+    loader: "WorkflowLoader",
+    evaluator: "ConditionEvaluator",
+    template_engine: "TemplateEngine | None",
+) -> HookResponse | None:
+    """
+    Check if an active step workflow should handle a premature stop.
+
+    Called on STOP events to evaluate whether the workflow's exit_condition
+    is met. If not met and workflow has on_premature_stop defined, returns
+    an appropriate response.
+
+    Args:
+        event: The STOP hook event
+        context_data: Shared context data including session variables
+        state_manager: Workflow state manager
+        loader: Workflow definition loader
+        evaluator: Condition evaluator
+        template_engine: Template engine for rendering messages
+
+    Returns:
+        HookResponse if premature stop detected, None otherwise
+    """
+    session_id = event.metadata.get("_platform_session_id")
+    if not session_id:
+        return None
+
+    # Check if there's an active step workflow
+    state = state_manager.get_state(session_id)
+    if not state:
+        return None
+
+    # Skip lifecycle-only states
+    if state.workflow_name == "__lifecycle__":
+        return None
+
+    # Load the workflow definition
+    project_path = Path(event.cwd) if event.cwd else None
+    workflow = loader.load_workflow(state.workflow_name, project_path=project_path)
+    if not workflow:
+        logger.warning(f"Workflow '{state.workflow_name}' not found for premature stop check")
+        return None
+
+    # Check if workflow has exit_condition and on_premature_stop
+    if not workflow.exit_condition:
+        return None
+
+    # Build evaluation context
+    # Use SimpleNamespace for variables so dot notation works (variables.session_task)
+    eval_context: dict[str, Any] = {
+        "workflow_state": state,
+        "state": state,
+        "variables": SimpleNamespace(**state.variables),
+        "current_step": state.step,
+    }
+    # Add session variables to context
+    eval_context.update(context_data)
+
+    # Evaluate the exit condition
+    exit_condition_met = evaluator.evaluate(workflow.exit_condition, eval_context)
+
+    if exit_condition_met:
+        logger.debug(f"Workflow '{workflow.name}' exit_condition met, allowing stop")
+        return None
+
+    # Exit condition not met - check for premature stop handler
+    if not workflow.on_premature_stop:
+        logger.debug(
+            f"Workflow '{workflow.name}' exit_condition not met but no on_premature_stop defined"
+        )
+        return None
+
+    # Failsafe: check if we've exceeded max stop attempts
+    # Counter is stored in variables and resets on BEFORE_AGENT (user prompt)
+    stop_count = state.variables.get("_premature_stop_count", 0) + 1
+    max_attempts = state.variables.get("premature_stop_max_attempts", 3)
+
+    # Update and persist the counter
+    state.variables["_premature_stop_count"] = stop_count
+    state_manager.save_state(state)
+
+    if max_attempts > 0 and stop_count >= max_attempts:
+        logger.warning(
+            f"Premature stop failsafe triggered for workflow '{workflow.name}': "
+            f"stop_count={stop_count} >= max_attempts={max_attempts}"
+        )
+        return HookResponse(
+            decision="allow",
+            context=(
+                f"⚠️ **Failsafe Exit**: Allowing stop after {stop_count} blocked attempts. "
+                f"Task may be incomplete."
+            ),
+        )
+
+    # Handle premature stop based on action type
+    handler = workflow.on_premature_stop
+
+    # Render the message through template engine (supports Jinja2 variables)
+    rendered_message = handler.message
+    if template_engine and handler.message:
+        render_context = {
+            "variables": state.variables,
+            "state": state,
+            "workflow": workflow,
+        }
+        try:
+            rendered_message = template_engine.render(handler.message, render_context)
+        except Exception as e:
+            logger.warning(f"Failed to render on_premature_stop message: {e}")
+            # Fall back to unrendered message
+
+    logger.info(
+        f"Premature stop detected for workflow '{workflow.name}': "
+        f"action={handler.action}, message={rendered_message[:100] if rendered_message else None}..., "
+        f"attempt {stop_count}/{max_attempts}"
+    )
+
+    if handler.action == "block":
+        return HookResponse(
+            decision="block",
+            reason=rendered_message,
+        )
+    elif handler.action == "warn":
+        return HookResponse(
+            decision="allow",
+            context=f"⚠️ **Warning**: {rendered_message}",
+        )
+    else:  # guide_continuation (default)
+        return HookResponse(
+            decision="block",
+            reason=rendered_message,
+            context=(
+                f"📋 **Task Incomplete**\n\n"
+                f"{rendered_message}\n\n"
+                f"The workflow exit condition `{workflow.exit_condition}` is not yet satisfied."
+            ),
+        )

gobby/workflows/session_actions.py

@@ -0,0 +1,139 @@
+"""Session lifecycle workflow actions.
+
+Extracted from actions.py as part of strangler fig decomposition.
+These functions handle session status updates, mode switching, and session chaining.
+"""
+
+import logging
+import shlex
+import subprocess  # nosec B404 - subprocess needed for session spawning
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def start_new_session(
+    session_manager: Any,
+    session_id: str,
+    command: str | None = None,
+    args: list[str] | str | None = None,
+    prompt: str | None = None,
+    cwd: str | None = None,
+) -> dict[str, Any]:
+    """Start a new CLI session (chaining).
+
+    Args:
+        session_manager: The session manager instance
+        session_id: Current session ID
+        command: CLI command to run (default: auto-detect from source)
+        args: List of arguments or string to split
+        prompt: Initial prompt/context to inject
+        cwd: Working directory (default: current session's cwd)
+
+    Returns:
+        Dict with started_new_session, pid, and command, or error
+    """
+    session = session_manager.get(session_id)
+    if not session:
+        return {"error": "Session not found"}
+
+    # Determine command
+    if not command:
+        source = getattr(session, "source", "claude")
+        if source == "claude":
+            command = "claude"
+        elif source == "antigravity":
+            command = "claude"  # Antigravity uses Claude Code
+        elif source == "gemini":
+            command = "gemini"
+        else:
+            command = "claude"  # Default fallthrough
+
+    # Parse args
+    cmd_args: list[str] = []
+    if args:
+        if isinstance(args, str):
+            cmd_args = shlex.split(args)
+        else:
+            cmd_args = list(args)
+
+    # Determine working directory
+    if not cwd:
+        cwd = getattr(session, "project_path", None) or "."
+
+    logger.info(f"Starting new session: {command} {cmd_args} in {cwd}")
+
+    try:
+        full_cmd = [command] + cmd_args
+
+        # Inject prompt via -p flag for Claude/Gemini if supported
+        if prompt and command in ["claude", "gemini"]:
+            full_cmd.extend(["-p", prompt])
+
+        proc = subprocess.Popen(  # nosec B603 - cmd built from config, no shell
+            full_cmd,
+            cwd=cwd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,  # Detach
+        )
+
+        logger.info(f"Spawned process {proc.pid}")
+        return {"started_new_session": True, "pid": proc.pid, "command": str(full_cmd)}
+
+    except Exception as e:
+        logger.error(f"Failed to start new session: {e}", exc_info=True)
+        return {"error": str(e)}
+
+
+def mark_session_status(
+    session_manager: Any,
+    session_id: str,
+    status: str | None = None,
+    target: str = "current_session",
+) -> dict[str, Any]:
+    """Mark a session status (current or parent).
+
+    Args:
+        session_manager: The session manager instance
+        session_id: Current session ID
+        status: New status to set
+        target: "current_session" or "parent_session"
+
+    Returns:
+        Dict with status_updated, session_id, and status, or error
+    """
+    if not status:
+        return {"error": "Missing status"}
+
+    target_session_id = session_id
+    if target == "parent_session":
+        current_session = session_manager.get(session_id)
+        if current_session and current_session.parent_session_id:
+            target_session_id = current_session.parent_session_id
+        else:
+            return {"error": "No parent session linked"}
+
+    session_manager.update_status(target_session_id, status)
+    return {"status_updated": True, "session_id": target_session_id, "status": status}
+
+
+def switch_mode(mode: str | None = None) -> dict[str, Any]:
+    """Signal the agent to switch modes (e.g., PLAN, ACT).
+
+    Args:
+        mode: The mode to switch to
+
+    Returns:
+        Dict with inject_context and mode_switch, or error
+    """
+    if not mode:
+        return {"error": "Missing mode"}
+
+    message = (
+        f"SYSTEM: SWITCH MODE TO {mode.upper()}\n"
+        f"You are now in {mode.upper()} mode. Adjust your behavior accordingly."
+    )
+
+    return {"inject_context": message, "mode_switch": mode}

gobby/workflows/state_actions.py

@@ -0,0 +1,123 @@
+"""Workflow state management actions.
+
+Extracted from actions.py as part of strangler fig decomposition.
+These functions handle workflow state persistence and variable management.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def load_workflow_state(db: Any, session_id: str, state: Any) -> dict[str, Any]:
+    """Load workflow state from DB into the provided state object.
+
+    Args:
+        db: Database instance
+        session_id: Session ID to load state for
+        state: WorkflowState object to update
+
+    Returns:
+        Dict with state_loaded boolean
+    """
+    from gobby.workflows.state_manager import WorkflowStateManager
+
+    state_manager = WorkflowStateManager(db)
+    loaded_state = state_manager.get_state(session_id)
+
+    if loaded_state:
+        # Copy attributes from loaded state to existing state object
+        for field in loaded_state.model_fields:
+            val = getattr(loaded_state, field)
+            setattr(state, field, val)
+        return {"state_loaded": True}
+
+    return {"state_loaded": False}
+
+
+def save_workflow_state(db: Any, state: Any) -> dict[str, Any]:
+    """Save workflow state to DB.
+
+    Args:
+        db: Database instance
+        state: WorkflowState object to save
+
+    Returns:
+        Dict with state_saved boolean
+    """
+    from gobby.workflows.state_manager import WorkflowStateManager
+
+    state_manager = WorkflowStateManager(db)
+    state_manager.save_state(state)
+    return {"state_saved": True}
+
+
+def set_variable(state: Any, name: str | None, value: Any) -> dict[str, Any] | None:
+    """Set a workflow variable.
+
+    Args:
+        state: WorkflowState object
+        name: Variable name
+        value: Variable value
+
+    Returns:
+        Dict with variable_set and value, or None if no name
+    """
+    if not name:
+        return None
+
+    if not state.variables:
+        state.variables = {}
+
+    state.variables[name] = value
+    return {"variable_set": name, "value": value}
+
+
+def increment_variable(
+    state: Any, name: str | None, amount: int | float = 1
+) -> dict[str, Any] | None:
+    """Increment a numeric workflow variable.
+
+    Args:
+        state: WorkflowState object
+        name: Variable name
+        amount: Amount to increment by (default: 1)
+
+    Returns:
+        Dict with variable_incremented and value, or None if no name
+    """
+    if not name:
+        return None
+
+    if not state.variables:
+        state.variables = {}
+
+    current = state.variables.get(name, 0)
+    if not isinstance(current, (int, float)):
+        logger.error(
+            f"increment_variable: Variable '{name}' is not numeric, got {type(current).__name__}: {current}"
+        )
+        raise TypeError(
+            f"Cannot increment non-numeric variable '{name}': "
+            f"expected int or float, got {type(current).__name__} with value {current!r}"
+        )
+
+    new_value = current + amount
+    state.variables[name] = new_value
+    return {"variable_incremented": name, "value": new_value}
+
+
+def mark_loop_complete(state: Any) -> dict[str, Any]:
+    """Mark the autonomous loop as complete.
+
+    Args:
+        state: WorkflowState object
+
+    Returns:
+        Dict with loop_marked_complete boolean
+    """
+    if not state.variables:
+        state.variables = {}
+    state.variables["stop_reason"] = "completed"
+    return {"loop_marked_complete": True}

gobby/workflows/state_manager.py

@@ -0,0 +1,104 @@
+import json
+import logging
+from datetime import UTC, datetime
+
+from gobby.storage.database import DatabaseProtocol
+
+from .definitions import WorkflowState
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowStateManager:
+    """
+    Manages persistence of WorkflowState and Handoffs.
+    """
+
+    def __init__(self, db: DatabaseProtocol):
+        self.db = db
+
+    def get_state(self, session_id: str) -> WorkflowState | None:
+        row = self.db.fetchone("SELECT * FROM workflow_states WHERE session_id = ?", (session_id,))
+        if not row:
+            return None
+
+        try:
+            return WorkflowState(
+                session_id=row["session_id"],
+                workflow_name=row["workflow_name"],
+                step=row["step"],
+                step_entered_at=(
+                    datetime.fromisoformat(row["step_entered_at"])
+                    if row["step_entered_at"]
+                    else datetime.now(UTC)
+                ),
+                step_action_count=row["step_action_count"],
+                total_action_count=row["total_action_count"],
+                artifacts=json.loads(row["artifacts"]) if row["artifacts"] else {},
+                observations=json.loads(row["observations"]) if row["observations"] else [],
+                reflection_pending=bool(row["reflection_pending"]),
+                context_injected=bool(row["context_injected"]),
+                variables=json.loads(row["variables"]) if row["variables"] else {},
+                task_list=json.loads(row["task_list"]) if row["task_list"] else None,
+                current_task_index=row["current_task_index"],
+                files_modified_this_task=row["files_modified_this_task"],
+                updated_at=(
+                    datetime.fromisoformat(row["updated_at"])
+                    if row["updated_at"]
+                    else datetime.now(UTC)
+                ),
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to parse workflow state for session {session_id}: {e}", exc_info=True
+            )
+            return None
+
+    def save_state(self, state: WorkflowState) -> None:
+        """Upsert workflow state."""
+        self.db.execute(
+            """
+            INSERT INTO workflow_states (
+                session_id, workflow_name, step, step_entered_at,
+                step_action_count, total_action_count, artifacts,
+                observations, reflection_pending, context_injected, variables,
+                task_list, current_task_index, files_modified_this_task,
+                updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(session_id) DO UPDATE SET
+                workflow_name = excluded.workflow_name,
+                step = excluded.step,
+                step_entered_at = excluded.step_entered_at,
+                step_action_count = excluded.step_action_count,
+                total_action_count = excluded.total_action_count,
+                artifacts = excluded.artifacts,
+                observations = excluded.observations,
+                reflection_pending = excluded.reflection_pending,
+                context_injected = excluded.context_injected,
+                variables = excluded.variables,
+                task_list = excluded.task_list,
+                current_task_index = excluded.current_task_index,
+                files_modified_this_task = excluded.files_modified_this_task,
+                updated_at = excluded.updated_at
+            """,
+            (
+                state.session_id,
+                state.workflow_name,
+                state.step,
+                state.step_entered_at.isoformat(),
+                state.step_action_count,
+                state.total_action_count,
+                json.dumps(state.artifacts),
+                json.dumps(state.observations),
+                1 if state.reflection_pending else 0,
+                1 if state.context_injected else 0,
+                json.dumps(state.variables),
+                json.dumps(state.task_list) if state.task_list else None,
+                state.current_task_index,
+                state.files_modified_this_task,
+                datetime.now(UTC).isoformat(),
+            ),
+        )
+
+    def delete_state(self, session_id: str) -> None:
+        self.db.execute("DELETE FROM workflow_states WHERE session_id = ?", (session_id,))

gobby/workflows/stop_signal_actions.py

@@ -0,0 +1,163 @@
+"""Stop signal workflow actions for autonomous execution.
+
+These actions enable workflows to check for and respond to stop signals
+sent by external systems (HTTP, WebSocket, CLI, MCP).
+"""
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gobby.autonomous.stop_registry import StopRegistry
+    from gobby.workflows.definitions import WorkflowState
+
+logger = logging.getLogger(__name__)
+
+
+def check_stop_signal(
+    stop_registry: "StopRegistry | None",
+    session_id: str,
+    state: "WorkflowState",
+    acknowledge: bool = False,
+) -> dict[str, Any]:
+    """Check if a stop signal has been sent for this session.
+
+    This action can be used in workflow transitions or as a periodic check
+    during autonomous execution.
+
+    Args:
+        stop_registry: StopRegistry instance for checking signals
+        session_id: The session to check
+        state: Current workflow state (updated with signal info)
+        acknowledge: If True, acknowledge the signal (session will stop)
+
+    Returns:
+        Dict with:
+        - has_signal: True if there's a pending stop signal
+        - signal: Signal details if present (source, reason, requested_at)
+        - acknowledged: True if the signal was acknowledged
+        - inject_context: Optional message about the stop signal
+    """
+    if not stop_registry:
+        logger.warning("No stop_registry available, cannot check stop signal")
+        return {"has_signal": False}
+
+    signal = stop_registry.get_signal(session_id)
+
+    if not signal or not signal.is_pending:
+        return {"has_signal": False}
+
+    # Store signal info in workflow variables
+    state.variables["_stop_signal_pending"] = True
+    state.variables["_stop_signal_source"] = signal.source
+    state.variables["_stop_signal_reason"] = signal.reason
+
+    result: dict[str, Any] = {
+        "has_signal": True,
+        "signal": {
+            "source": signal.source,
+            "reason": signal.reason,
+            "requested_at": signal.requested_at.isoformat(),
+        },
+    }
+
+    if acknowledge:
+        stop_registry.acknowledge(session_id)
+        result["acknowledged"] = True
+        result["inject_context"] = (
+            f"🛑 **Stop Signal Received**\n\n"
+            f"Source: {signal.source}\n"
+            f"Reason: {signal.reason or 'No reason provided'}\n\n"
+            f"The session will stop gracefully."
+        )
+        logger.info(f"Stop signal acknowledged for session {session_id}")
+    else:
+        result["acknowledged"] = False
+        result["inject_context"] = (
+            f"⚠️ **Stop Signal Pending**\n\n"
+            f"A stop signal was received from {signal.source}.\n"
+            f"Reason: {signal.reason or 'No reason provided'}\n\n"
+            f"Complete current work and prepare to stop."
+        )
+
+    return result
+
+
+def has_stop_signal(stop_registry: "StopRegistry | None", session_id: str) -> bool:
+    """Condition function to check if a stop signal is pending.
+
+    Use this in workflow transition conditions:
+
+    ```yaml
+    transitions:
+      - to: stopping
+        when: "has_stop_signal(session.id)"
+    ```
+
+    Args:
+        stop_registry: StopRegistry instance
+        session_id: The session to check
+
+    Returns:
+        True if there's a pending stop signal
+    """
+    if not stop_registry:
+        return False
+    return stop_registry.has_pending_signal(session_id)
+
+
+def request_stop(
+    stop_registry: "StopRegistry | None",
+    session_id: str,
+    source: str = "workflow",
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """Request a session to stop (can be used by stuck detection).
+
+    Args:
+        stop_registry: StopRegistry instance
+        session_id: The session to signal
+        source: Source of the request (workflow, stuck_detection, etc.)
+        reason: Optional reason for the stop request
+
+    Returns:
+        Dict with success status and signal details
+    """
+    if not stop_registry:
+        logger.warning("No stop_registry available, cannot request stop")
+        return {"success": False, "error": "No stop registry available"}
+
+    signal = stop_registry.signal_stop(session_id, source, reason)
+
+    return {
+        "success": True,
+        "signal": {
+            "session_id": signal.session_id,
+            "source": signal.source,
+            "reason": signal.reason,
+            "requested_at": signal.requested_at.isoformat(),
+        },
+    }
+
+
+def clear_stop_signal(
+    stop_registry: "StopRegistry | None",
+    session_id: str,
+) -> dict[str, Any]:
+    """Clear any stop signal for a session.
+
+    Use this after a session has fully stopped or when the signal
+    should be cancelled.
+
+    Args:
+        stop_registry: StopRegistry instance
+        session_id: The session to clear
+
+    Returns:
+        Dict with success status
+    """
+    if not stop_registry:
+        return {"success": False, "error": "No stop registry available"}
+
+    cleared = stop_registry.clear(session_id)
+    return {"success": True, "cleared": cleared}