plato-sdk-v2 2.6.1__py3-none-any.whl → 2.7.0__py3-none-any.whl

plato/v1/cli/ssh.py

@@ -1,8 +1,5 @@
-"""SSH utilities for Plato CLI - replicates Go hub behavior."""
+"""SSH utilities for Plato CLI."""
 
-import os
-import random
-import shutil
 from pathlib import Path
 
 from cryptography.hazmat.primitives import serialization
@@ -21,37 +18,22 @@ def get_plato_dir(working_dir: Path | str | None = None) -> Path:
     return Path.home() / ".plato"
 
 
-def get_next_sandbox_number(working_dir: Path | str | None = None) -> int:
-    """Find next available sandbox number by checking existing config files."""
-    plato_dir = get_plato_dir(working_dir)
-    if not plato_dir.exists():
-        return 1
-
-    max_num = 0
-    for file in plato_dir.iterdir():
-        if file.name.startswith("ssh_") and file.name.endswith(".conf"):
-            # Extract number from ssh_N.conf
-            try:
-                num_str = file.name[4:-5]  # Remove "ssh_" prefix and ".conf" suffix
-                num = int(num_str)
-                if num > max_num:
-                    max_num = num
-            except ValueError:
-                continue
-    return max_num + 1
-
-
-def generate_ssh_key_pair(sandbox_num: int, working_dir: Path | str | None = None) -> tuple[str, str]:
+def generate_ssh_key_pair(identifier: str, working_dir: Path | str | None = None) -> tuple[str, str]:
     """
-    Generate a new ed25519 SSH key pair for a specific sandbox.
+    Generate a new ed25519 SSH key pair.
+
+    Args:
+        identifier: A unique identifier for naming the key files (e.g., session_id prefix)
+        working_dir: Optional working directory for the .plato folder
 
-    Returns (public_key_str, private_key_path).
+    Returns:
+        Tuple of (public_key_str, private_key_path)
     """
     plato_dir = get_plato_dir(working_dir)
     plato_dir.mkdir(mode=0o700, exist_ok=True)
 
-    private_key_path = plato_dir / f"ssh_{sandbox_num}_key"
-    public_key_path = plato_dir / f"ssh_{sandbox_num}_key.pub"
+    private_key_path = plato_dir / f"ssh_{identifier}_key"
+    public_key_path = plato_dir / f"ssh_{identifier}_key.pub"
 
     # Remove existing keys if they exist
     private_key_path.unlink(missing_ok=True)
@@ -75,7 +57,7 @@ def generate_ssh_key_pair(sandbox_num: int, working_dir: Path | str | None = Non
     )
 
     # Add comment to public key
-    comment = f"plato-sandbox-{sandbox_num}"
+    comment = f"plato-sandbox-{identifier}"
     public_key_str = f"{public_key_bytes.decode('utf-8')} {comment}"
 
     # Write private key with 0600 permissions
