ralphx 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

ralphx/api/routes/items.py

@@ -139,6 +139,8 @@ async def list_items(
     source_step_id: Optional[int] = Query(None, description="Filter by source step"),
     limit: int = Query(50, ge=1, le=1000, description="Items per page"),
     offset: int = Query(0, ge=0, description="Offset for pagination"),
+    sort_by: str = Query("created_at", description="Column to sort by"),
+    sort_order: str = Query("desc", description="Sort order: asc or desc"),
 ):
     """List work items with optional filtering."""
     manager, project, project_db = get_project(slug)
@@ -151,6 +153,8 @@ async def list_items(
         source_step_id=source_step_id,
         limit=limit,
         offset=offset,
+        sort_by=sort_by,
+        sort_order=sort_order,
     )
 
     # Convert to response models

ralphx/api/routes/loops.py

@@ -17,6 +17,7 @@ from ralphx.core.project_db import ProjectDatabase
 from ralphx.models.loop import LoopConfig, LoopType, ModeSelectionStrategy, ItemTypes
 from ralphx.models.run import Run, RunStatus
 from ralphx.core.logger import loop_log
+from ralphx.core.checkpoint import kill_orphan_process
 
 router = APIRouter()
 
@@ -54,6 +55,9 @@ def detect_source_cycle(
 # Store for running loops
 _running_loops: dict[str, LoopExecutor] = {}
 
+# Prevent concurrent stop attempts
+_stopping_loops: set[str] = set()
+
 # Security: Validate loop names to prevent path traversal
 LOOP_NAME_PATTERN = re.compile(r'^[a-zA-Z0-9_-]+$')
 
@@ -428,34 +432,110 @@ async def start_loop(
 
 @router.post("/{slug}/loops/{loop_name}/stop")
 async def stop_loop(slug: str, loop_name: str):
-    """Stop a running loop."""
-    # Validate project exists first
-    get_managers(slug)
+    """Stop a running loop.
+
+    Attempts to stop via executor if in memory, otherwise falls back
+    to killing via PID from database (for orphaned processes after
+    server restart/hot-reload).
+    """
+    manager, project, project_db = get_managers(slug)
 
     key = f"{slug}:{loop_name}"
-    executor = _running_loops.get(key)
 
-    if not executor:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Loop {loop_name} is not running",
-        )
+    # Prevent concurrent stop attempts
+    if key in _stopping_loops:
+        return {"message": f"Stop already in progress for {loop_name}"}
 
-    await executor.stop()
+    _stopping_loops.add(key)
+    try:
+        # Try 1: Stop via executor (normal case)
+        executor = _running_loops.get(key)
+        if executor:
+            await executor.stop()
+            return {
+                "message": f"Stop signal sent to {loop_name}",
+                "method": "executor",
+            }
+
+        # Try 2: Kill via PID (orphan case after server restart)
+        runs = project_db.list_runs(loop_name=loop_name, status=["running", "paused"])
+        if not runs:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Loop {loop_name} is not running",
+            )
 
-    return {"message": f"Stop signal sent to {loop_name}"}
+        # Get most recent running run
+        run = runs[0]
+        pid = run.get("executor_pid")
+
+        if not pid:
+            # No PID recorded - can't kill, just mark as aborted
+            project_db.update_run(
+                run["id"],
+                status="aborted",
+                completed_at=datetime.utcnow().isoformat(),
+                error_message="Stopped by user (no PID available for orphan process)",
+            )
+            return {
+                "message": f"Marked {loop_name} as aborted (no PID available)",
+                "method": "database_only",
+                "warning": "Process may still be running",
+            }
+
+        # Kill the orphan process
+        success, reason = await kill_orphan_process(pid)
+
+        # Update database regardless of kill result
+        if success:
+            error_msg = f"Killed orphan process (PID {pid}) after server restart"
+            if reason == "already_dead":
+                error_msg = f"Orphan process (PID {pid}) already terminated"
+        else:
+            error_msg = f"Could not kill orphan process (PID {pid}): {reason}"
+
+        project_db.update_run(
+            run["id"],
+            status="aborted",
+            completed_at=datetime.utcnow().isoformat(),
+            error_message=error_msg,
+        )
+
+        if success:
+            return {
+                "message": f"Stopped orphan process for {loop_name}",
+                "method": "pid_kill",
+                "pid": pid,
+                "detail": reason,  # "killed" or "already_dead"
+            }
+        else:
+            return {
+                "message": f"Could not kill process {pid}, marked as aborted",
+                "method": "pid_kill_failed",
+                "pid": pid,
+                "reason": reason,
+                "warning": "Process may not have been our process (PID reuse)" if reason == "not_our_process" else None,
+            }
+    finally:
+        _stopping_loops.discard(key)
 
 
 @router.post("/{slug}/loops/{loop_name}/pause")
 async def pause_loop(slug: str, loop_name: str):
     """Pause a running loop."""
