plato-sdk-v2 2.7.9__tar.gz → 2.8.1__tar.gz

{plato_sdk_v2-2.7.9 → plato_sdk_v2-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plato-sdk-v2
-Version: 2.7.9
+Version: 2.8.1
 Summary: Python SDK for the Plato API
 Author-email: Plato <support@plato.so>
 License-Expression: MIT

plato_sdk_v2-2.8.1/VERSION

@@ -0,0 +1 @@
+2.8.1

{plato_sdk_v2-2.7.9 → plato_sdk_v2-2.8.1}/plato/cli/sandbox.py

@@ -747,6 +747,9 @@ def sandbox_ssh(
 
     Uses .plato/ssh_config from 'start'. Extra args after -- are passed to ssh.
 
+    NOTE FOR AGENTS: Do not use this command. Instead, use the raw SSH command
+    from 'plato sandbox status' which shows: ssh -F .plato/ssh_config sandbox
+
     Examples:
         plato sandbox ssh
         plato sandbox ssh -- -L 8080:localhost:8080
@@ -781,6 +784,9 @@ def sandbox_tunnel(
 
     Creates a TCP tunnel through the TLS gateway. Useful for database access.
 
+    NOTE FOR AGENTS: Do not use this command. Use raw SSH port forwarding instead:
+    ssh -F .plato/ssh_config sandbox -L <local_port>:127.0.0.1:<remote_port>
+
     Examples:
         plato sandbox tunnel 5432              # Forward PostgreSQL
         plato sandbox tunnel 3306              # Forward MySQL

{plato_sdk_v2-2.7.9 → plato_sdk_v2-2.8.1}/plato/v2/async_/session.py

@@ -23,6 +23,8 @@ 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.jobs import wait_for_ready as jobs_wait_for_ready
+from plato._generated.api.v2.sessions import add_job as sessions_add_job
 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
@@ -31,6 +33,7 @@ from plato._generated.api.v2.sessions import execute as sessions_execute
 from plato._generated.api.v2.sessions import get_public_url as sessions_get_public_url
 from plato._generated.api.v2.sessions import heartbeat as sessions_heartbeat
 from plato._generated.api.v2.sessions import make as sessions_make
+from plato._generated.api.v2.sessions import remove_job as sessions_remove_job
 from plato._generated.api.v2.sessions import reset as sessions_reset
 from plato._generated.api.v2.sessions import set_date as sessions_set_date
 from plato._generated.api.v2.sessions import setup_sandbox as sessions_setup_sandbox
@@ -39,6 +42,7 @@ from plato._generated.api.v2.sessions import snapshot_store as sessions_snapshot
 from plato._generated.api.v2.sessions import state as sessions_state
 from plato._generated.api.v2.sessions import wait_for_ready as sessions_wait_for_ready
 from plato._generated.models import (
+    AddJobRequest,
     AppApiV2SchemasSessionCreateSnapshotRequest,
     AppApiV2SchemasSessionCreateSnapshotResponse,
     AppApiV2SchemasSessionEvaluateResponse,
@@ -49,10 +53,12 @@ from plato._generated.models import (
     CreateDiskSnapshotResponse,
     CreateSessionFromEnvs,
     CreateSessionFromTask,
+    EnvironmentContext,
     Envs,
     ExecuteCommandRequest,
     ExecuteCommandResponse,
     Flow,
+    RemoveJobRequest,
     ResetSessionRequest,
     ResetSessionResponse,
     RunSessionSource,
@@ -780,6 +786,158 @@ class Session:
 
         return result
 
+    async def add_env(
+        self,
+        env: EnvFromSimulator | EnvFromArtifact | EnvFromResource,
+        *,
+        timeout: int = 1800,
+        heartbeat_timeout: int | None = None,
+        wait_for_ready: bool = True,
+    ) -> Environment:
+        """Add a new environment to this session.
+
+        The new environment will:
+        1. Become part of the session's job group
+        2. Be matched to an available VM via the resource matcher
+        3. Automatically join the session's WireGuard network if one exists
+
+        Args:
+            env: Environment configuration (from Env.simulator(), Env.artifact(), or Env.resource()).
+            timeout: VM timeout in seconds (default: 1800).
+            heartbeat_timeout: Per-VM heartbeat timeout. None=use default (300s), 0=disabled.
+            wait_for_ready: If True, wait for the job to be ready before returning (default: True).
+
+        Returns:
+            Environment object for the new job.
+
+        Raises:
+            RuntimeError: If session is closed or job creation fails.
+            TimeoutError: If wait_for_ready=True and the job doesn't become ready within timeout.
+        """
+        self._check_closed()
+
+        # Auto-generate alias if not set
+        if env.alias is None:
+            existing_aliases = {e.alias for e in self.envs}
+            unique_alias = f"env-{uuid.uuid4().hex[:8]}"
+            while unique_alias in existing_aliases:
+                unique_alias = f"env-{uuid.uuid4().hex[:8]}"
+            env.alias = unique_alias
+
+        # Build request
+        request = AddJobRequest(
+            env=env,
+            timeout=timeout,
+            heartbeat_timeout=heartbeat_timeout,
+        )
+
+        # Call the add_job API
+        response = await sessions_add_job.asyncio(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
+        # Check for failures
+        if not response.env.success:
+            raise RuntimeError(f"Failed to add job: {response.env.error}")
+
+        if not response.env.job_id:
+            raise RuntimeError("Backend did not return job_id for new environment")
+
+        job_id = response.env.job_id
+
+        # Wait for the job to be ready if requested
+        if wait_for_ready:
+            ready_response = await jobs_wait_for_ready.asyncio(
+                client=self._http,
+                job_id=job_id,
+                timeout=timeout,
+                x_api_key=self._api_key,
+            )
+
+            if not ready_response.ready:
+                error = ready_response.error or "Unknown error"
+                raise TimeoutError(f"Job {job_id} did not become ready: {error}")
+
+        # Update internal context with the new environment
+        new_env_context = EnvironmentContext(
+            job_id=job_id,
+            alias=env.alias,
+            artifact_id=response.env.artifact_id,
+            simulator=getattr(env, "simulator", None),
+        )
+
+        # Add to context's envs list
+        if self._context.envs is None:
+            self._context.envs = []
+        self._context.envs.append(new_env_context)
+
+        # Reset cached envs to force rebuild
+        self._envs = None
+
+        # Create and return the Environment object
+        new_environment = Environment(
+            session=self,
+            job_id=job_id,
+            alias=env.alias,
+            artifact_id=response.env.artifact_id,
+        )
+
+        logger.info(f"Added job {job_id} (alias={env.alias}) to session {self.session_id}")
+        return new_environment
+
+    async def remove_env(self, env: Environment | str) -> None:
+        """Remove an environment from this session.
+
+        This will:
+        1. Remove the job from the session's network (if connected)
+        2. Shut down the VM associated with the job
+        3. Cancel the job in the system
+
+        Args:
+            env: Environment object or alias string to remove.
+
+        Raises:
+            RuntimeError: If session is closed or removal fails.
+            ValueError: If environment not found in session.
+        """
+        self._check_closed()
+
+        # Resolve to job_id
+        if isinstance(env, str):
+            # Find by alias
+            found_env = self.get_env(env)
+            if not found_env:
+                raise ValueError(f"Environment with alias '{env}' not found in session")
+            job_id = found_env.job_id
+            alias = env
+        else:
+            job_id = env.job_id
+            alias = env.alias
+
+        # Call the remove_job API
+        request = RemoveJobRequest(job_id=job_id)
+        response = await sessions_remove_job.asyncio(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
+        if not response.success:
+            raise RuntimeError(f"Failed to remove job {job_id}")
+
+        # Update internal context - remove the environment
+        if self._context.envs:
+            self._context.envs = [e for e in self._context.envs if e.job_id != job_id]
+
+        # Reset cached envs to force rebuild
+        self._envs = None
+
+        logger.info(f"Removed job {job_id} (alias={alias}) from session {self.session_id}")
+
     async def cleanup_databases(self) -> SessionCleanupResult:
         """Clean up database audit logs for all environments.
 

{plato_sdk_v2-2.7.9 → plato_sdk_v2-2.8.1}/plato/v2/sync/session.py

@@ -22,6 +22,8 @@ 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.jobs import wait_for_ready as jobs_wait_for_ready
+from plato._generated.api.v2.sessions import add_job as sessions_add_job
 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
@@ -29,6 +31,7 @@ from plato._generated.api.v2.sessions import evaluate as sessions_evaluate
 from plato._generated.api.v2.sessions import execute as sessions_execute
 from plato._generated.api.v2.sessions import heartbeat as sessions_heartbeat
 from plato._generated.api.v2.sessions import make as sessions_make
+from plato._generated.api.v2.sessions import remove_job as sessions_remove_job
 from plato._generated.api.v2.sessions import reset as sessions_reset
 from plato._generated.api.v2.sessions import set_date as sessions_set_date
 from plato._generated.api.v2.sessions import setup_sandbox as sessions_setup_sandbox
@@ -37,6 +40,7 @@ from plato._generated.api.v2.sessions import snapshot_store as sessions_snapshot
 from plato._generated.api.v2.sessions import state as sessions_state
 from plato._generated.api.v2.sessions import wait_for_ready as sessions_wait_for_ready
 from plato._generated.models import (
+    AddJobRequest,
     AppApiV2SchemasSessionCreateSnapshotRequest,
     AppApiV2SchemasSessionCreateSnapshotResponse,
     AppApiV2SchemasSessionEvaluateResponse,
@@ -47,10 +51,12 @@ from plato._generated.models import (
     CreateDiskSnapshotResponse,
     CreateSessionFromEnvs,
     CreateSessionFromTask,
+    EnvironmentContext,
     Envs,
     ExecuteCommandRequest,
     ExecuteCommandResponse,
     Flow,
+    RemoveJobRequest,
     ResetSessionRequest,
     ResetSessionResponse,
     RunSessionSource,
@@ -690,6 +696,158 @@ class Session:
 
         return result
 
+    def add_env(
+        self,
+        env: EnvFromSimulator | EnvFromArtifact | EnvFromResource,
+        *,
+        timeout: int = 1800,
+        heartbeat_timeout: int | None = None,
+        wait_for_ready: bool = True,
+    ) -> Environment:
+        """Add a new environment to this session.
+
+        The new environment will:
+        1. Become part of the session's job group
+        2. Be matched to an available VM via the resource matcher
+        3. Automatically join the session's WireGuard network if one exists
+
+        Args:
+            env: Environment configuration (from Env.simulator(), Env.artifact(), or Env.resource()).
+            timeout: VM timeout in seconds (default: 1800).
+            heartbeat_timeout: Per-VM heartbeat timeout. None=use default (300s), 0=disabled.
+            wait_for_ready: If True, wait for the job to be ready before returning (default: True).
+
+        Returns:
+            Environment object for the new job.
+
+        Raises:
+            RuntimeError: If session is closed or job creation fails.
+            TimeoutError: If wait_for_ready=True and the job doesn't become ready within timeout.
+        """
+        self._check_closed()
+
+        # Auto-generate alias if not set
+        if env.alias is None:
+            existing_aliases = {e.alias for e in self.envs}
+            unique_alias = f"env-{uuid.uuid4().hex[:8]}"
+            while unique_alias in existing_aliases:
+                unique_alias = f"env-{uuid.uuid4().hex[:8]}"
+            env.alias = unique_alias
+
+        # Build request
+        request = AddJobRequest(
+            env=env,
+            timeout=timeout,
+            heartbeat_timeout=heartbeat_timeout,
+        )
+
+        # Call the add_job API
+        response = sessions_add_job.sync(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
+        # Check for failures
+        if not response.env.success:
+            raise RuntimeError(f"Failed to add job: {response.env.error}")
+
+        if not response.env.job_id:
+            raise RuntimeError("Backend did not return job_id for new environment")
+
+        job_id = response.env.job_id
+
+        # Wait for the job to be ready if requested
+        if wait_for_ready:
+            ready_response = jobs_wait_for_ready.sync(
+                client=self._http,
+                job_id=job_id,
+                timeout=timeout,
+                x_api_key=self._api_key,
+            )
+
+            if not ready_response.ready:
+                error = ready_response.error or "Unknown error"
+                raise TimeoutError(f"Job {job_id} did not become ready: {error}")
+
+        # Update internal context with the new environment
+        new_env_context = EnvironmentContext(
+            job_id=job_id,
+            alias=env.alias,
+            artifact_id=response.env.artifact_id,
+            simulator=getattr(env, "simulator", None),
+        )
+
+        # Add to context's envs list
+        if self._context.envs is None:
+            self._context.envs = []
+        self._context.envs.append(new_env_context)
+
+        # Reset cached envs to force rebuild
+        self._envs = None
+
+        # Create and return the Environment object
+        new_environment = Environment(
+            session=self,
+            job_id=job_id,
+            alias=env.alias,
+            artifact_id=response.env.artifact_id,
+        )
+
+        logger.info(f"Added job {job_id} (alias={env.alias}) to session {self.session_id}")
+        return new_environment
+
+    def remove_env(self, env: Environment | str) -> None:
+        """Remove an environment from this session.
+
+        This will:
+        1. Remove the job from the session's network (if connected)
+        2. Shut down the VM associated with the job
+        3. Cancel the job in the system
+
+        Args:
+            env: Environment object or alias string to remove.
+
+        Raises:
+            RuntimeError: If session is closed or removal fails.
+            ValueError: If environment not found in session.
+        """
+        self._check_closed()
+
+        # Resolve to job_id
+        if isinstance(env, str):
+            # Find by alias
+            found_env = self.get_env(env)
+            if not found_env:
+                raise ValueError(f"Environment with alias '{env}' not found in session")
+            job_id = found_env.job_id
+            alias = env
+        else:
+            job_id = env.job_id
+            alias = env.alias
+
+        # Call the remove_job API
+        request = RemoveJobRequest(job_id=job_id)
+        response = sessions_remove_job.sync(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
+        if not response.success:
+            raise RuntimeError(f"Failed to remove job {job_id}")
+
+        # Update internal context - remove the environment
+        if self._context.envs:
+            self._context.envs = [e for e in self._context.envs if e.job_id != job_id]
+
+        # Reset cached envs to force rebuild
+        self._envs = None
+
+        logger.info(f"Removed job {job_id} (alias={alias}) from session {self.session_id}")
+
     def login(
         self,
         browser: Browser,

plato_sdk_v2-2.7.9/VERSION

@@ -1 +0,0 @@
-2.7.9