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

ralphx/core/project_export.py

@@ -34,7 +34,6 @@ class WorkflowSummary:
     """Summary of a workflow in the project."""
     id: str
     name: str
-    namespace: str
     steps_count: int
     items_count: int
     resources_count: int
@@ -137,7 +136,6 @@ class ProjectExporter:
             summaries.append(WorkflowSummary(
                 id=wf['id'],
                 name=wf['name'],
-                namespace=wf['namespace'],
                 steps_count=wf_preview.steps_count,
                 items_count=wf_preview.items_total,
                 resources_count=wf_preview.resources_count,
@@ -231,7 +229,7 @@ class ProjectExporter:
             )
 
             for wf in workflows:
-                wf_prefix = f"workflows/{wf['namespace']}/"
+                wf_prefix = f"workflows/{wf['id']}/"
 
                 # Get workflow data
                 steps = self.db.list_workflow_steps(wf['id'])
@@ -261,7 +259,6 @@ class ProjectExporter:
                         'id': wf['id'],
                         'template_id': wf.get('template_id'),
                         'name': wf['name'],
-                        'namespace': wf['namespace'],
                         'status': 'draft',
                         'current_step': 1,
                         'created_at': wf.get('created_at'),
@@ -432,7 +429,6 @@ class ProjectExporter:
                     {
                         'id': w['id'],
                         'name': w['name'],
-                        'namespace': w['namespace'],
                     }
                     for w in workflows
                 ],

ralphx/core/project_import.py

@@ -30,7 +30,6 @@ class WorkflowPreviewInfo:
     """Preview info for a workflow in the project export."""
     id: str
     name: str
-    namespace: str
     steps_count: int
     items_count: int
     resources_count: int
@@ -263,8 +262,13 @@ class ProjectImporter:
 
         # Get workflow info from manifest
         for wf_info in manifest.get('contents', {}).get('workflows', []):
-            wf_namespace = wf_info['namespace']
-            wf_prefix = f"workflows/{wf_namespace}/"
+            wf_id = wf_info['id']
+            # Support both new (workflow_id) and old (namespace) path formats
+            wf_prefix = f"workflows/{wf_id}/"
+            # Check for old namespace-based paths for backward compatibility
+            old_namespace = wf_info.get('namespace')
+            if old_namespace and f"workflows/{old_namespace}/workflow.json" in zf.namelist():
+                wf_prefix = f"workflows/{old_namespace}/"
 
             # Count items
             items_count = 0