-    # Validate project exists first
-    get_managers(slug)
+    manager, project, project_db = get_managers(slug)
 
     key = f"{slug}:{loop_name}"
     executor = _running_loops.get(key)
 
     if not executor:
+        # Check if there's an orphan process
+        runs = project_db.list_runs(loop_name=loop_name, status=["running", "paused"])
+        if runs:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Loop {loop_name} is running as orphan process (server restarted). Use stop to terminate it.",
+            )
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail=f"Loop {loop_name} is not running",
@@ -469,13 +549,19 @@ async def pause_loop(slug: str, loop_name: str):
 @router.post("/{slug}/loops/{loop_name}/resume")
 async def resume_loop(slug: str, loop_name: str):
     """Resume a paused loop."""
-    # Validate project exists first
-    get_managers(slug)
+    manager, project, project_db = get_managers(slug)
 
     key = f"{slug}:{loop_name}"
     executor = _running_loops.get(key)
 
     if not executor:
+        # Check if there's an orphan process
+        runs = project_db.list_runs(loop_name=loop_name, status=["running", "paused"])
+        if runs:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Loop {loop_name} is orphaned (server restarted). Use stop to terminate, then start again.",
+            )
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail=f"Loop {loop_name} is not running",

ralphx/api/routes/planning.py

@@ -459,7 +459,7 @@ async def stream_planning_response(slug: str, workflow_id: str):
             async for event in service.stream_response(
                 messages,
                 model=model,
-                tools=allowed_tools if allowed_tools else None,
+                tools=allowed_tools,
                 timeout=timeout,
             ):
                 if event.type == AdapterEvent.TEXT:

ralphx/api/routes/stream.py

@@ -8,7 +8,7 @@ from fastapi import APIRouter, HTTPException, Query, status
 from fastapi.responses import StreamingResponse
 
 from ralphx.core.project import ProjectManager
-from ralphx.core.session import SessionEventType, SessionManager, SessionTailer
+from ralphx.core.session import SessionManager
 from ralphx.models.run import RunStatus
 
 router = APIRouter()
@@ -179,13 +179,18 @@ async def _tail_session(
     run_id: Optional[str] = None,
     iteration: Optional[int] = None,
 ) -> AsyncGenerator[str, None]:
-    """Tail a specific session file, storing events to DB for history.
+    """Stream session events from DB via polling.
+
+    Events are persisted to the session_events table by the executor's
+    persist_event callback. This function polls that table and yields
+    SSE events as they appear — same pattern as planning.py's
+    stream_iteration_progress().
 
     Args:
         session_manager: Session manager instance.
         session_id: Session UUID.
-        project_path: Project directory path.
-        project_db: ProjectDatabase for storing events.
+        project_path: Project directory path (used for optional file metadata).
+        project_db: ProjectDatabase for reading events.
         from_beginning: Start from file beginning.
         run_id: Run ID for this session.
         iteration: Iteration number for this session.
