plato-sdk-v2 2.7.8__py3-none-any.whl → 2.8.0__py3-none-any.whl

plato/_generated/__init__.py

@@ -1,4 +1,4 @@
-"""Plato API SDK - v0.47.0"""
+"""Plato API SDK - v0.48.2"""
 
 from . import api, errors, models
 from .client import AsyncClient, Client

plato/_generated/api/v2/sessions/__init__.py

@@ -23,6 +23,7 @@ from . import (
     list_sessions,
     log_job_mutation,
     make,
+    remove_job,
     reset,
     set_date,
     setup_sandbox,
@@ -37,6 +38,7 @@ __all__ = [
     "make",
     "list_jobs",
     "add_job",
+    "remove_job",
     "reset",
     "heartbeat",
     "connect_network",

plato/_generated/api/v2/sessions/remove_job.py

@@ -0,0 +1,89 @@
+"""Remove Job"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import RemoveJobRequest, RemoveJobResponse
+
+
+def _build_request_args(
+    session_id: str,
+    body: RemoveJobRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/v2/sessions/{session_id}/remove-job"
+
+    headers: dict[str, str] = {}
+    if authorization is not None:
+        headers["authorization"] = authorization
+    if x_api_key is not None:
+        headers["X-API-Key"] = x_api_key
+
+    return {
+        "method": "POST",
+        "url": url,
+        "json": body.model_dump(mode="json", exclude_none=True),
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    session_id: str,
+    body: RemoveJobRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> RemoveJobResponse:
+    """Remove a job from a 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
+
+    Use this to clean up individual jobs without closing the entire session."""
+
+    request_args = _build_request_args(
+        session_id=session_id,
+        body=body,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return RemoveJobResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    session_id: str,
+    body: RemoveJobRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> RemoveJobResponse:
+    """Remove a job from a 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
+
+    Use this to clean up individual jobs without closing the entire session."""
+
+    request_args = _build_request_args(
+        session_id=session_id,
+        body=body,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return RemoveJobResponse.model_validate(response.json())

plato/_generated/models/__init__.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
-#   filename:  tmpy5rfux2_.json
-#   timestamp: 2026-01-29T20:47:53+00:00
+#   filename:  tmp2hcn27e0.json
+#   timestamp: 2026-01-29T22:45:52+00:00
 
 from __future__ import annotations
 
@@ -1158,6 +1158,14 @@ class EnvFromArtifact(BaseModel):
     """
 
 
+class RootfsStorageBackend(Enum):
+    sparse_s3 = "sparse-s3"
+    blockdiff = "blockdiff"
+    blockdiff_checkpoint = "blockdiff_checkpoint"
+    blockdiff_disk = "blockdiff_disk"
+    snapshot_store = "snapshot-store"
+
+
 class EnvFromSimulator(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -1929,6 +1937,11 @@ class NodeSessionNetworkConfig(BaseModel):
     """
 
 
+class DefaultRootfsStorageBackend(Enum):
+    sparse_s3 = "sparse-s3"
+    snapshot_store = "snapshot-store"
+
+
 class NodeSnapshotStoreConfig(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -1977,9 +1990,12 @@ class NodeSnapshotStoreConfig(BaseModel):
     """
     Local storage root for snapshot-store data.
     """
-    dedup_rootfs: Annotated[bool | None, Field(title="Dedup Rootfs")] = False
+    default_rootfs_storage_backend: Annotated[
+        DefaultRootfsStorageBackend | None,
+        Field(title="Default Rootfs Storage Backend"),
+    ] = DefaultRootfsStorageBackend.sparse_s3
     """
-    Enable rootfs-level dedup via snapshot-store FUSE mount instead of file copy.
+    Default rootfs storage backend. 'sparse-s3' uses S3 archives, 'snapshot-store' uses FUSE-based dedup.
     """
 
 
@@ -2334,6 +2350,38 @@ class ReleaseStatus(Enum):
     failed = "failed"
 
 
+class RemoveJobRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    job_id: Annotated[str, Field(title="Job Id")]
+    """
+    Job ID to remove from the session
+    """
+
+
+class RemoveJobResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    session_id: Annotated[str, Field(title="Session Id")]
+    """
+    Session ID the job was removed from
+    """
+    job_id: Annotated[str, Field(title="Job Id")]
+    """
+    Job ID that was removed
+    """
+    success: Annotated[bool, Field(title="Success")]
+    """
+    Whether the removal was successful
+    """
+    message: Annotated[str | None, Field(title="Message")] = None
+    """
+    Status message or error details
+    """
+
+
 class RepositoryResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -4324,6 +4372,18 @@ class EnvFromResource(BaseModel):
     """
     Custom name for this environment
     """
+    docker_image_url: Annotated[str | None, Field(title="Docker Image Url")] = None
+    """
+    Custom Docker image URL (ECR). If not set, uses default from settings.
+    """
+    rootfs_storage_backend: Annotated[RootfsStorageBackend | None, Field(title="Rootfs Storage Backend")] = None
+    """
+    Storage backend for rootfs ('sparse-s3' or 'snapshot-store'). If not set, uses default.
+    """
+    upload_rootfs: Annotated[bool | None, Field(title="Upload Rootfs")] = True
+    """
+    Upload rootfs to S3/snapshot-store if not already cached. Set to False for one-off VMs.
+    """
 
 
 class ExecuteCommandResponse(BaseModel):

plato/chronos/api/agents/get_agent_versions.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import AgentVersionsResponse
+from plato.chronos.models import ChronosModelsAgentAgentVersionsResponse
 
 
 def _build_request_args(
@@ -32,7 +32,7 @@ def sync(
     client: httpx.Client,
     name: str,
     x_api_key: str | None = None,
-) -> AgentVersionsResponse:
+) -> ChronosModelsAgentAgentVersionsResponse:
     """Get all versions of an agent by name."""
 
     request_args = _build_request_args(
@@ -42,14 +42,14 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return AgentVersionsResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentVersionsResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     name: str,
     x_api_key: str | None = None,
-) -> AgentVersionsResponse:
+) -> ChronosModelsAgentAgentVersionsResponse:
     """Get all versions of an agent by name."""
 
     request_args = _build_request_args(
@@ -59,4 +59,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return AgentVersionsResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentVersionsResponse.model_validate(response.json())

plato/chronos/api/agents/list_agents.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import AgentListResponse
+from plato.chronos.models import ChronosModelsAgentAgentListResponse
 
 
 def _build_request_args(
@@ -30,7 +30,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     x_api_key: str | None = None,
-) -> AgentListResponse:
+) -> ChronosModelsAgentAgentListResponse:
     """List all agents for the org."""
 
     request_args = _build_request_args(
@@ -39,13 +39,13 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return AgentListResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentListResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     x_api_key: str | None = None,
-) -> AgentListResponse:
+) -> ChronosModelsAgentAgentListResponse:
     """List all agents for the org."""
 
     request_args = _build_request_args(
@@ -54,4 +54,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return AgentListResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentListResponse.model_validate(response.json())

plato/chronos/api/registry/get_agent_versions_api_registry_agents__agent_name__versions_get.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import ChronosApiRegistryAgentVersionsResponse
+from plato.chronos.models import AgentVersionsResponse
 
 
 def _build_request_args(
@@ -25,7 +25,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     agent_name: str,
-) -> ChronosApiRegistryAgentVersionsResponse:
+) -> AgentVersionsResponse:
     """Get versions for an agent from the registry."""
 
     request_args = _build_request_args(
@@ -34,13 +34,13 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentVersionsResponse.model_validate(response.json())
+    return AgentVersionsResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     agent_name: str,
-) -> ChronosApiRegistryAgentVersionsResponse:
+) -> AgentVersionsResponse:
     """Get versions for an agent from the registry."""
 
     request_args = _build_request_args(
@@ -49,4 +49,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentVersionsResponse.model_validate(response.json())
+    return AgentVersionsResponse.model_validate(response.json())

plato/chronos/api/registry/list_registry_agents_api_registry_agents_get.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import ChronosApiRegistryAgentListResponse
+from plato.chronos.models import AgentListResponse
 
 
 def _build_request_args() -> dict[str, Any]:
@@ -22,23 +22,23 @@ def _build_request_args() -> dict[str, Any]:
 
 def sync(
     client: httpx.Client,
-) -> ChronosApiRegistryAgentListResponse:
+) -> AgentListResponse:
     """List all agents from the registry with their ECR image URIs."""
 
     request_args = _build_request_args()
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentListResponse.model_validate(response.json())
+    return AgentListResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
-) -> ChronosApiRegistryAgentListResponse:
+) -> AgentListResponse:
     """List all agents from the registry with their ECR image URIs."""
 
     request_args = _build_request_args()
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentListResponse.model_validate(response.json())
+    return AgentListResponse.model_validate(response.json())

plato/chronos/models/__init__.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
-#   filename:  tmp9iosw1i3.json
-#   timestamp: 2026-01-29T20:31:32+00:00
+#   filename:  tmpi9d4hw2u.json
+#   timestamp: 2026-01-29T22:45:54+00:00
 
 from __future__ import annotations
 
@@ -30,6 +30,13 @@ class AgentInfo(BaseModel):
     image_uri: Annotated[str, Field(title="Image Uri")]
 
 
+class AgentListResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    agents: Annotated[list[AgentInfo], Field(title="Agents")]
+
+
 class AgentLookupResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -71,14 +78,6 @@ class AgentVersionInfo(BaseModel):
     created_at: Annotated[AwareDatetime, Field(title="Created At")]
 
 
-class AgentVersionsResponse(BaseModel):
-    model_config = ConfigDict(
-        extra="allow",
-    )
-    name: Annotated[str, Field(title="Name")]
-    versions: Annotated[list[AgentVersionInfo], Field(title="Versions")]
-
-
 class AuthStatusResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -566,13 +565,6 @@ class WorldVersionsResponse(BaseModel):
     versions: Annotated[list[str], Field(title="Versions")]
 
 
-class ChronosApiRegistryAgentListResponse(BaseModel):
-    model_config = ConfigDict(
-        extra="allow",
-    )
-    agents: Annotated[list[AgentInfo], Field(title="Agents")]
-
-
 class ChronosApiRegistryAgentSchemaResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -592,12 +584,19 @@ class ChronosApiRegistryAgentVersionInfo(BaseModel):
     created_at: Annotated[str | None, Field(title="Created At")] = None
 
 
-class ChronosApiRegistryAgentVersionsResponse(BaseModel):
+class ChronosModelsAgentAgentListResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    agents: Annotated[list[AgentResponse], Field(title="Agents")]
+
+
+class ChronosModelsAgentAgentVersionsResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
     name: Annotated[str, Field(title="Name")]
-    versions: Annotated[list[ChronosApiRegistryAgentVersionInfo], Field(title="Versions")]
+    versions: Annotated[list[AgentVersionInfo], Field(title="Versions")]
 
 
 class ChronosModelsSessionWorldInfo(BaseModel):
@@ -610,11 +609,12 @@ class ChronosModelsSessionWorldInfo(BaseModel):
     config_schema: Annotated[dict[str, Any] | None, Field(title="Config Schema")] = None
 
 
-class AgentListResponse(BaseModel):
+class AgentVersionsResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    agents: Annotated[list[AgentResponse], Field(title="Agents")]
+    name: Annotated[str, Field(title="Name")]
+    versions: Annotated[list[ChronosApiRegistryAgentVersionInfo], Field(title="Versions")]
 
 
 class CreatorsListResponse(BaseModel):

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/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.8.dist-info → plato_sdk_v2-2.8.0.dist-info}/METADATA

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

{plato_sdk_v2-2.7.8.dist-info → plato_sdk_v2-2.8.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 plato/__init__.py,sha256=a9E0KS1602GWHHStnf7wDEuvPCvh2GpPh0Sf8oKZx5Q,1795
 plato/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-plato/_generated/__init__.py,sha256=brhuFWbKg8Opk2yHAz61gRXPfpKEzNfdwTkft1lRx7w,738
+plato/_generated/__init__.py,sha256=finH7i7IrCbUnu4ussJ7wY_duPHgclocRcijeXEUVi8,738
 plato/_generated/client.py,sha256=_oMKXyAShQVddCaIKnfB2zPkRsDlCwLp-N3RFoKq_v8,5489
 plato/_generated/errors.py,sha256=goTGrZ4rrujGZ-BoOonoyaGwdGDkGO6GyeubIkQVv9E,4197
 plato/_generated/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -266,7 +266,7 @@ plato/_generated/api/v2/releases/handle_import.py,sha256=ByBl6tHDKMXD0Ic_C4jpokx
 plato/_generated/api/v2/releases/list_releases.py,sha256=ebNZc45ooGrKT-1lZ6mIjruTO8zwngz5G9edS6DB7lc,2149
 plato/_generated/api/v2/releases/prep_release_assigned_testcases.py,sha256=B171O7xqXZm1AEXGhSfPNobBsqQRINxX4gYBU-TTwEg,2668
 plato/_generated/api/v2/releases/update.py,sha256=aEz9dbnvRg5pAp1jkTZpwUjKxpOOn-xXktPeNVKpruI,1956
-plato/_generated/api/v2/sessions/__init__.py,sha256=DIDigu6vbUeREZGAmAhctkjjtBoC9G3NBs-ukWpJd5o,1225
+plato/_generated/api/v2/sessions/__init__.py,sha256=AC6xIczdSAW34kxj7aRUG1aWMPOwK93zHA0F_bcJ4Eo,1259
 plato/_generated/api/v2/sessions/add_job.py,sha256=PqnYCPuOFkqJjaK5jg7O4v92La4In2pSiCI1A_OoJRQ,2792
 plato/_generated/api/v2/sessions/add_ssh_key.py,sha256=JDaw5B1hHodH43DUoZ7FrO1_ECWacjinia4-DbU0jGo,2198
 plato/_generated/api/v2/sessions/checkpoint.py,sha256=Kd8NSIeuC41cRB4Y3j_L0yNIU_WVRjkBIL72pRqoRTc,2933
@@ -289,6 +289,7 @@ plato/_generated/api/v2/sessions/list_jobs.py,sha256=FbfOqNLqvk0hq4tngFYvgA-kQkL
 plato/_generated/api/v2/sessions/list_sessions.py,sha256=GPm_nShD8DxJD86v3n64kjtBctBZ8iGX9sERAdWKk68,1929
 plato/_generated/api/v2/sessions/log_job_mutation.py,sha256=6x8rSFCbd3u3p3jms62X4k2BGk6eMuoUn04Ha3Pj1P8,1870
 plato/_generated/api/v2/sessions/make.py,sha256=1FP7rCbjT62T8Of9otByl6L0p-VwwsruoaK--vYUUx0,2081
+plato/_generated/api/v2/sessions/remove_job.py,sha256=Lc3ERBR1cTFv-3u1Wbz5QDu5ksy5MqSke2GT6zgViiA,2374
 plato/_generated/api/v2/sessions/reset.py,sha256=L8s2E_8wMq0hkNGNKrCx8gHTm-1KXltlzfHVI5sY14U,1941
 plato/_generated/api/v2/sessions/set_date.py,sha256=jbw3KVBI5TngHGBMavFawjNudRutAC0eb8jEbsSJdkw,2278
 plato/_generated/api/v2/sessions/setup_sandbox.py,sha256=FtxC3NXFPpITupyBYlRtsMfP64vXYuKq23pwACT9v0U,3162
@@ -301,7 +302,7 @@ plato/_generated/api/v2/user/__init__.py,sha256=yMh1Gn9VpKHQMQCmJdpeDPA9Ek9PBgP0
 plato/_generated/api/v2/user/get_current_user.py,sha256=tvamtbWTEkeeNUBLSPqZIcCGqKVadQM3DVcezsWP22U,1814
 plato/_generated/api/version/__init__.py,sha256=dQXTYrXjD1RZcvWwnlqXWAZ-eAV-V-6JSNuY7uaca7o,70
 plato/_generated/api/version/check.py,sha256=HTVNw0oi9gbvX4pOVoH4y4JywCxdl1pJTCk2PjJFwJ4,778
-plato/_generated/models/__init__.py,sha256=UPFr8mItkDevaDF7ML28Ugqi0uudQIvWM_d629suqwA,162089
+plato/_generated/models/__init__.py,sha256=597HUbpzjUUHGONUbaS5JE4W_gjcqn7_sJDmvHkvDnc,163870
 plato/_sims_generator/__init__.py,sha256=Km4QOl9wxjQ5dgpdhk9QnBFJFFc9eq3rPbMWIQRjIn0,1602
 plato/_sims_generator/cli.py,sha256=mzolN-dxfMkVAdA-vC0esnai-cGg-i4ozOw8dACefV4,2709
 plato/_sims_generator/instruction.py,sha256=Na9M-jIdBPhp_fLuBPTicoFnWriRyi8YiZ-eQBj64HI,6644
@@ -340,8 +341,8 @@ plato/chronos/api/agents/create_agent.py,sha256=G8LR1KlWOCfmZ71Sl0seo7aRYmG7_nok
 plato/chronos/api/agents/delete_agent.py,sha256=fuL8Ip8veUXpOhSYxX_74S0zM_kZsTX61KosiFyhRWo,1241
 plato/chronos/api/agents/get_agent.py,sha256=o61fxCyYpTe6-3SC2RAebp3kW8rgEOWSN_NCph_iMUc,1358
 plato/chronos/api/agents/get_agent_schema.py,sha256=O-N1h0vQJIXM2uonYCgXa_FFr54C4_n0Spu-MdRy2U0,1679
-plato/chronos/api/agents/get_agent_versions.py,sha256=h8f_DQyX4OM0oDNA4iZ-Zm6j7iemNgRf7nuze_3bdXc,1406
-plato/chronos/api/agents/list_agents.py,sha256=jtzD0wFmlHPDFqrChCLCG5m6LkLuxNlZk4EboRpcAYA,1253
+plato/chronos/api/agents/get_agent_versions.py,sha256=mVLFvOrAwoyR9Jnu4F26EhNv08zGbXywiohr6hojxMY,1496
+plato/chronos/api/agents/list_agents.py,sha256=OcycIUUc8yTGAhmpr2qhU2-2qIbvAtKko6l7cgmcKes,1343
 plato/chronos/api/agents/lookup_agent.py,sha256=DOGfrOK6Lh6ULMqRmf4zRQHlDXMhYenidx8wcZx4caY,1766
 plato/chronos/api/auth/__init__.py,sha256=6qao3xT8yw9-WTpUlv4tVtpWhL2EycQd3I2WKQ5p9Lk,284
 plato/chronos/api/auth/debug_auth_api_auth_debug_get.py,sha256=L1RWyQ1w7V8dyhOAU2VQlT9x0jkeng3eIvZDOv9Gl2w,881
@@ -362,10 +363,10 @@ plato/chronos/api/otel/get_session_traces_api_otel_sessions__session_id__traces_
 plato/chronos/api/otel/receive_traces_api_otel_v1_traces_post.py,sha256=XvEe6XBB672qZ_d9IkD9dhxehK-H07yGxqKPaZG-EXA,1074
 plato/chronos/api/registry/__init__.py,sha256=gPN-3oENHUrwaiacYt1_jI7HQ6gGe9i-34-Smb-0KHg,819
 plato/chronos/api/registry/get_agent_schema_api_registry_agents__agent_name__schema_get.py,sha256=gkM9RY6yO_I4A2152BkaBzGyjAmWg0mm25s-c8QixwY,1533
-plato/chronos/api/registry/get_agent_versions_api_registry_agents__agent_name__versions_get.py,sha256=f1YtvnT9HMkPxP3hLpIRx1K0KidEV9WmUA_bhBXCtiY,1266
+plato/chronos/api/registry/get_agent_versions_api_registry_agents__agent_name__versions_get.py,sha256=TjYCZcIc6Bc0iS1E2MMPAK-yDUX_zijT8g7We7dNcQI,1176
 plato/chronos/api/registry/get_world_schema_api_registry_worlds__package_name__schema_get.py,sha256=RM-1MDYaG8B9iRl93KBG4tVjWJAHA08X6lSwjzk8fkw,1697
 plato/chronos/api/registry/get_world_versions_api_registry_worlds__package_name__versions_get.py,sha256=07MKXi5-d8Qk8cKRdVW2AZoeeksX7OpTgFR9bkJni0Y,1206
-plato/chronos/api/registry/list_registry_agents_api_registry_agents_get.py,sha256=gzRRPfHGzhczL1Xi274cg-oLwUzqdS2B7JkzhHNZKEw,1121
+plato/chronos/api/registry/list_registry_agents_api_registry_agents_get.py,sha256=3rACHpvv2P7gooHcNH4sU82pCSPIWH0f17lmQyGdEyU,1031
 plato/chronos/api/registry/list_registry_worlds_api_registry_worlds_get.py,sha256=g9KHZ2ZLJnhS5uCb55K7ez5plpfGL88o-pcdLMDgrRg,1010
 plato/chronos/api/runtimes/__init__.py,sha256=_887oqgAfMazmoU-tTbOQ4k-k6E0PW004bdFxTM117M,270
 plato/chronos/api/runtimes/create_runtime.py,sha256=D37d2nMqyTxT8r_9faPWI-E18pAVjLlh0hCgBf0L6wQ,1524
@@ -412,7 +413,7 @@ plato/chronos/api/worlds/create_world.py,sha256=H6yl5QIazNXgryOR5rvscSIMf8Y9kjc6
 plato/chronos/api/worlds/delete_world.py,sha256=UETu3Zk0e2VkDdAyMilv1ev-0g_j-oujH1Dc8DBqQOc,1239
 plato/chronos/api/worlds/get_world.py,sha256=eHTM1U5JiNTaZwYLh7x4QVBoRQeI5kaJ9o6xSi4-nos,1356
 plato/chronos/api/worlds/list_worlds.py,sha256=hBAuGb69tlasyn-kV_LNr9x6Rr7SHhST5hXJn1uqMf8,1253
-plato/chronos/models/__init__.py,sha256=d_L57okr2l6WIqAD-VLFQ9njrbovP2CCdvsEV50jMn4,23198
+plato/chronos/models/__init__.py,sha256=M2dV42UmYgsNC4M76jOO4vILgzNvM6m3BGpf6McfFwE,23198
 plato/cli/__init__.py,sha256=UsKj-69eWKuAlk-Fiwlrz0GJiBfuOmcf-ZLmZJb21Vo,102
 plato/cli/agent.py,sha256=5qA0T1n0H0JQ5ZB-fAVKm3Nw-y_M-GiSQx1OTcKgkrI,44050
 plato/cli/audit_ui.py,sha256=AfnC3wngGV3ujg9POHNYQhal2S6Hr0ZhcXrAAxtVfMg,12307
@@ -505,7 +506,7 @@ plato/v2/async_/chronos.py,sha256=WeqYF3HIKs7hV9LNZb2GlDS1yP6b422DZKtNuPxdL34,12
 plato/v2/async_/client.py,sha256=IhiEiwbLNPBr9JJilw4uz7MLKXY_rUZpYGYC1dX-UfA,5186
 plato/v2/async_/environment.py,sha256=M5IeWYLwREOIyuS2zqgBSqHE_x66_OZXrevA9Rkc8Is,5825
 plato/v2/async_/flow_executor.py,sha256=Tl4nRu1ZPWJFNNxyTGy-PxvebZEUD18ZDaz8T2chtzU,14188
-plato/v2/async_/session.py,sha256=0zErrTEm9-xxIz6pzp_y2stzn498KXVle7n51HVhyhc,37910
+plato/v2/async_/session.py,sha256=31sJeQNKlUL2g0GRsJAG1OmoQp5LJxwfCECuUBh87CQ,43459
 plato/v2/sync/__init__.py,sha256=3WXLqem7GbicVevLD1lCarr7YI1m6j7-AmJf9OVKKgc,521
 plato/v2/sync/artifact.py,sha256=wTLC-tugG128wLvh-JqNPb0zsw5FXEJlZNahurSWink,1169
 plato/v2/sync/chronos.py,sha256=ChXpasjRzAZjoYTimpPqYydnwEk-IgdxR0SDXDOZbUM,12078
@@ -513,7 +514,7 @@ plato/v2/sync/client.py,sha256=rsrU7_RhE-syf3FMNw5LaxmF7rYw2GBzC_TPpd-6thk,4986
 plato/v2/sync/environment.py,sha256=WnDzbyEHpwCSEP8XnfNSjIYS7rt7lYR4HGJjzprZmTQ,5066
 plato/v2/sync/flow_executor.py,sha256=N41-WCWIJVcCR2UmPUEiK7roNacYoeONkRXpR7lUgT8,13941
 plato/v2/sync/sandbox.py,sha256=yRwkms1_qsHjhbLZQ7FiaLgFme2tMw8YM2xg2-ZZS04,53734
-plato/v2/sync/session.py,sha256=NL_qEXnXjZfAsuFgpq72pVmHa9ouo8W3HkJ5vYaNSQU,29555
+plato/v2/sync/session.py,sha256=FYVxgGZ3eL_YpoJiUgJamrt-jVaBqJITzFzepOKMRjA,35065
 plato/v2/utils/__init__.py,sha256=XLeFFsjXkm9g2raMmo7Wt4QN4hhCrNZDJKnpffJ4LtM,38
 plato/v2/utils/db_cleanup.py,sha256=JMzAAJz0ZnoUXtd8F4jpQmBpJpos2__RkgN_cuEearg,8692
 plato/v2/utils/gateway_tunnel.py,sha256=eWgwf4VV8-jx6iCuHFgCISsAOVmNOOjCB56EuZLsnOA,7171
@@ -525,7 +526,7 @@ plato/worlds/base.py,sha256=-RR71bSxEFI5yydtrtq-AAbuw98CIjvmrbztqzB9oIc,31041
 plato/worlds/build_hook.py,sha256=KSoW0kqa5b7NyZ7MYOw2qsZ_2FkWuz0M3Ru7AKOP7Qw,3486
 plato/worlds/config.py,sha256=O1lUXzxp-Z_M7izslT8naXgE6XujjzwYFFrDDzUOueI,12736
 plato/worlds/runner.py,sha256=r9B2BxBae8_dM7y5cJf9xhThp_I1Qvf_tlPq2rs8qC8,4013
-plato_sdk_v2-2.7.8.dist-info/METADATA,sha256=0tWLTeELlL1LpEnzxTPy9pYg1rMvoLc5Ie3MxMYxVIA,8652
-plato_sdk_v2-2.7.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plato_sdk_v2-2.7.8.dist-info/entry_points.txt,sha256=iynJvTkU7E4MZNtSozVF0Wh083yPm6cuKV362Ol_ez8,133
-plato_sdk_v2-2.7.8.dist-info/RECORD,,
+plato_sdk_v2-2.8.0.dist-info/METADATA,sha256=ouPYAxE-Lp1XW9dhodGVz5E-cPdN-jEFRPjkYnsooNM,8652
+plato_sdk_v2-2.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plato_sdk_v2-2.8.0.dist-info/entry_points.txt,sha256=iynJvTkU7E4MZNtSozVF0Wh083yPm6cuKV362Ol_ez8,133
+plato_sdk_v2-2.8.0.dist-info/RECORD,,