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

ralphx/core/resources.py

@@ -225,6 +225,12 @@ class ResourceManager:
         """
         file_path = self._resources_path / resource_data["file_path"]
 
+        # Security: verify path stays within resources directory
+        resolved = file_path.resolve()
+        resources_root = self._resources_path.resolve()
+        if not str(resolved).startswith(str(resources_root) + "/") and resolved != resources_root:
+            return None
+
         if not file_path.exists():
             return None
 
@@ -426,8 +432,19 @@ class ResourceManager:
         else:
             file_name = name
 
+        # Security: prevent path traversal in resource names
+        # Only allow simple filenames (alphanumeric, hyphens, underscores, dots)
+        if ".." in file_name or "/" in file_name or "\\" in file_name or "\0" in file_name:
+            raise ValueError(f"Invalid resource name: {name} (path traversal characters not allowed)")
+
         file_path = self.get_resources_path(resource_type) / f"{file_name}.md"
 
+        # Verify resolved path stays within resources directory
+        resolved = file_path.resolve()
+        resources_root = self.get_resources_path(resource_type).resolve()
+        if not str(resolved).startswith(str(resources_root) + "/") and resolved != resources_root:
+            raise ValueError(f"Invalid resource name: {name} (resolves outside resources directory)")
+
         # Ensure directory exists
         file_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -483,6 +500,11 @@ class ResourceManager:
         # Update file content if provided
         if content is not None:
             file_path = self._resources_path / resource["file_path"]
+            # Security: verify path stays within resources directory
+            resolved = file_path.resolve()
+            resources_root = self._resources_path.resolve()
+            if not str(resolved).startswith(str(resources_root) + "/") and resolved != resources_root:
+                return False
             file_path.parent.mkdir(parents=True, exist_ok=True)
             file_path.write_text(content, encoding="utf-8")
 
@@ -519,8 +541,12 @@ class ResourceManager:
         # Delete file if requested
         if delete_file:
             file_path = self._resources_path / resource["file_path"]
-            if file_path.exists():
-                file_path.unlink()
+            # Security: verify path stays within resources directory
+            resolved = file_path.resolve()
+            resources_root = self._resources_path.resolve()
+            if str(resolved).startswith(str(resources_root) + "/") or resolved == resources_root:
+                if file_path.exists():
+                    file_path.unlink()
 
         # Delete database entry
         return self.db.delete_resource(resource_id)

ralphx/core/session.py

@@ -27,6 +27,8 @@ class SessionEventType(str, Enum):
     TEXT = "text"
     TOOL_CALL = "tool_call"
     TOOL_RESULT = "tool_result"
+    THINKING = "thinking"
+    USAGE = "usage"
     ERROR = "error"
     COMPLETE = "complete"
     UNKNOWN = "unknown"
@@ -42,6 +44,8 @@ class SessionEvent:
     tool_name: Optional[str] = None
     tool_input: Optional[dict] = None
     tool_result: Optional[str] = None
+    thinking: Optional[str] = None
+    usage: Optional[dict] = None
     error_message: Optional[str] = None
     raw_data: dict = field(default_factory=dict)
 
@@ -327,6 +331,9 @@ class SessionTailer:
     def _parse_event(self, data: dict) -> SessionEvent:
         """Parse event data into a SessionEvent.
 
+        Handles both stream-json format (content_block_delta) and
+        session JSONL format (assistant/user message pairs).
+
         Args:
             data: Parsed JSON data.
 