@@ -195,16 +200,12 @@ async def _tail_session(
     """
     from pathlib import Path
 
+    # Session file is optional metadata — streaming uses DB polling, not file tailing
     session_file = session_manager.find_session_file(
         session_id=session_id,
         project_path=Path(project_path),
     )
-
-    if not session_file:
-        yield await format_sse("error", {
-            "message": f"Session file not found: {session_id}"
-        })
-        return
+    # Don't abort if file not found — we stream from DB
 
     # Get session info if not provided
     if run_id is None or iteration is None:
@@ -250,6 +251,16 @@ async def _tail_session(
                 "message": db_event.get("error_message"),
                 **event_meta,
             })
+        elif event_type == "thinking":
+            yield await format_sse("thinking", {
+                "content": db_event.get("content", ""),
+                **event_meta,
+            })
+        elif event_type == "usage":
+            yield await format_sse("usage", {
+                "data": db_event.get("raw_data"),
+                **event_meta,
+            })
         elif event_type == "init":
             yield await format_sse("init", {
                 "data": db_event.get("raw_data"),
@@ -261,64 +272,95 @@ async def _tail_session(
 
     yield await format_sse("session_start", {
         "session_id": session_id,
-        "file": str(session_file),
+        "file": str(session_file) if session_file else None,
         "history_events": len(existing_events),
         "run_id": run_id,
         "iteration": iteration,
     })
 
-    # Now tail the file for new events, starting from where DB left off
-    # If we have history, start from end of file to avoid duplicates
-    tailer = SessionTailer(
-        session_path=session_file,
-        from_beginning=from_beginning and len(existing_events) == 0,
-    )
-
+    # Poll DB for new events (same pattern as planning.py stream_iteration_progress)
+    # This replaces the SessionTailer file-tailing approach to unify streaming
     try:
-        async for event in tailer.tail():
-            # Skip UNKNOWN events (like queue-operation, user messages)
-            if event.type == SessionEventType.UNKNOWN:
-                continue
-
-            # Stream events to client (persistence handled by executor)
-            if event.type == SessionEventType.TEXT:
-                yield await format_sse("text", {
-                    "content": event.text,
-                    **event_meta,
-                })
-
-            elif event.type == SessionEventType.TOOL_CALL:
-                yield await format_sse("tool_call", {
-                    "name": event.tool_name,
-                    "input": event.tool_input,
-                    **event_meta,
-                })
-
-            elif event.type == SessionEventType.TOOL_RESULT:
-                yield await format_sse("tool_result", {
-                    "name": event.tool_name,
-                    "result": event.tool_result[:1000] if event.tool_result else None,
-                    **event_meta,
-                })
-
-            elif event.type == SessionEventType.ERROR:
-                yield await format_sse("error", {
-                    "message": event.error_message,
-                    **event_meta,
-                })
-
-            elif event.type == SessionEventType.COMPLETE:
-                yield await format_sse("complete", event_meta)
+        while True:
+            # Fetch new events since last seen
+            new_events = project_db.get_session_events(session_id, after_id=last_db_event_id)
+
+            for db_event in new_events:
+                last_db_event_id = db_event.get("id", 0)
+                event_type = db_event.get("event_type", "unknown")
+
+                if event_type == "text":
+                    yield await format_sse("text", {
+                        "content": db_event.get("content", ""),
+                        **event_meta,
+                    })
+                elif event_type == "tool_call":
+                    yield await format_sse("tool_call", {
+                        "name": db_event.get("tool_name"),
+                        "input": db_event.get("tool_input"),
+                        **event_meta,
+                    })
+                elif event_type == "tool_result":
+                    yield await format_sse("tool_result", {
+                        "name": db_event.get("tool_name"),
+                        "result": db_event.get("tool_result"),
+                        **event_meta,
+                    })
+                elif event_type == "error":
+                    yield await format_sse("error", {
+                        "message": db_event.get("error_message"),
+                        **event_meta,
+                    })
+                elif event_type == "thinking":
+                    yield await format_sse("thinking", {
+                        "content": db_event.get("content", ""),
+                        **event_meta,
+                    })
+                elif event_type == "usage":
+                    yield await format_sse("usage", {
+                        "data": db_event.get("raw_data"),
+                        **event_meta,
+                    })
+                elif event_type == "complete":
+                    yield await format_sse("complete", event_meta)
+                    return  # Session complete
+                elif event_type == "init":
+                    yield await format_sse("init", {
+                        "data": db_event.get("raw_data"),
+                        **event_meta,
+                    })
+
+            # Check if session is done (status updated by executor)
+            session_info = project_db.get_session(session_id)
+            if session_info and session_info.get("status") in ("completed", "error"):
+                # Drain any remaining events
+                final_events = project_db.get_session_events(session_id, after_id=last_db_event_id)
+                for db_event in final_events:
+                    last_db_event_id = db_event.get("id", 0)
+                    event_type = db_event.get("event_type", "unknown")
+                    if event_type == "text":
+                        yield await format_sse("text", {"content": db_event.get("content", ""), **event_meta})
+                    elif event_type == "tool_call":
+                        yield await format_sse("tool_call", {"name": db_event.get("tool_name"), "input": db_event.get("tool_input"), **event_meta})
+                    elif event_type == "tool_result":
+                        yield await format_sse("tool_result", {"name": db_event.get("tool_name"), "result": db_event.get("tool_result"), **event_meta})
+                    elif event_type == "error":
+                        yield await format_sse("error", {"message": db_event.get("error_message"), **event_meta})
+                    elif event_type == "complete":
+                        yield await format_sse("complete", event_meta)
+                    elif event_type == "thinking":
+                        yield await format_sse("thinking", {"content": db_event.get("content", ""), **event_meta})
+                    elif event_type == "usage":
+                        yield await format_sse("usage", {"data": db_event.get("raw_data"), **event_meta})
+                    elif event_type == "init":
+                        yield await format_sse("init", {"data": db_event.get("raw_data"), **event_meta})
                 break
 
-            elif event.type == SessionEventType.INIT:
-                yield await format_sse("init", {
-                    "data": event.raw_data,
-                    **event_meta,
-                })
+            # Heartbeat + poll interval (same as planning.py)
+            yield await format_sse("heartbeat", {})
+            await asyncio.sleep(0.5)
 
     except asyncio.CancelledError:
-        tailer.stop()
         yield await format_sse("disconnected", {})
 
 
@@ -452,6 +494,7 @@ async def list_sessions(
             "status": s.status,
             "started_at": s.started_at.isoformat() if s.started_at else None,
             "duration_seconds": s.duration_seconds,
+            "account_email": s.account_email,
         }
         for s in sessions
     ]
@@ -484,6 +527,7 @@ async def get_session(
         "started_at": session.started_at.isoformat() if session.started_at else None,
         "duration_seconds": session.duration_seconds,
         "items_added": session.items_added,
+        "account_email": session.account_email,
     }
 
 
@@ -527,7 +571,7 @@ async def get_session_events(
 async def get_grouped_events(
     slug: str,
     loop_name: str,
-    limit_runs: int = Query(5, ge=1, le=50, description="Max runs to return"),
+    limit_runs: int = Query(20, ge=1, le=50, description="Max runs to return"),
     limit_sessions: int = Query(20, ge=1, le=100, description="Max sessions per run"),
     limit_events: int = Query(200, ge=1, le=1000, description="Max events per session"),
 ):
@@ -579,6 +623,7 @@ async def get_grouped_events(
                 "mode": session.mode,
                 "status": session.status,
                 "is_live": is_live,
+                "account_email": session.account_email,
                 "events": events,
                 "events_truncated": len(events) >= limit_events,
             }

ralphx/api/routes/templates.py

@@ -42,6 +42,7 @@ class TemplateListItem(BaseModel):
     description: str
     type: str
     category: str
+    default_tools: Optional[list[str]] = None
 
 
 class TemplateDetail(BaseModel):

ralphx/api/routes/workflows.py

@@ -28,7 +28,7 @@ PROCESSING_TYPES = {
         "config": {
             "loopType": "generator",
             "template": "extractgen_requirements",
-            "allowedTools": ["WebSearch", "WebFetch"],
+            "allowedTools": ["Read", "Glob", "Grep"],
             "model": "opus",
             "timeout": 600,
             "max_iterations": 100,
@@ -41,7 +41,7 @@ PROCESSING_TYPES = {
         "config": {
             "loopType": "generator",
             "template": "webgen_requirements",
-            "allowedTools": ["WebSearch", "WebFetch"],
+            "allowedTools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
             "model": "opus",
             "timeout": 900,
             "max_iterations": 15,

ralphx/core/checkpoint.py

@@ -7,9 +7,12 @@ Implements:
 - Recovery flow for resuming interrupted runs
 """
 
+import asyncio
 import fcntl
 import json
 import os
+import signal
+import subprocess
 import sys
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -197,6 +200,121 @@ def is_pid_running(pid: int) -> bool:
             return False
 
 
+def is_our_claude_process(pid: int) -> bool:
+    """Verify PID is actually our Claude process, not a reused PID.
+
+    This prevents PID reuse attacks where we might accidentally kill
+    an unrelated process that was assigned the same PID after our
+    Claude process terminated.
+
+    Returns False if:
+    - Process doesn't exist
+    - Can't read cmdline (permissions, etc.)
+    - Process is not a Claude CLI or Python/RalphX process
+
+    Note: There is still a small TOCTOU (time-of-check-to-time-of-use) race
+    between this check and the actual kill. This is an accepted risk that
+    is mitigated by:
+    1. The check significantly reduces the window vs. no check at all
+    2. We only use PIDs from our own database, not user input
+    3. The target must match expected process names
+    """
+    if pid <= 0:
+        return False
+
+    if sys.platform == "win32":
+        # Windows: Use tasklist to verify process name
+        try:
+            result = subprocess.run(
+                ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
+                capture_output=True, text=True, timeout=5
+            )
+            output = result.stdout.lower()
+            # Check for claude or python (for multiprocessing spawn)
+            return "claude" in output or "python" in output
+        except Exception:
+            return False
+
+    elif sys.platform == "darwin":
+        # macOS: Use ps command (no /proc filesystem)
+        try:
+            result = subprocess.run(
+                ["ps", "-p", str(pid), "-o", "command="],
+                capture_output=True, text=True, timeout=5
+            )
+            output = result.stdout.lower()
+            return "claude" in output or "python" in output or "ralphx" in output
+        except Exception:
+            return False
+
+    else:
+        # Linux: Check /proc/{pid}/cmdline (most reliable)
+        try:
+            with open(f"/proc/{pid}/cmdline", "rb") as f:
+                cmdline = f.read().decode("utf-8", errors="replace").lower()
+                # cmdline uses null bytes as separators
+                return "claude" in cmdline or "python" in cmdline or "ralphx" in cmdline
+        except (OSError, IOError):
+            return False
+
+
+async def kill_orphan_process(pid: int, timeout: float = 5.0) -> tuple[bool, str]:
+    """Kill an orphan Claude/RalphX process by PID.
+
+    Returns tuple of (success, reason):
+    - (True, "killed") - Process was terminated by us
+    - (True, "already_dead") - Process was already dead
+    - (False, "not_our_process") - PID exists but isn't our process
+    - (False, "permission_denied") - Can't kill (permissions)
+    - (False, "unknown_error") - Other failure
+
+    Cross-platform notes:
+    - Linux/macOS: SIGTERM for graceful, SIGKILL for force
+    - Windows: os.kill() with any signal calls TerminateProcess (immediate)
+    """
+    # Check if process is already dead
+    if not is_pid_running(pid):
+        return (True, "already_dead")
+
+    # Validate this is our process
+    if not is_our_claude_process(pid):
+        return (False, "not_our_process")
+
+    try:
+        if sys.platform == "win32":
+            # Windows: TerminateProcess is immediate, no graceful option
+            os.kill(pid, signal.SIGTERM)  # Actually calls TerminateProcess
+            await asyncio.sleep(0.1)
+            if not is_pid_running(pid):
+                return (True, "killed")
+            return (False, "unknown_error")
+        else:
+            # Unix: Send SIGTERM for graceful shutdown
+            os.kill(pid, signal.SIGTERM)
+
+            # Wait for process to die
+            for _ in range(int(timeout * 10)):
+                await asyncio.sleep(0.1)
+                if not is_pid_running(pid):
+                    return (True, "killed")
+
+            # Process didn't die, force kill
+            os.kill(pid, signal.SIGKILL)
+            await asyncio.sleep(0.1)
+            if not is_pid_running(pid):
+                return (True, "killed")
+            return (False, "unknown_error")
+
+    except ProcessLookupError:
+        # Process already dead - success
+        return (True, "already_dead")
+    except PermissionError:
+        # Can't kill - likely not our process
+        return (False, "permission_denied")
+    except OSError:
+        return (False, "unknown_error")
+
+
 class ProjectLock:
     """Atomic file lock for a project.