Merge pull request #103 from WecoAI/features/require-review

Features/require review

Author: aliroberts

weco/api.py

@@ -1,4 +1,5 @@
 import sys
+from dataclasses import dataclass
 from typing import Dict, Any, Optional, Union, Tuple
 import requests
 from rich.console import Console
@@ -7,6 +8,24 @@
 from .utils import truncate_output
 
 
+@dataclass
+class RunSummary:
+    """Brief run summary from execution task response."""
+
+    id: str
+    status: str
+    name: Optional[str] = None
+    require_review: bool = False
+
+
+@dataclass
+class ExecutionTasksResult:
+    """Result from get_execution_tasks containing tasks and run info."""
+
+    tasks: list
+    run: Optional[RunSummary] = None
+
+
 def handle_api_error(e: requests.exceptions.HTTPError, console: Console) -> None:
     """Extract and display error messages from API responses in a structured format."""
     status = getattr(e.response, "status_code", None)
@@ -110,6 +129,7 @@ def start_optimization_run(
     auth_headers: dict = {},
     timeout: Union[int, Tuple[int, int]] = (10, 3650),
     api_keys: Optional[Dict[str, str]] = None,
+    require_review: bool = False,
 ) -> Optional[Dict[str, Any]]:
     """Start the optimization run."""
     with console.status("[bold green]Starting Optimization..."):
@@ -128,6 +148,7 @@ def start_optimization_run(
                 "eval_timeout": eval_timeout,
                 "save_logs": save_logs,
                 "log_dir": log_dir,
+                "require_review": require_review,
                 "metadata": {"client_name": "cli", "client_version": __pkg_version__},
             }
             if api_keys:
@@ -315,3 +336,107 @@ def report_termination(
     except Exception as e:
         print(f"Warning: Failed to report termination to backend for run {run_id}: {e}", file=sys.stderr)
         return False
+
+
+# --- Execution Queue API Functions ---
+
+
+def get_execution_tasks(
+    run_id: str, auth_headers: dict = {}, timeout: Union[int, Tuple[int, int]] = (5, 30)
+) -> Optional[ExecutionTasksResult]:
+    """Poll for ready execution tasks.
+
+    Args:
+        run_id: The run ID to get tasks for.
+        auth_headers: Authentication headers.
+        timeout: Request timeout.
+
+    Returns:
+        ExecutionTasksResult with tasks and run summary, or None if request failed.
+    """
+    try:
+        response = requests.get(
+            f"{__base_url__}/execution-tasks/", params={"run_id": run_id}, headers=auth_headers, timeout=timeout
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # Extract run summary from top-level run field
+        run_summary = None
+        if data.get("run"):
+            run_data = data["run"]
+            run_summary = RunSummary(
+                id=run_data["id"],
+                status=run_data["status"],
+                name=run_data.get("name"),
+                require_review=run_data.get("require_review", False),
+            )
+
+        return ExecutionTasksResult(tasks=data.get("tasks", []), run=run_summary)
+    except requests.exceptions.HTTPError:
+        return None
+    except Exception:
+        return None
+
+
+def claim_execution_task(
+    task_id: str, auth_headers: dict = {}, timeout: Union[int, Tuple[int, int]] = (5, 30)
+) -> Optional[Dict[str, Any]]:
+    """Claim an execution task.
+
+    Args:
+        task_id: The task ID to claim.
+        auth_headers: Authentication headers.
+        timeout: Request timeout.
+
+    Returns:
+        The claimed task with revision, or None if already claimed or error.
+    """
+    try:
+        response = requests.post(f"{__base_url__}/execution-tasks/{task_id}/claim", headers=auth_headers, timeout=timeout)
+        if response.status_code == 409:
+            return None  # Already claimed
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.HTTPError:
+        return None
+    except Exception:
+        return None
+
+
+def submit_execution_result(
+    run_id: str,
+    task_id: str,
+    execution_output: str,
+    auth_headers: dict = {},
+    timeout: Union[int, Tuple[int, int]] = (10, 3650),
+    api_keys: Optional[Dict[str, str]] = None,
+) -> Optional[Dict[str, Any]]:
+    """Submit execution result for a task.
+
+    Args:
+        run_id: The run ID.
+        task_id: The task ID being completed.
+        execution_output: The execution output to submit.
+        auth_headers: Authentication headers.
+        timeout: Request timeout.
+        api_keys: Optional API keys for LLM providers.
+
+    Returns:
+        The suggest response, or None if request failed.
+    """
+    try:
+        truncated_output = truncate_output(execution_output)
+        request_json = {"execution_output": truncated_output, "task_id": task_id, "metadata": {}}
+        if api_keys:
+            request_json["api_keys"] = api_keys
+
+        response = requests.post(
+            f"{__base_url__}/runs/{run_id}/suggest", json=request_json, headers=auth_headers, timeout=timeout
+        )
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.HTTPError:
+        return None
+    except Exception:
+        return None

weco/browser.py

@@ -0,0 +1,29 @@
+"""Cross-platform browser utilities."""
+
+import webbrowser
+
+
+def open_browser(url: str) -> bool:
+    """
+    Open a URL in the user's default web browser.
+
+    This function is cross-platform compatible (Windows, macOS, Linux).
+    It uses Python's built-in webbrowser module which handles platform
+    detection automatically.
+
+    Args:
+        url: The URL to open in the browser.
+
+    Returns:
+        True if the browser was opened successfully, False otherwise.
+    """
+    try:
+        # webbrowser.open() is cross-platform and uses the default browser
+        # - On macOS: uses 'open' command
+        # - On Windows: uses 'start' command
+        # - On Linux: tries common browsers (xdg-open, gnome-open, etc.)
+        return webbrowser.open(url)
+    except Exception:
+        # Silently fail - browser opening is a convenience feature
+        # and should not interrupt the optimization flow
+        return False

weco/cli.py

@@ -3,9 +3,10 @@
 from rich.console import Console
 from rich.traceback import install
 
-from .auth import clear_api_key
+from .auth import clear_api_key, perform_login, load_weco_api_key
 from .constants import DEFAULT_MODELS
 from .utils import check_for_cli_updates, get_default_model, UnrecognizedAPIKeysError, DefaultModelNotFoundError
+from .validation import validate_source_file, validate_log_directory, ValidationError, print_validation_error
 
 
 install(show_locals=True)
@@ -108,6 +109,11 @@ def configure_run_parser(run_parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Automatically apply the best solution to the source file without prompting",
     )
+    run_parser.add_argument(
+        "--require-review",
+        action="store_true",
+        help="Require manual review and approval of each proposed change before execution",
+    )
 
     default_api_keys = " ".join([f"{provider}=xxx" for provider, _ in DEFAULT_MODELS])
     supported_providers = ", ".join([provider for provider, _ in DEFAULT_MODELS])
@@ -206,7 +212,15 @@ def configure_resume_parser(resume_parser: argparse.ArgumentParser) -> None:
 
 def execute_run_command(args: argparse.Namespace) -> None:
     """Execute the 'weco run' command with all its logic."""
-    from .optimizer import execute_optimization
+    from .optimizer import optimize
+
+    # Early validation — fail fast with helpful errors
+    try:
+        validate_source_file(args.source)
+        validate_log_directory(args.log_dir)
+    except ValidationError as e:
+        print_validation_error(e, console)
+        sys.exit(1)
 
     try:
         api_keys = parse_api_keys(args.api_key)
@@ -225,7 +239,7 @@ def execute_run_command(args: argparse.Namespace) -> None:
         if api_keys:
             console.print(f"[bold yellow]Custom API keys provided. Using default model: {model} for the run.[/]")
 
-    success = execute_optimization(
+    success = optimize(
         source=args.source,
         eval_command=args.eval_command,
         metric=args.metric,
@@ -234,12 +248,13 @@ def execute_run_command(args: argparse.Namespace) -> None:
         steps=args.steps,
         log_dir=args.log_dir,
         additional_instructions=args.additional_instructions,
-        console=console,
         eval_timeout=args.eval_timeout,
         save_logs=args.save_logs,
-        apply_change=args.apply_change,
         api_keys=api_keys,
+        apply_change=args.apply_change,
+        require_review=args.require_review,
     )
+
     exit_code = 0 if success else 1
     sys.exit(exit_code)
 
@@ -254,12 +269,23 @@ def execute_resume_command(args: argparse.Namespace) -> None:
         console.print(f"[bold red]Error parsing API keys: {e}[/]")
         sys.exit(1)
 
-    success = resume_optimization(run_id=args.run_id, console=console, api_keys=api_keys, apply_change=args.apply_change)
+    success = resume_optimization(run_id=args.run_id, api_keys=api_keys, apply_change=args.apply_change)
+
     sys.exit(0 if success else 1)
 
 
 def main() -> None:
     """Main function for the Weco CLI."""
+    try:
+        _main()
+    except KeyboardInterrupt:
+        # Clean exit on Ctrl+C without traceback
+        console.print("\n[yellow]Interrupted.[/]")
+        sys.exit(130)  # Standard exit code for SIGINT
+
+
+def _main() -> None:
+    """Internal main function containing the CLI logic."""
     check_for_cli_updates()
 
     parser = argparse.ArgumentParser(
@@ -277,6 +303,9 @@ def main() -> None:
     )
     configure_run_parser(run_parser)  # Use the helper to add arguments
 
+    # --- Login Command Parser Setup ---
+    _ = subparsers.add_parser("login", help="Log in to Weco and save your API key.")
+
     # --- Logout Command Parser Setup ---
     _ = subparsers.add_parser("logout", help="Log out from Weco and clear saved API key.")
 
@@ -295,7 +324,20 @@ def main() -> None:
 
     args = parser.parse_args()
 
-    if args.command == "logout":
+    if args.command == "login":
+        # Check if already logged in
+        existing_key = load_weco_api_key()
+        if existing_key:
+            console.print("[bold green]You are already logged in.[/]")
+            console.print("[dim]Use 'weco logout' to log out first if you want to switch accounts.[/]")
+            sys.exit(0)
+
+        # Perform the login flow
+        if perform_login(console):
+            sys.exit(0)
+        else:
+            sys.exit(1)
+    elif args.command == "logout":
         clear_api_key()
         sys.exit(0)
     elif args.command == "run":