@@ -335,14 +342,21 @@ class SessionTailer:
         """
         msg_type = data.get("type", "")
 
-        # Init event
-        if msg_type == "init" or "session_id" in data:
+        # Session JSONL: queue-operation is the first line with sessionId
+        if msg_type == "queue-operation":
+            return SessionEvent(
+                type=SessionEventType.INIT,
+                raw_data=data,
+            )
+
+        # Stream-json: init event
+        if msg_type == "init" or (msg_type == "system" and "session_id" in data):
             return SessionEvent(
                 type=SessionEventType.INIT,
                 raw_data=data,
             )
 
-        # Text content
+        # Stream-json: text content delta
         if msg_type == "content_block_delta":
             delta = data.get("delta", {})
             if delta.get("type") == "text_delta":
@@ -352,7 +366,7 @@ class SessionTailer:
                     raw_data=data,
                 )
 
-        # Tool call start
+        # Stream-json: tool call start
         if msg_type == "content_block_start":
             content = data.get("content_block", {})
             if content.get("type") == "tool_use":
@@ -363,7 +377,7 @@ class SessionTailer:
                     raw_data=data,
                 )
 
-        # Tool result
+        # Stream-json: tool result
         if msg_type == "tool_result":
             return SessionEvent(
                 type=SessionEventType.TOOL_RESULT,
@@ -380,31 +394,69 @@ class SessionTailer:
                 raw_data=data,
             )
 
-        # Message complete
+        # Stream-json: message complete
         if msg_type == "message_stop":
             return SessionEvent(
                 type=SessionEventType.COMPLETE,
                 raw_data=data,
             )
 
-        # Assistant message with content array
-        # Claude Code session format: content is at data["message"]["content"]
+        # Session JSONL: assistant message with content array
         if msg_type == "assistant":
             message = data.get("message", {})
             content = message.get("content") if message else data.get("content")
+            usage = message.get("usage") if message else None
+            is_error = data.get("isApiErrorMessage", False)
+
+            if is_error:
+                error_text = ""
+                if isinstance(content, list):
+                    for block in content:
+                        if block.get("type") == "text":
+                            error_text = block.get("text", "")
+                return SessionEvent(
+                    type=SessionEventType.ERROR,
+                    error_message=error_text or data.get("error", "API error"),
+                    raw_data=data,
+                )
+
             if isinstance(content, list):
+                # Return the first meaningful event (text > tool_use > thinking)
                 for block in content:
-                    if block.get("type") == "text":
+                    block_type = block.get("type")
+                    if block_type == "text":
                         return SessionEvent(
                             type=SessionEventType.TEXT,
                             text=block.get("text", ""),
+                            usage=usage,
                             raw_data=data,
                         )
-                    if block.get("type") == "tool_use":
+                    if block_type == "tool_use":
                         return SessionEvent(
                             type=SessionEventType.TOOL_CALL,
                             tool_name=block.get("name"),
                             tool_input=block.get("input", {}),
+                            usage=usage,
+                            raw_data=data,
+                        )
+                    if block_type == "thinking":
+                        return SessionEvent(
+                            type=SessionEventType.THINKING,
+                            thinking=block.get("thinking", ""),
+                            usage=usage,
+                            raw_data=data,
+                        )
+
+        # Session JSONL: user message with tool results
+        if msg_type == "user":
+            message = data.get("message", {})
+            content = message.get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if block.get("type") == "tool_result":
+                        return SessionEvent(
+                            type=SessionEventType.TOOL_RESULT,
+                            tool_result=str(block.get("content", ""))[:1000],
                             raw_data=data,
                         )
 

ralphx/core/templates.py

@@ -1,25 +1,70 @@
 """
 Base loop templates for quick-start configuration.
 
