plato-sdk-v2 2.6.2__py3-none-any.whl → 2.7.1__py3-none-any.whl

plato/v1/cli/chronos.py

@@ -48,30 +48,21 @@ def launch(
         help="Wait for job completion and stream logs",
     ),
 ):
-    """
-    Launch a Chronos job from a config file.
-
-    \b
-    Config format:
-        {
-            "world": {
-                "package": "plato-world-structured-execution:0.1.17",
-                "config": {
-                    "skill_runner": {
-                        "image": "computer-use:1.1.0",
-                        "config": { ... }
-                    },
-                    "secrets": { ... }
-                }
-            },
-            "runtime": {
-                "artifact_id": "..."  // optional
-            }
-        }
-
-    Examples:
-        plato chronos launch config.json
-        plato chronos launch config.json --wait
+    """Launch a Chronos job from a config file.
+
+    Submits a job configuration to the Chronos service to run a world with its
+    configured agents and secrets.
+
+    Arguments:
+        config: Path to the job configuration JSON file
+
+    Options:
+        -u, --url: Chronos API URL (default: https://chronos.plato.so, or CHRONOS_URL env var)
+        -k, --api-key: Plato API key for authentication (or PLATO_API_KEY env var)
+        -w, --wait: Wait for job completion and stream logs (not yet implemented)
+
+    The config file should contain world.package (required) and optionally world.config,
+    runtime.artifact_id, and tags.
     """
     import httpx
 
@@ -148,12 +139,18 @@ def example(
         help="Output file path (prints to stdout if not specified)",
     ),
 ):
-    """
-    Generate an example job config file.
+    """Generate an example job config file.
+
+    Creates a sample JSON configuration for launching Chronos jobs, which can be
+    customized for your use case.
+
+    Arguments:
+        world: World type to generate example for (default: "structured-execution")
 
-    Examples:
-        plato chronos example
-        plato chronos example structured-execution -o config.json
+    Options:
+        -o, --output: Output file path. If not specified, prints to stdout.
+
+    Available worlds: structured-execution, code-world
     """
     examples = {
         "structured-execution": {
@@ -724,14 +721,17 @@ def stop(
         help="Plato API key for authentication",
     ),
 ):
-    """
-    Stop a running Chronos session.
+    """Stop a running Chronos session.
 
-    This marks the session as cancelled with status reason "User cancelled".
+    Marks the session as cancelled with status reason "User cancelled" and terminates
+    any running containers.
 
-    Examples:
-        plato chronos stop abc123
-        plato chronos stop abc123 --url https://chronos.plato.so
+    Arguments:
+        session_id: The session ID to stop (from 'plato chronos launch' output)
+
+    Options:
+        -u, --url: Chronos API URL (default: https://chronos.plato.so, or CHRONOS_URL env var)
+        -k, --api-key: Plato API key for authentication (or PLATO_API_KEY env var)
     """
     # Set defaults
     if not chronos_url:
@@ -784,32 +784,20 @@ def dev(
         typer.Option("--env-timeout", help="Timeout for environment creation (seconds)"),
     ] = 7200,
 ):
-    """
-    Run a world locally for development/debugging.
+    """Run a world locally for development/debugging.
 
-    This runs the world in a Docker container with docker.sock mounted,
-    allowing the world to spawn agent containers.
+    Builds and runs the world in a Docker container with docker.sock mounted,
+    allowing the world to spawn agent containers. Mounts local source code for
+    live development without rebuilding.
 
-    \b
-    Config format (same as Chronos launch):
-    {
-        "world": {
-            "package": "plato-world-structured-execution:0.1.17",
-            "config": {
-                "skill_runner": {
-                    "image": "computer-use:1.1.0",
-                    "config": { ... }
-                },
-                "secrets": { ... }
-            }
-        },
-        "runtime": {
-            "artifact_id": "..."
-        }
-    }
+    Arguments:
+        config: Path to job config JSON file (same format as 'plato chronos launch')
 
-    Example:
-        plato chronos dev config.json -w ~/worlds/my-world -a ~/agents --platform linux/amd64
+    Options:
+        -w, --world-dir: Directory containing world source code to mount into the container
+        -a, --agents-dir: Directory containing agent source code to mount (optional)
+        -p, --platform: Docker platform for building (e.g., 'linux/amd64' for M1 Macs)
+        --env-timeout: Timeout in seconds for environment creation (default: 7200 = 2 hours)
     """
     logging.basicConfig(
         level=logging.INFO,

plato/v1/cli/main.py

@@ -11,6 +11,7 @@ from dotenv import load_dotenv
 from plato.v1.cli.agent import agent_app
 from plato.v1.cli.chronos import chronos_app
 from plato.v1.cli.pm import pm_app
+from plato.v1.cli.proxy import app as proxy_app
 from plato.v1.cli.sandbox import sandbox_app
 from plato.v1.cli.utils import console
 from plato.v1.cli.world import world_app
@@ -73,6 +74,7 @@ app.add_typer(pm_app, name="pm")
 app.add_typer(agent_app, name="agent")
 app.add_typer(world_app, name="world")
 app.add_typer(chronos_app, name="chronos")
+app.add_typer(proxy_app, name="proxy")
 
 
 # =============================================================================
@@ -84,21 +86,13 @@ app.add_typer(chronos_app, name="chronos")
 def hub(
     ctx: typer.Context,
 ):
-    """
-    Launch the Plato Hub CLI (interactive TUI for managing simulators).
-
-    The hub command opens the Go-based Plato CLI which provides an interactive
-    terminal UI for browsing simulators, launching environments, and managing VMs.
+    """Launch the Plato Hub CLI (interactive TUI for managing simulators).
 
-    Available subcommands:
-    - clone <service>: Clone a service from Plato Hub
-    - credentials: Display your Plato Hub credentials
-    - (no args): Start interactive TUI mode
+    Opens the Go-based Plato CLI which provides an interactive terminal UI for
+    browsing simulators, launching environments, and managing VMs. Any additional
+    arguments are passed through to the Go CLI.
 
-    Examples:
-        plato hub clone espocrm
-        plato hub credentials
-        plato hub
+    Common subcommands: 'clone <service>', 'credentials', or no args for interactive mode.
     """
     # Find the bundled CLI binary
     plato_bin = _find_bundled_cli()
@@ -129,14 +123,12 @@ def hub(
 def clone(
     service: str = typer.Argument(..., help="Service name to clone (e.g., espocrm)"),
 ):
-    """
-    Clone a service repository from Plato Hub (Gitea).
+    """Clone a service repository from Plato Hub (Gitea).
 
-    This clones the simulator source code to your local machine.
+    Clones the simulator source code to your local machine for development or review.
 
-    Examples:
-        plato clone espocrm
-        plato clone gitea
+    Arguments:
+        service: Service name to clone (e.g., 'espocrm', 'gitea')
     """
     plato_bin = _find_bundled_cli()
     if not plato_bin:
@@ -153,13 +145,10 @@ def clone(
 
 @app.command()
 def credentials():
-    """
-    Display your Plato Hub (Gitea) credentials.
-
-    Shows the username and password needed to access Plato's Gitea repositories.
+    """Display your Plato Hub (Gitea) credentials.
 
-    Example:
-        plato credentials
+    Shows the username and password needed to access Plato's Gitea repositories
+    for cloning and pushing simulator code.
     """
     plato_bin = _find_bundled_cli()
     if not plato_bin:

plato/v1/cli/pm.py

@@ -6,10 +6,12 @@ import os
 import re
 import shutil
 import tempfile
+from datetime import datetime, timedelta
 from pathlib import Path
 
 import httpx
 import typer
+import yaml
 from rich.table import Table
 
 from plato._generated.api.v1.env import get_simulator_by_name, get_simulators
@@ -25,6 +27,7 @@ from plato._generated.models import (
     AddReviewRequest,
     AppApiV1SimulatorRoutesUpdateSimulatorRequest,
     Authentication,
+    Flow,
     Outcome,
     ReviewType,
     UpdateStatusRequest,
@@ -41,6 +44,7 @@ from plato.v1.cli.utils import (
 )
 from plato.v1.cli.verify import pm_verify_app
 from plato.v2.async_.client import AsyncPlato
+from plato.v2.async_.flow_executor import FlowExecutor
 from plato.v2.types import Env
 
 # =============================================================================
@@ -240,44 +244,20 @@ def _list_pending_reviews(review_type: str):
 
 @list_app.command(name="base")
 def list_base():
-    """
-    List simulators pending base/environment review.
-
-    Shows simulators waiting for environment review (status: env_review_requested).
-    Use this to see what needs reviewing before running 'plato pm review base'.
-
-    USAGE:
+    """List simulators pending base/environment review.
 
-        plato pm list base
-
-    OUTPUT COLUMNS:
-
-        - Name: Simulator name
-        - Assignees: Who's assigned to review
-        - Notes: Any notes about the simulator
-        - base_artifact_id: The artifact to review
+    Shows simulators with status 'env_review_requested' in a table format.
+    Displays name, assignees, notes, and base_artifact_id for each simulator.
     """
     _list_pending_reviews("base")
 
 
 @list_app.command(name="data")
 def list_data():
-    """
-    List simulators pending data review.
+    """List simulators pending data review.
 
-    Shows simulators waiting for data review (status: data_review_requested).
-    Use this to see what needs reviewing before running 'plato pm review data'.
-
-    USAGE:
-
-        plato pm list data
-
-    OUTPUT COLUMNS:
-
-        - Name: Simulator name
-        - Assignees: Who's assigned to review
-        - Notes: Any notes about the simulator
-        - data_artifact_id: The artifact to review
+    Shows simulators with status 'data_review_requested' in a table format.
+    Displays name, assignees, notes, and data_artifact_id for each simulator.
     """
     _list_pending_reviews("data")
 
@@ -306,26 +286,31 @@ def review_base(
         "--skip-review",
         help="Run login flow and check state, but skip interactive review. For automated verification.",
     ),
+    local: str = typer.Option(
+        None,
+        "--local",
+        "-l",
+        help="Path to a local flow YAML file to run instead of the default login flow.",
+    ),
+    clock: str = typer.Option(
+        None,
+        "--clock",
+        help="Set fake browser time (ISO format or offset like '-30d' for 30 days ago).",
+    ),
 ):
-    """
-    Review base/environment artifact for a simulator.
-
-    Opens the simulator in a browser for manual testing. After testing,
-    you can pass (→ env_approved) or reject (→ env_in_progress).
-
-    SPECIFYING SIMULATOR AND ARTIFACT:
-
-        -s <simulator>                      Use server's base_artifact_id
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -s <simulator>:<artifact-uuid>      Colon notation (same as above)
+    """Review base/environment artifact for a simulator.
 
-    EXAMPLES:
-
-        plato pm review base -s espocrm
-        plato pm review base -s espocrm -a e9c25ca5-1234-5678-9abc-def012345678
-        plato pm review base -s espocrm:e9c25ca5-1234-5678-9abc-def012345678
+    Creates an environment from the artifact, launches a browser for testing,
+    runs the login flow, and checks for database mutations. After testing,
+    choose pass (→ env_approved) or reject (→ env_in_progress).
 
     Requires simulator status: env_review_requested
+
+    Options:
+        -s, --simulator: Simulator name. Supports colon notation for artifact:
+            '-s sim' (uses server's base_artifact_id) or '-s sim:<uuid>'
+        -a, --artifact: Explicit artifact UUID to review. Overrides server's value.
+        --skip-review: Run automated checks without interactive review session.
     """
     api_key = require_api_key()
 
@@ -403,16 +388,87 @@ def review_base(
                 playwright = await async_playwright().start()
                 browser = await playwright.chromium.launch(headless=False)
 
-                try:
-                    login_result = await session.login(browser, dataset="base")
-                    page = list(login_result.pages.values())[0] if login_result.pages else None
-                    console.print("[green]✅ Logged into environment[/green]")
-                except Exception as e:
-                    console.print(f"[yellow]⚠️  Login error: {e}[/yellow]")
+                # Install fake clock if requested
+                fake_time = None
+                if clock:
+                    # Parse clock option: ISO format or offset like '-30d'
+                    if clock.startswith("-") and clock[-1] in "dhms":
+                        # Offset format: -30d, -1h, -30m, -60s
+                        unit = clock[-1]
+                        amount = int(clock[1:-1])
+                        if unit == "d":
+                            fake_time = datetime.now() - timedelta(days=amount)
+                        elif unit == "h":
+                            fake_time = datetime.now() - timedelta(hours=amount)
+                        elif unit == "m":
+                            fake_time = datetime.now() - timedelta(minutes=amount)
+                        elif unit == "s":
+                            fake_time = datetime.now() - timedelta(seconds=amount)
+                    else:
+                        # ISO format
+                        fake_time = datetime.fromisoformat(clock)
+
+                    console.print(f"[cyan]Setting fake browser time to:[/cyan] {fake_time.isoformat()}")
+
+                if local:
+                    # Use local flow file instead of default login
+                    local_path = Path(local)
+                    if not local_path.exists():
+                        console.print(f"[red]❌ Local flow file not found: {local}[/red]")
+                        raise typer.Exit(1)
+
+                    console.print(f"[cyan]Loading local flow from: {local}[/cyan]")
+                    with open(local_path) as f:
+                        flow_dict = yaml.safe_load(f)
+
+                    # Find login flow (or first flow if only one)
+                    flows = flow_dict.get("flows", [])
+                    if not flows:
+                        console.print("[red]❌ No flows found in flow file[/red]")
+                        raise typer.Exit(1)
+
+                    # Try to find 'login' flow, otherwise use first flow
+                    flow_data = next((f for f in flows if f.get("name") == "login"), flows[0])
+                    flow = Flow.model_validate(flow_data)
+                    console.print(f"[cyan]Running flow: {flow.name}[/cyan]")
+
+                    # Create page and navigate to public URL
                     page = await browser.new_page()
+
+                    # Install fake clock if requested
+                    if fake_time:
+                        await page.clock.install(time=fake_time)
+                        console.print(f"[green]✅ Fake clock installed: {fake_time.isoformat()}[/green]")
+
                     if public_url:
                         await page.goto(public_url)
 
+                    # Execute the flow
+                    try:
+                        executor = FlowExecutor(page, flow)
+                        await executor.execute()
+                        console.print("[green]✅ Local flow executed successfully[/green]")
+                    except Exception as e:
+                        console.print(f"[yellow]⚠️  Flow execution error: {e}[/yellow]")
+                else:
+                    # Use default login via session.login()
+                    if fake_time:
+                        console.print("[yellow]⚠️  --clock with default login may not work correctly.[/yellow]")
+                        console.print("[yellow]   Use --local with a flow file for reliable clock testing.[/yellow]")
+                    try:
+                        login_result = await session.login(browser, dataset="base")
+                        page = list(login_result.pages.values())[0] if login_result.pages else None
+                        console.print("[green]✅ Logged into environment[/green]")
+                    except Exception as e:
+                        console.print(f"[yellow]⚠️  Login error: {e}[/yellow]")
+                        page = await browser.new_page()
+                        # Install fake clock on fallback page
+                        if fake_time:
+                            await page.clock.install(time=fake_time)
+                            console.print(f"[green]✅ Fake clock installed: {fake_time.isoformat()}[/green]")
+                        if public_url:
+                            await page.goto(public_url)
+
                 # ALWAYS check state after login to verify no mutations
                 console.print("\n[cyan]Checking environment state after login...[/cyan]")
                 has_mutations = False
@@ -676,25 +732,18 @@ def review_data(
         help="Artifact UUID to review. If not provided, uses server's data_artifact_id.",
     ),
 ):
-    """
-    Launch browser with EnvGen Recorder extension for data review.
+    """Launch browser with EnvGen Recorder extension for data review.
 
     Opens Chrome with the EnvGen Recorder extension installed for reviewing
-    data artifacts. Close the browser when done.
-
-    SPECIFYING SIMULATOR AND ARTIFACT:
-
-        -s <simulator>                      Use server's data_artifact_id
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -s <simulator>:<artifact-uuid>      Colon notation (same as above)
-
-    EXAMPLES:
-
-        plato pm review data -s fathom
-        plato pm review data -s fathom -a e9c25ca5-1234-5678-9abc-def012345678
-        plato pm review data -s fathom:e9c25ca5-1234-5678-9abc-def012345678
+    data artifacts. The extension sidebar can be used to record and submit reviews.
+    Press Control-C to exit when done.
 
     Requires simulator status: data_review_requested
+
+    Options:
+        -s, --simulator: Simulator name. Supports colon notation for artifact:
+            '-s sim' (uses server's data_artifact_id) or '-s sim:<uuid>'
+        -a, --artifact: Explicit artifact UUID to review. Overrides server's value.
     """
     api_key = require_api_key()
 
@@ -924,27 +973,14 @@ def review_data(
 
 @submit_app.command(name="base")
 def submit_base():
-    """
-    Submit base/environment artifact for review after snapshot.
+    """Submit base/environment artifact for review after snapshot.
 
-    Reads simulator name and artifact ID from .sandbox.yaml (created by
-    plato sandbox start). Run this from the simulator directory after
-    creating a snapshot.
-
-    Transitions simulator from env_in_progress → env_review_requested.
-
-    USAGE:
-
-        plato pm submit base    # No args needed - reads from .sandbox.yaml
-
-    PREREQUISITES:
-
-        1. plato sandbox start --from-config
-        2. plato sandbox start-services
-        3. plato sandbox snapshot
-        4. plato pm submit base   ← you are here
+    Reads simulator name and artifact_id from .sandbox.yaml, syncs metadata from
+    plato-config.yml to the server, and transitions status to env_review_requested.
+    Run from the simulator directory after creating a snapshot.
 
     Requires simulator status: env_in_progress
+    No arguments needed - reads everything from .sandbox.yaml and plato-config.yml.
     """
     api_key = require_api_key()
 
@@ -1091,22 +1127,17 @@ def submit_data(
         help="Artifact UUID to submit for data review (required).",
     ),
 ):
-    """
-    Submit data artifact for review after data generation.
+    """Submit data artifact for review after data generation.
 
-    Transitions simulator from data_in_progress → data_review_requested.
-
-    SPECIFYING SIMULATOR AND ARTIFACT (both required):
-
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -s <simulator>:<artifact-uuid>      Colon notation (same as above)
-
-    EXAMPLES:
-
-        plato pm submit data -s espocrm -a e9c25ca5-1234-5678-9abc-def012345678
-        plato pm submit data -s espocrm:e9c25ca5-1234-5678-9abc-def012345678
+    Transitions simulator from data_in_progress → data_review_requested and
+    tags the artifact as 'data-pending-review'.
 
     Requires simulator status: data_in_progress
+
+    Options:
+        -s, --simulator: Simulator name. Supports colon notation:
+            '-s sim:<uuid>' or use separate -a flag
+        -a, --artifact: Artifact UUID to submit (required)
     """
     api_key = require_api_key()