feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 14
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta%2Fwarp-api-8f9c749573846b07a55a3131b66456f0a592838c6bfc986ab30948df66cd6f11.yml
-openapi_spec_hash: 59f1ac98ad6cf13b12c59196bcecffd7
-config_hash: 60052b2c1c0862014416821aba875574
+configured_endpoints: 15
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta%2Fwarp-api-abde9a81e648a7bbddbb7c7af07eb9202e584f78dea9cc79ff075da2ad66efd5.yml
+openapi_spec_hash: db45809e85b0f85020a6b046c6eed90e
+config_hash: 253e4b5ca01236d448980a78491c17c5

api.md

@@ -7,6 +7,7 @@ from oz_agent_sdk.types import (
     AgentSkill,
     AmbientAgentConfig,
     AwsProviderConfig,
+    CloudEnvironment,
     CloudEnvironmentConfig,
     Error,
     ErrorCode,
@@ -16,6 +17,7 @@ from oz_agent_sdk.types import (
     UserProfile,
     AgentListResponse,
     AgentGetArtifactResponse,
+    AgentListEnvironmentsResponse,
     AgentRunResponse,
 )
 ```
@@ -24,6 +26,7 @@ Methods:
 
 - <code title="get /agent">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">list</a>(\*\*<a href="src/oz_agent_sdk/types/agent_list_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent_list_response.py">AgentListResponse</a></code>
 - <code title="get /agent/artifacts/{artifactUid}">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">get_artifact</a>(artifact_uid) -> <a href="./src/oz_agent_sdk/types/agent_get_artifact_response.py">AgentGetArtifactResponse</a></code>
+- <code title="get /agent/environments">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">list_environments</a>(\*\*<a href="src/oz_agent_sdk/types/agent_list_environments_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent_list_environments_response.py">AgentListEnvironmentsResponse</a></code>
 - <code title="post /agent/runs">client.agent.<a href="./src/oz_agent_sdk/resources/agent/agent.py">run</a>(\*\*<a href="src/oz_agent_sdk/types/agent_run_params.py">params</a>) -> <a href="./src/oz_agent_sdk/types/agent_run_response.py">AgentRunResponse</a></code>
 
 ## Runs

src/oz_agent_sdk/resources/agent/agent.py

@@ -15,7 +15,7 @@
     RunsResourceWithStreamingResponse,
     AsyncRunsResourceWithStreamingResponse,
 )
-from ...types import agent_run_params, agent_list_params
+from ...types import agent_run_params, agent_list_params, agent_list_environments_params
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
 from ..._utils import path_template, maybe_transform, async_maybe_transform
 from .sessions import (
@@ -47,6 +47,7 @@
 from ...types.agent_list_response import AgentListResponse
 from ...types.ambient_agent_config_param import AmbientAgentConfigParam
 from ...types.agent_get_artifact_response import AgentGetArtifactResponse
+from ...types.agent_list_environments_response import AgentListEnvironmentsResponse
 
 __all__ = ["AgentResource", "AsyncAgentResource"]
 
@@ -163,8 +164,9 @@ def get_artifact(
     ) -> AgentGetArtifactResponse:
         """Retrieve an artifact by its UUID.
 
-        For supported downloadable artifacts, returns
-        a time-limited signed download URL.
+        For downloadable file-like artifacts, returns
+        a time-limited signed download URL. For plan artifacts, returns the current plan
+        content inline.
 
         Args:
           extra_headers: Send extra headers
@@ -190,6 +192,49 @@ def get_artifact(
             ),
         )
 
+    def list_environments(
+        self,
+        *,
+        sort_by: Literal["name", "last_updated"] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AgentListEnvironmentsResponse:
+        """Retrieve cloud environments accessible to the authenticated principal.
+
+        Returns
+        environments the caller owns, has been granted guest access to, or has accessed
+        via link sharing.
+
+        Args:
+          sort_by: Sort order for the returned environments.
+
+              - `name`: alphabetical by environment name
+              - `last_updated`: most recently updated first (default)
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._get(
+            "/agent/environments",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform({"sort_by": sort_by}, agent_list_environments_params.AgentListEnvironmentsParams),
+            ),
+            cast_to=AgentListEnvironmentsResponse,
+        )
+
     def run(
         self,
         *,
@@ -392,8 +437,9 @@ async def get_artifact(
     ) -> AgentGetArtifactResponse:
         """Retrieve an artifact by its UUID.
 
-        For supported downloadable artifacts, returns
-        a time-limited signed download URL.
+        For downloadable file-like artifacts, returns
+        a time-limited signed download URL. For plan artifacts, returns the current plan
+        content inline.
 
         Args:
           extra_headers: Send extra headers
@@ -419,6 +465,51 @@ async def get_artifact(
             ),
         )
 
+    async def list_environments(
+        self,
+        *,
+        sort_by: Literal["name", "last_updated"] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AgentListEnvironmentsResponse:
+        """Retrieve cloud environments accessible to the authenticated principal.
+
+        Returns
+        environments the caller owns, has been granted guest access to, or has accessed
+        via link sharing.
+
+        Args:
+          sort_by: Sort order for the returned environments.
+
+              - `name`: alphabetical by environment name
+              - `last_updated`: most recently updated first (default)
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._get(
+            "/agent/environments",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform(
+                    {"sort_by": sort_by}, agent_list_environments_params.AgentListEnvironmentsParams
+                ),
+            ),
+            cast_to=AgentListEnvironmentsResponse,
+        )
+
     async def run(
         self,
         *,
@@ -519,6 +610,9 @@ def __init__(self, agent: AgentResource) -> None:
         self.get_artifact = to_raw_response_wrapper(
             agent.get_artifact,
         )
+        self.list_environments = to_raw_response_wrapper(
+            agent.list_environments,
+        )
         self.run = to_raw_response_wrapper(
             agent.run,
         )
@@ -549,6 +643,9 @@ def __init__(self, agent: AsyncAgentResource) -> None:
         self.get_artifact = async_to_raw_response_wrapper(
             agent.get_artifact,
         )
+        self.list_environments = async_to_raw_response_wrapper(
+            agent.list_environments,
+        )
         self.run = async_to_raw_response_wrapper(
             agent.run,
         )
@@ -579,6 +676,9 @@ def __init__(self, agent: AgentResource) -> None:
         self.get_artifact = to_streamed_response_wrapper(
             agent.get_artifact,
         )
+        self.list_environments = to_streamed_response_wrapper(
+            agent.list_environments,
+        )
         self.run = to_streamed_response_wrapper(
             agent.run,
         )
@@ -609,6 +709,9 @@ def __init__(self, agent: AsyncAgentResource) -> None:
         self.get_artifact = async_to_streamed_response_wrapper(
             agent.get_artifact,
         )
+        self.list_environments = async_to_streamed_response_wrapper(
+            agent.list_environments,
+        )
         self.run = async_to_streamed_response_wrapper(
             agent.run,
         )

src/oz_agent_sdk/resources/agent/runs.py

@@ -87,6 +87,7 @@ def retrieve(
     def list(
         self,
         *,
+        ancestor_run_id: str | Omit = omit,
         artifact_type: Literal["PLAN", "PULL_REQUEST", "SCREENSHOT", "FILE"] | Omit = omit,
         created_after: Union[str, datetime] | Omit = omit,
         created_before: Union[str, datetime] | Omit = omit,
@@ -119,6 +120,9 @@ def list(
         to `sort_by=updated_at` and `sort_order=desc`.
 
         Args:
+          ancestor_run_id: Filter runs by ancestor run ID. The referenced run must exist and be accessible
+              to the caller.
+
           artifact_type: Filter runs by artifact type
 
           created_after: Filter runs created after this timestamp (RFC3339 format)
@@ -182,6 +186,7 @@ def list(
                 timeout=timeout,
                 query=maybe_transform(
                     {
+                        "ancestor_run_id": ancestor_run_id,
                         "artifact_type": artifact_type,
                         "created_after": created_after,
                         "created_before": created_before,
@@ -307,6 +312,7 @@ async def retrieve(
     def list(
         self,
         *,
+        ancestor_run_id: str | Omit = omit,
         artifact_type: Literal["PLAN", "PULL_REQUEST", "SCREENSHOT", "FILE"] | Omit = omit,
         created_after: Union[str, datetime] | Omit = omit,
         created_before: Union[str, datetime] | Omit = omit,
@@ -339,6 +345,9 @@ def list(
         to `sort_by=updated_at` and `sort_order=desc`.
 
         Args:
+          ancestor_run_id: Filter runs by ancestor run ID. The referenced run must exist and be accessible
+              to the caller.
+
           artifact_type: Filter runs by artifact type
 
           created_after: Filter runs created after this timestamp (RFC3339 format)
@@ -402,6 +411,7 @@ def list(
                 timeout=timeout,
                 query=maybe_transform(
                     {
+                        "ancestor_run_id": ancestor_run_id,
                         "artifact_type": artifact_type,
                         "created_after": created_after,
                         "created_before": created_before,

src/oz_agent_sdk/types/__init__.py

@@ -8,6 +8,7 @@
 from .user_profile import UserProfile as UserProfile
 from .agent_run_params import AgentRunParams as AgentRunParams
 from .agent_list_params import AgentListParams as AgentListParams
+from .cloud_environment import CloudEnvironment as CloudEnvironment
 from .mcp_server_config import McpServerConfig as McpServerConfig
 from .agent_run_response import AgentRunResponse as AgentRunResponse
 from .agent_list_response import AgentListResponse as AgentListResponse
@@ -18,3 +19,5 @@
 from .cloud_environment_config import CloudEnvironmentConfig as CloudEnvironmentConfig
 from .ambient_agent_config_param import AmbientAgentConfigParam as AmbientAgentConfigParam
 from .agent_get_artifact_response import AgentGetArtifactResponse as AgentGetArtifactResponse
+from .agent_list_environments_params import AgentListEnvironmentsParams as AgentListEnvironmentsParams
+from .agent_list_environments_response import AgentListEnvironmentsResponse as AgentListEnvironmentsResponse

src/oz_agent_sdk/types/agent/artifact_item.py

@@ -24,12 +24,21 @@ class PlanArtifactData(BaseModel):
     document_uid: str
     """Unique identifier for the plan document"""
 
+    artifact_uid: Optional[str] = None
+    """
+    Unique identifier for the plan artifact, usable with the artifact retrieval
+    endpoint
+    """
+
     notebook_uid: Optional[str] = None
     """Unique identifier for the associated notebook"""
 
     title: Optional[str] = None
     """Title of the plan"""
 
+    url: Optional[str] = None
+    """URL to open the plan in Warp Drive"""
+
 
 class PlanArtifact(BaseModel):
     artifact_type: Literal["PLAN"]

src/oz_agent_sdk/types/agent/run_list_params.py

@@ -14,6 +14,12 @@
 
 
 class RunListParams(TypedDict, total=False):
+    ancestor_run_id: str
+    """Filter runs by ancestor run ID.
+
+    The referenced run must exist and be accessible to the caller.
+    """
+
     artifact_type: Literal["PLAN", "PULL_REQUEST", "SCREENSHOT", "FILE"]
     """Filter runs by artifact type"""
 

src/oz_agent_sdk/types/agent_get_artifact_response.py

@@ -9,13 +9,53 @@
 
 __all__ = [
     "AgentGetArtifactResponse",
+    "PlanArtifactResponse",
+    "PlanArtifactResponseData",
     "ScreenshotArtifactResponse",
     "ScreenshotArtifactResponseData",
     "FileArtifactResponse",
     "FileArtifactResponseData",
 ]
 
 
+class PlanArtifactResponseData(BaseModel):
+    """Response data for a plan artifact, including current markdown content."""
+
+    content: str
+    """Current markdown content of the plan"""
+
+    content_type: str
+    """MIME type of the returned plan content"""
+
+    document_uid: str
+    """Unique identifier for the plan document"""
+
+    notebook_uid: str
+    """Unique identifier for the associated notebook"""
+
+    title: Optional[str] = None
+    """Current title of the plan"""
+
+    url: Optional[str] = None
+    """URL to open the plan in Warp Drive"""
+
+
+class PlanArtifactResponse(BaseModel):
+    """Response for retrieving a plan artifact."""
+
+    artifact_type: Literal["PLAN"]
+    """Type of the artifact"""
+
+    artifact_uid: str
+    """Unique identifier (UUID) for the artifact"""
+
+    created_at: datetime
+    """Timestamp when the artifact was created (RFC3339)"""
+
+    data: PlanArtifactResponseData
+    """Response data for a plan artifact, including current markdown content."""
+
+
 class ScreenshotArtifactResponseData(BaseModel):
     """Response data for a screenshot artifact, including a signed download URL."""
 
@@ -90,5 +130,6 @@ class FileArtifactResponse(BaseModel):
 
 
 AgentGetArtifactResponse: TypeAlias = Annotated[
-    Union[ScreenshotArtifactResponse, FileArtifactResponse], PropertyInfo(discriminator="artifact_type")
+    Union[PlanArtifactResponse, ScreenshotArtifactResponse, FileArtifactResponse],
+    PropertyInfo(discriminator="artifact_type"),
 ]

src/oz_agent_sdk/types/agent_list_environments_params.py

@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, TypedDict
+
+__all__ = ["AgentListEnvironmentsParams"]
+
+
+class AgentListEnvironmentsParams(TypedDict, total=False):
+    sort_by: Literal["name", "last_updated"]
+    """Sort order for the returned environments.
+
+    - `name`: alphabetical by environment name
+    - `last_updated`: most recently updated first (default)
+    """