+Templates map 1:1 to workflow step processing types:
+- design_doc: Interactive planning with web research
+- extractgen_requirements: Extract user stories from design documents
+- webgen_requirements: Discover requirements via web research
+- implementation: Implement user stories with code changes
+
 Templates are global, read-only, and shipped with RalphX.
 Users can copy template config into their loop, then modify as needed.
 """
 
 from typing import Optional
 
-# Base loop templates
+# Base loop templates — one per processing_type
 TEMPLATES: dict[str, dict] = {
+    "design_doc": {
+        "name": "design_doc",
+        "display_name": "Design Document",
+        "description": "Interactive planning chat to build a design document with web research",
+        "type": "generator",
+        "category": "planning",
+        "default_tools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
+        "config": {
+            "name": "design_doc",
+            "display_name": "Design Document",
+            "type": "generator",
+            "description": "Build a comprehensive design document through interactive planning",
+            "item_types": {
+                "output": {
+                    "singular": "artifact",
+                    "plural": "artifacts",
+                    "description": "Design document and guardrails",
+                }
+            },
+            "modes": [
+                {
+                    "name": "default",
+                    "description": "Interactive planning with web research",
+                    "model": "claude-sonnet-4-20250514",
+                    "timeout": 300,
+                    "tools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
+                    "prompt_template": "prompts/planning.md",
+                }
+            ],
+            "mode_selection": {"strategy": "fixed", "fixed_mode": "default"},
+            "limits": {
+                "max_iterations": 100,
+                "max_runtime_seconds": 28800,
+                "max_consecutive_errors": 5,
+                "cooldown_between_iterations": 5,
+            },
+        },
+    },
     "extractgen_requirements": {
         "name": "extractgen_requirements",
-        "display_name": "Extract Requirements Loop",
-        "description": "Discover and document user stories from design documents or web research",
+        "display_name": "Extract Requirements",
+        "description": "Extract user stories from design documents",
         "type": "generator",
         "category": "discovery",
+        "default_tools": ["Read", "Glob", "Grep"],
         "config": {
             "name": "extractgen_requirements",
-            "display_name": "Extract Requirements Loop",
+            "display_name": "Extract Requirements",
             "type": "generator",
-            "description": "Discover and document user stories from design documents",
+            "description": "Extract and generate user stories from design documents",
             "item_types": {
                 "output": {
                     "singular": "story",
@@ -33,7 +78,7 @@ TEMPLATES: dict[str, dict] = {
                     "description": "Fast extraction from design docs (no web search)",
                     "model": "claude-sonnet-4-20250514",
                     "timeout": 180,
-                    "tools": [],
+                    "tools": ["Read", "Glob", "Grep"],
                     "prompt_template": "prompts/extractgen_requirements_turbo.md",
                 },
                 {
@@ -41,7 +86,7 @@ TEMPLATES: dict[str, dict] = {
                     "description": "Thorough web research for best practices",
                     "model": "claude-sonnet-4-20250514",
                     "timeout": 900,
-                    "tools": ["web_search"],
+                    "tools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
                     "prompt_template": "prompts/extractgen_requirements_deep.md",
                 },
             ],
@@ -63,6 +108,7 @@ TEMPLATES: dict[str, dict] = {
         "description": "Discover missing requirements through web research on domain best practices",
         "type": "generator",
         "category": "discovery",
+        "default_tools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
         "config": {
             "name": "webgen_requirements",
             "display_name": "Web-Generated Requirements",
@@ -81,7 +127,7 @@ TEMPLATES: dict[str, dict] = {
                     "description": "Web research for best practices and gaps",
                     "model": "claude-sonnet-4-20250514",
                     "timeout": 900,
-                    "tools": ["web_search"],
+                    "tools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
                     "prompt_template": "prompts/webgen_requirements.md",
                 }
             ],
@@ -96,13 +142,14 @@ TEMPLATES: dict[str, dict] = {
     },
     "implementation": {
         "name": "implementation",
-        "display_name": "Implementation Loop",
+        "display_name": "Implementation",
         "description": "Implement user stories one at a time with test verification",
         "type": "consumer",
         "category": "execution",
+        "default_tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
         "config": {
             "name": "implementation",
-            "display_name": "Implementation Loop",
+            "display_name": "Implementation",
             "type": "consumer",
             "description": "Implement user stories with automated testing",
             "item_types": {
@@ -124,7 +171,7 @@ TEMPLATES: dict[str, dict] = {
                     "description": "Implement one story per iteration",
                     "model": "claude-sonnet-4-20250514",
                     "timeout": 1800,
-                    "tools": ["file_read", "file_write", "shell"],
+                    "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
                     "prompt_template": "prompts/implementation.md",
                 }
             ],
@@ -136,82 +183,6 @@ TEMPLATES: dict[str, dict] = {
             },
         },
     },
-    "simple_generator": {
-        "name": "simple_generator",
-        "display_name": "Simple Generator",
-        "description": "Basic content generation loop for creating items",
-        "type": "generator",
-        "category": "generation",
-        "config": {
-            "name": "generator",
-            "display_name": "Content Generator",
-            "type": "generator",
-            "description": "Generate content items in a loop",
-            "item_types": {
-                "output": {
-                    "singular": "item",
-                    "plural": "items",
-                    "description": "Generated content",
-                }
-            },
-            "modes": [
-                {
-                    "name": "default",
-                    "description": "Generate content",
-                    "model": "claude-sonnet-4-20250514",
-                    "timeout": 300,
-                    "tools": [],
-                    "prompt_template": "prompts/generate.md",
-                }
-            ],
-            "mode_selection": {"strategy": "fixed", "fixed_mode": "default"},
-            "limits": {
-                "max_iterations": 10,
-                "max_consecutive_errors": 3,
-            },
-        },
-    },
-    "reviewer": {
-        "name": "reviewer",
-        "display_name": "Review Loop",
-        "description": "Process and review existing items (validate, transform, enhance)",
-        "type": "consumer",
-        "category": "processing",
-        "config": {
-            "name": "reviewer",
-            "display_name": "Review Loop",
-            "type": "consumer",
-            "description": "Review and validate existing items",
-            "item_types": {
-                "input": {
-                    "singular": "item",
-                    "plural": "items",
-                    "source": "generator",
-                    "description": "Items to review",
-                },
-                "output": {
-                    "singular": "review",
-                    "plural": "reviews",
-                    "description": "Review results and recommendations",
-                },
-            },
-            "modes": [
-                {
-                    "name": "default",
-                    "description": "Review one item per iteration",
-                    "model": "claude-sonnet-4-20250514",
-                    "timeout": 300,
-                    "tools": [],
-                    "prompt_template": "prompts/review.md",
-                }
-            ],
-            "mode_selection": {"strategy": "fixed", "fixed_mode": "default"},
-            "limits": {
-                "max_iterations": 0,  # Process all items
-                "max_consecutive_errors": 5,
-            },
-        },
-    },
 }
 
 
@@ -227,6 +198,21 @@ def get_template(name: str) -> Optional[dict]:
     return TEMPLATES.get(name)
 
 
+def get_default_tools(processing_type: str) -> Optional[list[str]]:
+    """Get default tools for a processing type.
+
+    Args:
+        processing_type: Step processing type (design_doc, extractgen_requirements, etc.)
+
+    Returns:
+        List of tool names, or None if not found.
+    """
+    template = TEMPLATES.get(processing_type)
+    if template:
+        return template.get("default_tools")
+    return None
+
+
 def list_templates() -> list[dict]:
     """List all available templates.
 