@@ -304,7 +308,6 @@ class ProjectImporter:
             workflows_info.append(WorkflowPreviewInfo(
                 id=wf_info['id'],
                 name=wf_info['name'],
-                namespace=wf_namespace,
                 steps_count=steps_count,
                 items_count=items_count,
                 resources_count=resources_count,
@@ -354,7 +357,6 @@ class ProjectImporter:
             workflows=[WorkflowPreviewInfo(
                 id=wf_info.get('id', ''),
                 name=wf_info.get('name', ''),
-                namespace=wf_info.get('namespace', ''),
                 steps_count=contents.get('steps', 0),
                 items_count=contents.get('items_total', 0),
                 resources_count=contents.get('resources', 0),
@@ -484,8 +486,13 @@ class ProjectImporter:
         import hashlib
         import uuid
 
-        wf_namespace = wf_info['namespace']
-        wf_prefix = f"workflows/{wf_namespace}/"
+        wf_id = wf_info['id']
+        # Support both new (workflow_id) and old (namespace) path formats
+        wf_prefix = f"workflows/{wf_id}/"
+        # Check for old namespace-based paths for backward compatibility
+        old_namespace = wf_info.get('namespace')
+        if old_namespace and f"workflows/{old_namespace}/workflow.json" in zf.namelist():
+            wf_prefix = f"workflows/{old_namespace}/"
 
         # Read workflow data
         workflow_data = json.loads(zf.read(f"{wf_prefix}workflow.json").decode('utf-8'))
@@ -522,15 +529,10 @@ class ProjectImporter:
             hash_suffix = hashlib.md5(f"{old_id}-{uuid.uuid4().hex}".encode()).hexdigest()[:8]
             id_mapping[old_id] = f"{old_id}-{hash_suffix}"
 
-        # Generate unique namespace
-        base_namespace = workflow_data['workflow']['namespace']
-        namespace = self._generate_unique_namespace(base_namespace)
-
         # Create workflow
         workflow = self.db.create_workflow(
             id=new_wf_id,
             name=workflow_data['workflow']['name'],
-            namespace=namespace,
             template_id=workflow_data['workflow'].get('template_id'),
             status='draft',
         )
@@ -666,20 +668,3 @@ class ProjectImporter:
             id_mapping=id_mapping,
             warnings=warnings,
         )
-
-    def _generate_unique_namespace(self, base_namespace: str) -> str:
-        """Generate a unique namespace."""
-        import uuid
-
-        existing_workflows = self.db.list_workflows()
-        existing_namespaces = {w['namespace'] for w in existing_workflows}
-
-        if base_namespace not in existing_namespaces:
-            return base_namespace
-
-        for i in range(1, 1000):
-            candidate = f"{base_namespace[:56]}-{i}"
-            if candidate not in existing_namespaces:
-                return candidate
-
-        return f"{base_namespace[:50]}-{uuid.uuid4().hex[:8]}"

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/sample_project.py

@@ -124,14 +124,10 @@ def _create_workflow_with_stories(
             logger.warning(f"Template '{template_id}' not found")
             return None
 
-        # Generate namespace
-        namespace = f"excuse-gen-{uuid.uuid4().hex[:7]}"
-
-        # Create workflow
+        # Create workflow (namespace parameter removed in schema v16)
         workflow = project_db.create_workflow(
             id=workflow_id,
             name="Build Excuse Generator",
-            namespace=namespace,
             template_id=template_id,
             status="draft",
         )

ralphx/core/templates.py

@@ -9,15 +9,15 @@ from typing import Optional
 
 # Base loop templates
 TEMPLATES: dict[str, dict] = {
-    "research": {
-        "name": "research",
-        "display_name": "Research Loop",
+    "extractgen_requirements": {
+        "name": "extractgen_requirements",
+        "display_name": "Extract Requirements Loop",
         "description": "Discover and document user stories from design documents or web research",
         "type": "generator",
         "category": "discovery",
         "config": {
-            "name": "research",
-            "display_name": "Research Loop",
+            "name": "extractgen_requirements",
+            "display_name": "Extract Requirements Loop",
             "type": "generator",
             "description": "Discover and document user stories from design documents",
             "item_types": {
@@ -34,7 +34,7 @@ TEMPLATES: dict[str, dict] = {
                     "model": "claude-sonnet-4-20250514",
                     "timeout": 180,
                     "tools": [],
-                    "prompt_template": "prompts/research_turbo.md",
+                    "prompt_template": "prompts/extractgen_requirements_turbo.md",
                 },
                 {
                     "name": "deep",
@@ -42,7 +42,7 @@ TEMPLATES: dict[str, dict] = {
                     "model": "claude-sonnet-4-20250514",
                     "timeout": 900,
                     "tools": ["web_search"],
-                    "prompt_template": "prompts/research_deep.md",
+                    "prompt_template": "prompts/extractgen_requirements_deep.md",
                 },
             ],
             "mode_selection": {
@@ -109,7 +109,7 @@ TEMPLATES: dict[str, dict] = {
                 "input": {
                     "singular": "story",
                     "plural": "stories",
-                    "source": "research",
+                    "source": "extractgen_requirements",
                     "description": "Stories to implement",
                 },
                 "output": {
@@ -219,7 +219,7 @@ def get_template(name: str) -> Optional[dict]:
     """Get a template by name.
 
     Args:
-        name: Template name (e.g., 'research', 'implementation')
+        name: Template name (e.g., 'extractgen_requirements', 'implementation')
 
     Returns:
         Template dict or None if not found

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
@@ -610,7 +639,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/core/workflow_export.py

@@ -63,7 +63,7 @@ class SecretMatch:
 class ExportPreview:
     """Preview of what will be exported."""
     workflow_name: str
-    workflow_namespace: str
+    workflow_id: str
     steps_count: int
     items_total: int
     items_by_step: dict[int, int]  # step_id -> count
@@ -155,7 +155,7 @@ class WorkflowExporter:
 
         return ExportPreview(
             workflow_name=workflow['name'],
-            workflow_namespace=workflow['namespace'],
+            workflow_id=workflow['id'],
             steps_count=len(steps),
             items_total=total_items,  # Show real count, not truncated count
             items_by_step=items_by_step,
@@ -247,8 +247,7 @@ class WorkflowExporter:
 
         # Generate filename
         timestamp = datetime.utcnow().strftime('%Y%m%d-%H%M%S')
-        namespace = workflow['namespace']
-        filename = f"workflow-{namespace}-{timestamp}.ralphx.zip"
+        filename = f"workflow-{workflow['id']}-{timestamp}.ralphx.zip"
 
         zip_bytes = zip_buffer.getvalue()
 
@@ -342,7 +341,7 @@ class WorkflowExporter:
                         snippet=redacted[:50] + '...' if len(redacted) > 50 else redacted,
                     ))
 
-        # Scan workflow name and namespace (unlikely but check)
+        # Scan workflow name (unlikely but check)
         scan_text(workflow.get('name', ''), 'workflow.name')
 
         # Scan resources
@@ -383,7 +382,6 @@ class WorkflowExporter:
             'workflow': {
                 'id': workflow['id'],
                 'name': workflow['name'],
-                'namespace': workflow['namespace'],
                 'template_id': workflow.get('template_id'),
             },
             'contents': {
@@ -447,7 +445,6 @@ class WorkflowExporter:
                 'id': workflow['id'],
                 'template_id': workflow.get('template_id'),
                 'name': workflow['name'],
-                'namespace': workflow['namespace'],
                 'status': 'draft',  # Reset status on export
                 'current_step': 1,  # Reset to beginning
                 'created_at': workflow.get('created_at'),

ralphx/core/workflow_import.py

@@ -16,7 +16,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Optional
 
-from ralphx.core.project_db import PROJECT_SCHEMA_VERSION, ProjectDatabase, validate_namespace
+from ralphx.core.project_db import PROJECT_SCHEMA_VERSION, ProjectDatabase
 from ralphx.core.workflow_export import EXPORT_FORMAT_NAME, EXPORT_FORMAT_VERSION
 
 
@@ -106,7 +106,7 @@ class ImportPreview:
     """Preview of what will be imported."""
     # Basic info
     workflow_name: str
-    workflow_namespace: str
+    workflow_id: str
     exported_at: str
     ralphx_version: str
     schema_version: int
@@ -254,7 +254,7 @@ class WorkflowImporter:
 
             return ImportPreview(
                 workflow_name=manifest['workflow']['name'],
-                workflow_namespace=manifest['workflow']['namespace'],
+                workflow_id=manifest['workflow']['id'],
                 exported_at=manifest['exported_at'],
                 ralphx_version=manifest.get('ralphx_version', 'unknown'),
                 schema_version=manifest.get('schema_version', 0),
@@ -736,10 +736,6 @@ class WorkflowImporter:
         old_wf_id = workflow_data['workflow']['id']
         new_wf_id = id_mapping[old_wf_id]
 
-        # Generate new namespace (ensure unique)
-        base_namespace = workflow_data['workflow']['namespace']
-        namespace = self._generate_unique_namespace(base_namespace)
-
         # Update items with new IDs
         updated_items = self._update_references(items_data, id_mapping)
 
@@ -747,7 +743,6 @@ class WorkflowImporter:
         workflow = self.db.create_workflow(
             id=new_wf_id,
             name=workflow_data['workflow']['name'],
-            namespace=namespace,
             template_id=workflow_data['workflow'].get('template_id'),
             status='draft',
         )
@@ -905,7 +900,6 @@ class WorkflowImporter:
         original_metadata = {
             'imported_from': {
                 'original_workflow_id': old_wf_id,
-                'original_namespace': workflow_data['workflow']['namespace'],
                 'export_timestamp': manifest.get('exported_at'),
                 'export_version': manifest.get('ralphx_version'),
             },
@@ -1153,21 +1147,3 @@ class WorkflowImporter:
             id_mapping=step_id_mapping,
             warnings=warnings,
         )
-
-    def _generate_unique_namespace(self, base_namespace: str) -> str:
-        """Generate a unique namespace based on the base."""
-        # Check if base namespace exists
-        existing_workflows = self.db.list_workflows()
-        existing_namespaces = {w['namespace'] for w in existing_workflows}
-
-        if base_namespace not in existing_namespaces:
-            return base_namespace
-
-        # Add suffix until unique
-        for i in range(1, 1000):
-            candidate = f"{base_namespace[:56]}-{i}"
-            if candidate not in existing_namespaces:
-                return candidate
-
-        # Fallback with uuid
-        return f"{base_namespace[:50]}-{uuid.uuid4().hex[:8]}"

ralphx/mcp/__init__.py

@@ -3,8 +3,12 @@
 This module provides a modular MCP server implementation that exposes RalphX
 functionality as tools that Claude Code can use.
 
-Usage:
-    claude mcp add ralphx -- ralphx mcp
+Usage (Linux/Mac):
+    claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- "$(which ralphx)" mcp
+    # Mac zsh: if "which" fails, run: conda init zsh && source ~/.zshrc
+
+Usage (Windows - find path first with: where.exe ralphx):
+    claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- C:\\path\\to\\ralphx.exe mcp
 """
 
 from ralphx.mcp.server import MCPServer

ralphx/mcp/registry.py

@@ -39,11 +39,11 @@ class ToolRegistry:
         """Check if a tool is registered."""
         return name in self._tools
 
-    def call(self, name: str, **kwargs) -> Any:
+    def call(self, tool_name: str, **kwargs) -> Any:
         """Call a tool by name with arguments."""
-        tool = self._tools.get(name)
+        tool = self._tools.get(tool_name)
         if not tool:
-            raise KeyError(f"Unknown tool: {name}")
+            raise KeyError(f"Unknown tool: {tool_name}")
         return tool.handler(**kwargs)
 
     def get_definitions(self) -> list[dict]:

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"),