@@ -87,140 +69,3 @@ def generate_ssh_key_pair(sandbox_num: int, working_dir: Path | str | None = Non
     public_key_path.chmod(0o644)
 
     return public_key_str, str(private_key_path)
-
-
-def get_proxy_config(base_url: str) -> tuple[str, bool]:
-    """
-    Get proxy server configuration based on base URL.
-
-    Returns (proxy_server, is_secure).
-    """
-    # Match Go hub's GetProxyConfig behavior
-    if "localhost" in base_url:
-        return "proxy.localhost:9000", False
-    elif "staging" in base_url:
-        return "staging.proxy.plato.so:9000", True
-    else:
-        # Default to production
-        return "proxy.plato.so:9000", True
-
-
-def find_proxytunnel() -> str | None:
-    """Find proxytunnel binary - checks bundled location first, then PATH."""
-    # Check bundled location - go up from cli/ to v1/
-    package_dir = Path(__file__).resolve().parent.parent
-    bin_dir = package_dir / "bin"
-    bundled_path = bin_dir / "proxytunnel"
-    if bundled_path.exists() and os.access(bundled_path, os.X_OK):
-        return str(bundled_path)
-
-    # Check plato-client/cli/bin for development
-    plato_client_dir = package_dir.parent.parent.parent
-    dev_path = plato_client_dir / "cli" / "bin" / "proxytunnel"
-    if dev_path.exists() and os.access(dev_path, os.X_OK):
-        return str(dev_path)
-
-    # Check PATH
-    which_result = shutil.which("proxytunnel")
-    if which_result:
-        return which_result
-
-    return None
-
-
-def create_ssh_config(
-    base_url: str,
-    hostname: str,
-    local_port: int,
-    job_public_id: str,
-    username: str,
-    private_key_path: str,
-    sandbox_num: int,
-    working_dir: Path | str | None = None,
-) -> str:
-    """
-    Create a temporary SSH config file for a specific sandbox.
-
-    Returns the path to the config file.
-    """
-    proxytunnel_path = find_proxytunnel()
-    if not proxytunnel_path:
-        raise RuntimeError(
-            "proxytunnel not found. Install it with: brew install proxytunnel (macOS) "
-            "or apt-get install proxytunnel (Linux)"
-        )
-
-    proxy_server, is_secure = get_proxy_config(base_url)
-
-    # Build ProxyCommand
-    proxy_cmd = proxytunnel_path
-    if is_secure:
-        proxy_cmd += " -E"
-    proxy_cmd += f" -p {proxy_server} -P '{job_public_id}@22:newpass' -d %h:%p --no-check-certificate"
-
-    config_content = f"""Host {hostname}
-    HostName localhost
-    Port {local_port}
-    User {username}
-    IdentityFile {private_key_path}
-    IdentitiesOnly yes
-    StrictHostKeyChecking no
-    UserKnownHostsFile /dev/null
-    ConnectTimeout 10
-    ProxyCommand {proxy_cmd}
-    ServerAliveInterval 30
-    ServerAliveCountMax 3
-    TCPKeepAlive yes
-"""
-
-    plato_dir = get_plato_dir(working_dir)
-    plato_dir.mkdir(mode=0o700, exist_ok=True)
-
-    config_path = plato_dir / f"ssh_{sandbox_num}.conf"
-    config_path.write_text(config_content)
-    config_path.chmod(0o600)
-
-    return str(config_path)
-
-
-def setup_ssh_for_sandbox(
-    base_url: str,
-    job_public_id: str,
-    username: str = "plato",
-    working_dir: Path | str | None = None,
-) -> dict:
-    """
-    Set up SSH access for a sandbox - generates keys and creates config.
-
-    This replicates the Go hub's SetupSSHConfig function.
-
-    Returns dict with: ssh_host, config_path, public_key, private_key_path
-    """
-    sandbox_num = get_next_sandbox_number(working_dir)
-    ssh_host = f"sandbox-{sandbox_num}"
-
-    # Choose random port between 2200 and 2299
-    local_port = random.randint(2200, 2299)
-
-    # Generate SSH key pair
-    public_key, private_key_path = generate_ssh_key_pair(sandbox_num, working_dir)
-
-    # Create SSH config file
-    config_path = create_ssh_config(
-        base_url=base_url,
-        hostname=ssh_host,
-        local_port=local_port,
-        job_public_id=job_public_id,
-        username=username,
-        private_key_path=private_key_path,
-        sandbox_num=sandbox_num,
-        working_dir=working_dir,
-    )
-
-    return {
-        "ssh_host": ssh_host,
-        "config_path": config_path,
-        "public_key": public_key,
-        "private_key_path": private_key_path,
-        "sandbox_num": sandbox_num,
-    }

plato/v1/cli/verify.py

@@ -49,11 +49,13 @@ sandbox_verify_app = typer.Typer(help="Verify sandbox setup and state")
 
 @sandbox_verify_app.callback(invoke_without_command=True)
 def sandbox_verify_default(ctx: typer.Context):
-    """
-    Verify sandbox is properly configured.
+    """Verify sandbox is properly configured.
+
+    Checks that .sandbox.yaml exists and contains all required fields (job_id,
+    session_id, public_url, plato_config_path, service). Also verifies that the
+    plato_config_path file exists.
 
-    Exit 0 if .sandbox.yaml has all required fields.
-    Exit 1 with stderr describing missing fields.
+    Exit code 0 = verification passed, exit code 1 = verification failed with error on stderr.
     """
     if ctx.invoked_subcommand is not None:
         return
@@ -92,11 +94,12 @@ def sandbox_verify_default(ctx: typer.Context):
 
 @sandbox_verify_app.command(name="services")
 def verify_services():
-    """
-    Verify containers are running and public URL returns 200.
+    """Verify containers are running and public URL returns 200.
+
+    Checks container health via SSH (docker ps) and makes an HTTP HEAD request to
+    the public URL. Reports unhealthy/exited/dead containers and HTTP errors.
 
-    Exit 0 if all containers healthy and URL accessible.
-    Exit 1 with stderr describing the issue (e.g., "HTTP 502 - check nginx config").
+    Exit code 0 = all healthy, exit code 1 = issues found with error on stderr.
     """
     if not Path(SANDBOX_FILE).exists():
         _fail(f"File not found: {SANDBOX_FILE}")
@@ -174,11 +177,12 @@ def verify_services():
 
 @sandbox_verify_app.command(name="login")
 def verify_login():
-    """
-    Verify login page is accessible.
+    """Verify login page is accessible.
+
+    Makes an HTTP GET request to the public URL from .sandbox.yaml and verifies
+    it returns HTTP 200.
 
-    Exit 0 if public URL returns 200.
-    Exit 1 if not accessible.
+    Exit code 0 = accessible, exit code 1 = not accessible with error on stderr.
     """
     if not Path(SANDBOX_FILE).exists():
         _fail(f"File not found: {SANDBOX_FILE}")
@@ -210,11 +214,12 @@ def verify_login():
 
 @sandbox_verify_app.command(name="worker")
 def verify_worker():
-    """
-    Verify Plato worker is connected and audit triggers installed.
+    """Verify Plato worker is connected and audit triggers installed.
+
+    Calls the state API and checks that the worker responds without errors.
+    A 502 error indicates the worker is not running.
 
-    Exit 0 if worker connected.
-    Exit 1 with stderr describing the issue.
+    Exit code 0 = worker connected, exit code 1 = worker not connected.
     """
     if not Path(SANDBOX_FILE).exists():
         _fail(f"File not found: {SANDBOX_FILE}")
@@ -274,11 +279,12 @@ def verify_worker():
 
 @sandbox_verify_app.command(name="audit-clear")
 def verify_audit_clear():
-    """
-    Verify audit log is cleared (0 mutations).
+    """Verify audit log is cleared (0 mutations).
+
+    Checks the state API to confirm no mutations are recorded. Use after
+    'plato sandbox clear-audit' to verify the audit tables were truncated.
 
-    Exit 0 if 0 mutations.
-    Exit 1 if mutations exist.
+    Exit code 0 = no mutations, exit code 1 = mutations exist.
     """
     if not Path(SANDBOX_FILE).exists():
         _fail(f"File not found: {SANDBOX_FILE}")
@@ -323,11 +329,12 @@ def verify_audit_clear():
 
 @sandbox_verify_app.command(name="flow")
 def verify_flow():
-    """
-    Verify login flow exists and is valid.
+    """Verify login flow exists and is valid.
+
+    Checks that flows.yml (or base/flows.yml) exists and contains a valid 'login'
+    flow definition with required fields (name, steps, etc.).
 
-    Exit 0 if flows.yml exists with login section.
-    Exit 1 if missing or invalid.
+    Exit code 0 = valid flow found, exit code 1 = missing or invalid.
     """
     flow_paths = ["flows.yml", "base/flows.yml", "login-flow.yml"]
     flow_file = None
@@ -360,11 +367,12 @@ def verify_flow():
 
 @sandbox_verify_app.command(name="mutations")
 def verify_mutations():
-    """
-    Verify no mutations after login flow.
+    """Verify no mutations after login flow.
+
+    Checks the state API to confirm no database mutations were recorded. Should
+    be run after executing the login flow to verify it doesn't cause mutations.
 
-    Exit 0 if 0 mutations.
-    Exit 1 with stderr listing tables and counts.
+    Exit code 0 = no mutations, exit code 1 = mutations found (lists tables and counts).
     """
     if not Path(SANDBOX_FILE).exists():
         _fail(f"File not found: {SANDBOX_FILE}")
@@ -422,10 +430,10 @@ def verify_mutations():
 
 @sandbox_verify_app.command(name="audit-active")
 def verify_audit_active():
-    """
-    Verify audit system is tracking changes.
+    """Verify audit system is tracking changes.
 
-    This is a manual verification step. Always exits 0.
+    This is a manual verification step that requires making a change in the app
+    and confirming mutations appear. Always exits 0 - actual verification is manual.
     """
     # This step requires manual verification - just pass
     pass
@@ -433,11 +441,12 @@ def verify_audit_active():
 
 @sandbox_verify_app.command(name="snapshot")
 def verify_snapshot():
-    """
-    Verify snapshot was created.
+    """Verify snapshot was created.
+
+    Checks that .sandbox.yaml contains an artifact_id field, which is set by
+    'plato sandbox snapshot' after successfully creating a snapshot.
 
-    Exit 0 if artifact_id exists in .sandbox.yaml.
-    Exit 1 if missing.
+    Exit code 0 = artifact_id present, exit code 1 = missing.
     """
     if not Path(SANDBOX_FILE).exists():
         _fail(f"File not found: {SANDBOX_FILE}")
@@ -470,11 +479,12 @@ pm_verify_app = typer.Typer(help="Verify review and submit steps")
 
 @pm_verify_app.command(name="review")
 def verify_review():
-    """
-    Verify review prerequisites.
+    """Verify review prerequisites.
+
+    Checks all prerequisites for submitting a simulator for review: PLATO_API_KEY set,
+    .sandbox.yaml exists with artifact_id, and flows.yml has a login flow.
 
-    Exit 0 if ready for review.
-    Exit 1 if missing prerequisites.
+    Exit code 0 = ready for review, exit code 1 = missing prerequisites.
     """
     issues = []
 
@@ -506,11 +516,12 @@ def verify_review():
 
 @pm_verify_app.command(name="submit")
 def verify_submit():
-    """
-    Verify submit prerequisites.
+    """Verify submit prerequisites.
+
+    Checks all prerequisites for submission: PLATO_API_KEY set and .sandbox.yaml
+    exists with artifact_id.
 
-    Exit 0 if ready to submit.
-    Exit 1 if missing prerequisites.
+    Exit code 0 = ready to submit, exit code 1 = missing prerequisites.
     """
     issues = []
 
@@ -543,11 +554,15 @@ def verify_submit():
 def verify_research(
     report_path: str = typer.Option("research-report.yml", "--report", "-r"),
 ):
-    """
-    Verify research report is complete.
+    """Verify research report is complete.
+
+    Checks that the research report YAML file contains all required fields:
+    app_name, source, database.type, docker, and credentials.
 
-    Exit 0 if all required fields present.
-    Exit 1 with stderr listing missing fields.
+    Options:
+        -r, --report: Path to research report file (default: research-report.yml)
+
+    Exit code 0 = complete, exit code 1 = missing required fields.
     """
     if not Path(report_path).exists():
         _fail(f"Research report not found: {report_path}")
@@ -587,11 +602,15 @@ def verify_research(
 def verify_validation(
     report_path: str = typer.Option("research-report.yml", "--report", "-r"),
 ):
-    """
-    Verify app can become a simulator.
+    """Verify app can become a simulator.
+
+    Checks that the research report indicates a supported database type
+    (postgresql, mysql, mariadb, sqlite) and has no blocking issues.
+
+    Options:
+        -r, --report: Path to research report file (default: research-report.yml)
 
-    Exit 0 if database type supported and no blockers.
-    Exit 1 with stderr describing blocker.
+    Exit code 0 = can become simulator, exit code 1 = has blockers.
     """
     if not Path(report_path).exists():
         _fail(f"Research report not found: {report_path}")
@@ -622,11 +641,16 @@ def verify_config(
     config_path: str = typer.Option("plato-config.yml", "--config", "-c"),
     compose_path: str = typer.Option("base/docker-compose.yml", "--compose"),
 ):
-    """
-    Verify configuration files are valid.
+    """Verify configuration files are valid.
+
+    Checks that plato-config.yml and docker-compose.yml exist and contain valid
+    YAML. Validates required fields in plato-config.yml (service, datasets, etc.).
+
+    Options:
+        -c, --config: Path to plato-config.yml (default: plato-config.yml)
+        --compose: Path to docker-compose.yml (default: base/docker-compose.yml)
 
-    Exit 0 if plato-config.yml and docker-compose.yml are valid.
-    Exit 1 with stderr describing issues.
+    Exit code 0 = valid, exit code 1 = issues found.
     """
     issues = []
 

plato/v1/cli/world.py

@@ -67,22 +67,23 @@ def world_publish(
     path: str = typer.Argument(".", help="Path to the world package directory (default: current directory)"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Build without uploading"),
 ):
-    """
-    Build and publish a world package to the Plato worlds repository.
+    """Build and publish a world package to the Plato worlds repository.
+
+    Reads pyproject.toml for package info, builds with 'uv build', extracts the
+    config schema from schema.json in the wheel, and uploads to the Plato worlds
+    repository via uv publish.
 
-    Reads pyproject.toml for package info, builds with 'uv build',
-    extracts config schema from schema.json in the wheel, and uploads
-    to the Plato worlds repository.
+    The schema.json is automatically generated during build by a hatch build hook
+    that calls the world's get_schema() method.
 
-    The schema.json is automatically generated during build by a hatch
-    build hook that calls the world's get_schema() method.
+    Arguments:
+        path: Path to the world package directory containing pyproject.toml
+            (default: current directory)
 
-    Requires PLATO_API_KEY environment variable.
+    Options:
+        --dry-run: Build the package and show schema without uploading
 
-    Example:
-        plato world publish
-        plato world publish ./my-world-package
-        plato world publish --dry-run
+    Requires PLATO_API_KEY environment variable for upload.
     """
     try:
         import tomli

plato/v2/async_/client.py

@@ -31,6 +31,7 @@ class AsyncSessionManager:
         task: str | None = None,
         timeout: int = 1800,
         agent_artifact_id: str | None = None,
+        connect_network: bool = True,
     ) -> Session:
         """Create a new session.
 
@@ -41,6 +42,7 @@ class AsyncSessionManager:
             task: Task public ID to create session from
             timeout: VM timeout in seconds
             agent_artifact_id: Optional agent artifact ID to associate with the session
+            connect_network: If True, automatically connect all VMs to a WireGuard network
 
         Returns:
             A new Session instance with all environments ready
@@ -59,19 +61,22 @@ class AsyncSessionManager:
             >>>
             >>> # From task
             >>> session = await plato.sessions.create(task="abc123")
+            >>>
+            >>> # With networking enabled automatically
+            >>> session = await plato.sessions.create(envs=[...], connect_network=True)
         """
         if envs is not None and task is not None:
             raise ValueError("Cannot specify both envs and task")
 
         if task is not None:
-            return await Session.from_task(
+            session = await Session.from_task(
                 http_client=self._http,
                 api_key=self._api_key,
                 task_id=task,
                 timeout=timeout,
             )
         elif envs is not None:
-            return await Session.from_envs(
+            session = await Session.from_envs(
                 http_client=self._http,
                 api_key=self._api_key,
                 envs=envs,
@@ -81,6 +86,23 @@ class AsyncSessionManager:
         else:
             raise ValueError("Must specify either envs or task")
 
+        if connect_network:
+            try:
+                await session.connect_network()
+            except Exception:
+                # Clean up session if network connection fails
+                import logging
+
+                logging.getLogger(__name__).info(f"Network connection failed, closing session {session.session_id}")
+                try:
+                    await session.close()
+                    logging.getLogger(__name__).info(f"Session {session.session_id} closed")
+                except Exception as close_err:
+                    logging.getLogger(__name__).warning(f"Failed to close session: {close_err}")
+                raise
+
+        return session
+
 
 class AsyncPlato:
     """Asynchronous Plato client for v2 API.

plato/v2/async_/session.py

@@ -24,6 +24,7 @@ if TYPE_CHECKING:
 from plato._generated.api.v2.jobs import get_flows as jobs_get_flows
 from plato._generated.api.v2.jobs import public_url as jobs_public_url
 from plato._generated.api.v2.sessions import close as sessions_close
+from plato._generated.api.v2.sessions import connect_network as sessions_connect_network
 from plato._generated.api.v2.sessions import disk_snapshot as sessions_disk_snapshot
 from plato._generated.api.v2.sessions import evaluate as sessions_evaluate
 from plato._generated.api.v2.sessions import execute as sessions_execute
@@ -44,6 +45,7 @@ from plato._generated.models import (
     AppApiV2SchemasSessionHeartbeatResponse,
     AppApiV2SchemasSessionSetupSandboxRequest,
     AppApiV2SchemasSessionSetupSandboxResponse,
+    ConnectNetworkRequest,
     CreateDiskSnapshotRequest,
     CreateDiskSnapshotResponse,
     CreateSessionFromEnvs,
@@ -146,6 +148,15 @@ class Session:
         self._heartbeat_task: asyncio.Task | None = None
         self._heartbeat_interval = 30
         self._envs: list[Environment] | None = None
+        self._network_host_only: bool = False  # True if WireGuard not available (no VM-to-VM mesh)
+
+    @property
+    def network_host_only(self) -> bool:
+        """True if network is using host-only routing (WireGuard not available in VM).
+
+        When True, external SSH access works but VM-to-VM mesh networking does not.
+        """
+        return self._network_host_only
 
     @property
     def session_id(self) -> str:
@@ -751,6 +762,43 @@ class Session:
 
         return urls
 
+    async def connect_network(self, host_only: bool = False) -> dict:
+        """Connect all VMs in this session to a WireGuard network.
+
+        Creates a full mesh WireGuard network between all VMs in the session.
+        Must be called after all environments are ready. This method is idempotent -
+        calling it multiple times will not reconnect already-connected VMs.
+
+        Args:
+            host_only: If True, force WireGuard to run on the worker instead of
+                       inside the VM. Useful for VMs without WireGuard tools or
+                       for testing worker-side WireGuard.
+
+        Returns:
+            Dict with:
+                - success: bool - True if all VMs connected successfully
+                - session_id: str - The session ID
+                - subnet: str - The network subnet (e.g., "10.100.0.0/24")
+                - results: dict[str, bool] - Success status per job_id
+
+        Raises:
+            RuntimeError: If session is closed or network connection fails.
+        """
+        self._check_closed()
+
+        # Server returns 500 with error detail if network connection fails
+        result = await sessions_connect_network.asyncio(
+            client=self._http,
+            session_id=self.session_id,
+            body=ConnectNetworkRequest(host_only=host_only),
+            x_api_key=self._api_key,
+        )
+
+        # Track if any VMs are using host-only routing (no VM-to-VM mesh)
+        self._network_host_only = result.get("host_only", False)
+
+        return result
+
     async def cleanup_databases(self) -> SessionCleanupResult:
         """Clean up database audit logs for all environments.