@@ -240,6 +226,7 @@ def list_templates() -> list[dict]:
             "description": t["description"],
             "type": t["type"],
             "category": t["category"],
+            "default_tools": t.get("default_tools"),
         }
         for t in TEMPLATES.values()
     ]

ralphx/core/workflow_executor.py

@@ -6,10 +6,13 @@ step transitions.
 """
 
 import asyncio
+import logging
 import uuid
 from pathlib import Path
 from typing import Any, Callable, Optional
 
+_logger = logging.getLogger(__name__)
+
 from ralphx.core.executor import LoopExecutor
 from ralphx.core.loop import LoopLoader
 from ralphx.core.project import Project
@@ -50,6 +53,7 @@ class WorkflowExecutor:
         self.workflow_id = workflow_id
         self._on_step_change = on_step_change
         self._running_executors: dict[int, LoopExecutor] = {}
+        self._running_tasks: dict[int, asyncio.Task] = {}
 
     def get_workflow(self) -> Optional[dict]:
         """Get the current workflow."""
@@ -161,6 +165,9 @@ class WorkflowExecutor:
             # Create new loop for this step
             loop_config = self._create_step_loop(step, loop_name, loop_type)
 
+        # Save loop_name to the step record so the UI can find logs
+        self.db.update_workflow_step(step_id, loop_name=loop_name)
+
         if not loop_config:
             raise ValueError(f"Failed to create loop config for step {step_id}")
 
@@ -188,6 +195,9 @@ class WorkflowExecutor:
         # Check if architecture-first mode is enabled
         architecture_first = step_config.get("architecture_first", False)
 
+        # Get cross-step context links (for generator loops)
+        context_from_steps = step_config.get("context_from_steps") or []
+
         # Create and start executor
         executor = LoopExecutor(
             project=self.project,
@@ -197,12 +207,14 @@ class WorkflowExecutor:
             step_id=step_id,
             consume_from_step_id=consume_from_step_id,
             architecture_first=architecture_first,
+            context_from_steps=context_from_steps,
         )
 
         self._running_executors[step_id] = executor
 
-        # Run executor in background
-        asyncio.create_task(self._run_loop_and_advance(executor, step))
+        # Run executor in background (store task reference to prevent GC and enable cancellation)
+        task = asyncio.create_task(self._run_loop_and_advance(executor, step))
+        self._running_tasks[step_id] = task
 
     async def _run_loop_and_advance(
         self, executor: LoopExecutor, step: dict
@@ -241,8 +253,25 @@ class WorkflowExecutor:
             if auto_advance:
                 await self.complete_step(step_id)
 
+        except Exception:
+            _logger.exception(
+                "Unhandled exception in background loop execution for step %s",
+                step_id,
+            )
+            # Mark step as failed so the error is visible in the UI
+            try:
+                self.db.update_workflow_step(
+                    step_id,
+                    status="error",
+                    artifacts={"error": "Unexpected executor crash - check logs"},
+                )
+                self._emit_step_change(step["step_number"], "error")
+            except Exception:
+                _logger.exception("Failed to mark step %s as errored", step_id)
+
         finally:
             self._running_executors.pop(step_id, None)
+            self._running_tasks.pop(step_id, None)
 
     def _create_step_loop(
         self, step: dict, loop_name: str, loop_type: str
@@ -268,6 +297,7 @@ class WorkflowExecutor:
         max_iterations = step_config.get("max_iterations")
         cooldown = step_config.get("cooldown_between_iterations")
         max_errors = step_config.get("max_consecutive_errors")
+        tools = step_config.get("allowedTools")
 
         # Generate YAML config based on loop type
         if loop_type == "generator":
@@ -278,6 +308,7 @@ class WorkflowExecutor:
                 max_iterations=max_iterations,
                 cooldown_between_iterations=cooldown,
                 max_consecutive_errors=max_errors,
+                tools=tools,
             )
         else:
             config_yaml = generate_simple_implementation_config(
@@ -287,6 +318,7 @@ class WorkflowExecutor:
                 max_iterations=max_iterations,
                 cooldown_between_iterations=cooldown,
                 max_consecutive_errors=max_errors,
+                tools=tools,
             )
 
         # Save to database
@@ -610,7 +642,7 @@ class WorkflowExecutor:
 
         # Stop running executors
         for executor in self._running_executors.values():
-            executor.stop()
+            await executor.stop()
 
         self.db.update_workflow(self.workflow_id, status="paused")
         return self.get_workflow()

ralphx/mcp/tools/diagnostics.py

@@ -243,7 +243,7 @@ def get_stop_reason(
         if sessions:
             last_session = sessions[-1]
             events = project_db.get_session_events(
-                session_id=last_session["id"],
+                session_id=last_session.get("session_id", last_session.get("id")),
                 event_type="error",
                 limit=5,
             )

ralphx/mcp/tools/monitoring.py

@@ -73,8 +73,8 @@ def list_runs(
                 "workflow_id": r.get("workflow_id"),
                 "step_id": r.get("step_id"),
                 "status": r["status"],
-                "current_iteration": r.get("current_iteration"),
-                "current_mode": r.get("current_mode"),
+                "iterations_completed": r.get("iterations_completed", 0),
+                "items_generated": r.get("items_generated", 0),
                 "executor_pid": r.get("executor_pid"),
                 "started_at": r.get("started_at"),
                 "completed_at": r.get("completed_at"),
@@ -117,8 +117,8 @@ def get_run(
         "workflow_id": run.get("workflow_id"),
         "step_id": run.get("step_id"),
         "status": run["status"],
-        "current_iteration": run.get("current_iteration"),
-        "current_mode": run.get("current_mode"),
+        "iterations_completed": run.get("iterations_completed", 0),
+        "items_generated": run.get("items_generated", 0),
         "executor_pid": run.get("executor_pid"),
         "started_at": run.get("started_at"),
         "completed_at": run.get("completed_at"),
@@ -130,11 +130,11 @@ def get_run(
         sessions = project_db.list_sessions(run_id=run_id)
         result["sessions"] = [
             {
-                "id": s["id"],
+                "id": s.get("session_id", s.get("id")),
+                "iteration": s.get("iteration"),
                 "status": s.get("status"),
                 "started_at": s.get("started_at"),
-                "completed_at": s.get("completed_at"),
-                "event_count": s.get("event_count", 0),
+                "duration_seconds": s.get("duration_seconds"),
             }
             for s in sessions
         ]
@@ -146,7 +146,6 @@ def get_run(
 def get_logs(
     slug: str,
     level: Optional[str] = None,
-    category: Optional[str] = None,
     run_id: Optional[str] = None,
     session_id: Optional[str] = None,
     search: Optional[str] = None,
@@ -170,7 +169,6 @@ def get_logs(
     try:
         logs, total = project_db.get_logs(
             level=level,
-            category=category,
             run_id=run_id,
             session_id=session_id,
             search=search,
@@ -190,10 +188,8 @@ def get_logs(
                 "id": log.get("id"),
                 "timestamp": log.get("timestamp"),
                 "level": log.get("level"),
-                "category": log.get("category"),
                 "message": scrub_sensitive_data(log.get("message", "")),
                 "run_id": log.get("run_id"),
-                "session_id": log.get("session_id"),
             }
             for log in logs
         ],
@@ -311,13 +307,12 @@ def list_sessions(
     return PaginatedResult(
         items=[
             {
-                "id": s["id"],
+                "id": s.get("session_id", s.get("id")),
                 "run_id": s.get("run_id"),
+                "iteration": s.get("iteration"),
                 "status": s.get("status"),
                 "started_at": s.get("started_at"),
-                "completed_at": s.get("completed_at"),
-                "event_count": s.get("event_count", 0),
-                "item_id": s.get("item_id"),
+                "duration_seconds": s.get("duration_seconds"),
             }
             for s in paginated
         ],
@@ -432,7 +427,6 @@ def get_monitoring_tools() -> list[ToolDefinition]:
                 properties={
                     "slug": prop_string("Project slug"),
                     "level": prop_enum("Filter by log level", ["debug", "info", "warning", "error"]),
-                    "category": prop_string("Filter by category"),
                     "run_id": prop_string("Filter by run ID"),
                     "session_id": prop_string("Filter by session ID"),
                     "search": prop_string("Search text in messages"),