feat(api): sorting

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-39e18bbb8b0af73eca7a880f56afbdecd69e3e5bab82a04c4d6429c32d7e6727.yml
-openapi_spec_hash: 7a0de988bb37416d6e80f4a4bbe9d0d0
-config_hash: 38ab203e1bd97a9bb22bbf744bcb5808
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta%2Fwarp-api-a368122275968e270e3e786e6cf176ae87aa56ef85e3270ed59da99c87996dc8.yml
+openapi_spec_hash: 86cab7da7cb620fc90482f50d92acf70
+config_hash: 25c1059aa958c8c2ad60ef16c318514d

api.md

@@ -7,10 +7,7 @@ from oz_agent_sdk.types import (
     AgentSkill,
     AmbientAgentConfig,
     CloudEnvironmentConfig,
-    Error,
-    ErrorCode,
     McpServerConfig,
-    Scope,
     UserProfile,
     AgentListResponse,
     AgentGetArtifactResponse,
@@ -51,7 +48,6 @@ Types:
 
 ```python
 from oz_agent_sdk.types.agent import (
-    ScheduledAgentHistoryItem,
     ScheduledAgentItem,
     ScheduleListResponse,
     ScheduleDeleteResponse,

src/oz_agent_sdk/resources/agent/runs.py

@@ -100,6 +100,8 @@ def list(
         schedule_id: str | Omit = omit,
         skill: str | Omit = omit,
         skill_spec: str | Omit = omit,
+        sort_by: Literal["updated_at", "created_at", "title", "agent"] | Omit = omit,
+        sort_order: Literal["asc", "desc"] | Omit = omit,
         source: RunSourceType | Omit = omit,
         state: List[RunState] | Omit = omit,
         updated_after: Union[str, datetime] | Omit = omit,
@@ -112,8 +114,8 @@ def list(
     ) -> RunListResponse:
         """Retrieve a paginated list of agent runs with optional filtering.
 
-        Results are
-        ordered by creation time (newest first).
+        Results default
+        to `sort_by=updated_at` and `sort_order=desc`.
 
         Args:
           artifact_type: Filter runs by artifact type (PLAN or PULL_REQUEST)
@@ -143,6 +145,15 @@ def list(
 
           skill_spec: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
 
+          sort_by: Sort field for results.
+
+              - `updated_at`: Sort by last update timestamp (default)
+              - `created_at`: Sort by creation timestamp
+              - `title`: Sort alphabetically by run title
+              - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
+
+          sort_order: Sort direction
+
           source: Filter by run source type
 
           state: Filter by run state. Can be specified multiple times to match any of the given
@@ -180,6 +191,8 @@ def list(
                         "schedule_id": schedule_id,
                         "skill": skill,
                         "skill_spec": skill_spec,
+                        "sort_by": sort_by,
+                        "sort_order": sort_order,
                         "source": source,
                         "state": state,
                         "updated_after": updated_after,
@@ -204,11 +217,7 @@ def cancel(
         """Cancel an agent run that is currently queued or in progress.
 
         Once cancelled, the
-        run will transition to a cancelled state.
-
-        Not all runs can be cancelled. Runs that are in a terminal state (SUCCEEDED,
-        FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in PENDING state return 409
-        (retry after a moment). Self-hosted, local, and GitHub Action runs return 422.
+        run will transition to a failed state.
 
         Args:
           extra_headers: Send extra headers
@@ -302,6 +311,8 @@ async def list(
         schedule_id: str | Omit = omit,
         skill: str | Omit = omit,
         skill_spec: str | Omit = omit,
+        sort_by: Literal["updated_at", "created_at", "title", "agent"] | Omit = omit,
+        sort_order: Literal["asc", "desc"] | Omit = omit,
         source: RunSourceType | Omit = omit,
         state: List[RunState] | Omit = omit,
         updated_after: Union[str, datetime] | Omit = omit,
@@ -314,8 +325,8 @@ async def list(
     ) -> RunListResponse:
         """Retrieve a paginated list of agent runs with optional filtering.
 
-        Results are
-        ordered by creation time (newest first).
+        Results default
+        to `sort_by=updated_at` and `sort_order=desc`.
 
         Args:
           artifact_type: Filter runs by artifact type (PLAN or PULL_REQUEST)
@@ -345,6 +356,15 @@ async def list(
 
           skill_spec: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
 
+          sort_by: Sort field for results.
+
+              - `updated_at`: Sort by last update timestamp (default)
+              - `created_at`: Sort by creation timestamp
+              - `title`: Sort alphabetically by run title
+              - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
+
+          sort_order: Sort direction
+
           source: Filter by run source type
 
           state: Filter by run state. Can be specified multiple times to match any of the given
@@ -382,6 +402,8 @@ async def list(
                         "schedule_id": schedule_id,
                         "skill": skill,
                         "skill_spec": skill_spec,
+                        "sort_by": sort_by,
+                        "sort_order": sort_order,
                         "source": source,
                         "state": state,
                         "updated_after": updated_after,
@@ -406,11 +428,7 @@ async def cancel(
         """Cancel an agent run that is currently queued or in progress.
 
         Once cancelled, the
-        run will transition to a cancelled state.
-
-        Not all runs can be cancelled. Runs that are in a terminal state (SUCCEEDED,
-        FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in PENDING state return 409
-        (retry after a moment). Self-hosted, local, and GitHub Action runs return 422.
+        run will transition to a failed state.
 
         Args:
           extra_headers: Send extra headers

src/oz_agent_sdk/types/__init__.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from .scope import Scope as Scope
-from .error_code import ErrorCode as ErrorCode
 from .agent_skill import AgentSkill as AgentSkill
 from .user_profile import UserProfile as UserProfile
 from .agent_run_params import AgentRunParams as AgentRunParams

src/oz_agent_sdk/types/agent/__init__.py

@@ -14,5 +14,4 @@
 from .schedule_list_response import ScheduleListResponse as ScheduleListResponse
 from .schedule_update_params import ScheduleUpdateParams as ScheduleUpdateParams
 from .schedule_delete_response import ScheduleDeleteResponse as ScheduleDeleteResponse
-from .scheduled_agent_history_item import ScheduledAgentHistoryItem as ScheduledAgentHistoryItem
 from .session_check_redirect_response import SessionCheckRedirectResponse as SessionCheckRedirectResponse

src/oz_agent_sdk/types/agent/run_item.py

@@ -2,17 +2,16 @@
 
 from typing import List, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
-from ..scope import Scope
 from ..._models import BaseModel
 from .run_state import RunState
-from ..error_code import ErrorCode
 from ..user_profile import UserProfile
 from .artifact_item import ArtifactItem
 from .run_source_type import RunSourceType
 from ..ambient_agent_config import AmbientAgentConfig
 
-__all__ = ["RunItem", "AgentSkill", "RequestUsage", "Schedule", "StatusMessage"]
+__all__ = ["RunItem", "AgentSkill", "RequestUsage", "Schedule", "Scope", "StatusMessage"]
 
 
 class AgentSkill(BaseModel):
@@ -59,52 +58,19 @@ class Schedule(BaseModel):
     """Name of the schedule at the time the run was created"""
 
 
-class StatusMessage(BaseModel):
-    """Status message for a run.
-
-    For terminal error states, includes structured
-    error code and retryability info from the platform error catalog.
-    """
+class Scope(BaseModel):
+    """Ownership scope for a resource (team or personal)"""
 
-    message: str
-    """Human-readable status message"""
+    type: Literal["User", "Team"]
+    """Type of ownership ("User" for personal, "Team" for team-owned)"""
 
-    error_code: Optional[ErrorCode] = None
-    """
-    Machine-readable error code identifying the problem type. Used in the `type` URI
-    of Error responses and in the `error_code` field of RunStatusMessage.
-
-    User errors (run transitions to FAILED):
-
-    - `insufficient_credits` — Team has no remaining add-on credits
-    - `feature_not_available` — Required feature not enabled for user's plan
-    - `external_authentication_required` — User hasn't authorized a required
-      external service
-    - `not_authorized` — Principal lacks permission for the requested operation
-    - `invalid_request` — Request is malformed or contains invalid parameters
-    - `resource_not_found` — Referenced resource does not exist
-    - `budget_exceeded` — Spending budget limit has been reached
-    - `integration_disabled` — Integration is disabled and must be enabled
-    - `integration_not_configured` — Integration setup is incomplete
-    - `operation_not_supported` — Requested operation not supported for this
-      resource/state
-    - `environment_setup_failed` — Client-side environment setup failed
-    - `content_policy_violation` — Prompt or setup commands violated content policy
-    - `conflict` — Request conflicts with the current state of the resource
-
-    Warp errors (run transitions to ERROR):
-
-    - `authentication_required` — Request lacks valid authentication credentials
-    - `resource_unavailable` — Transient infrastructure issue (retryable)
-    - `internal_error` — Unexpected server-side error (retryable)
-    """
+    uid: Optional[str] = None
+    """UID of the owning user or team"""
 
-    retryable: Optional[bool] = None
-    """Whether the error is transient and the client may retry by submitting a new run.
 
-    Only present on terminal error states. When false, retrying without addressing
-    the underlying cause will not succeed.
-    """
+class StatusMessage(BaseModel):
+    message: Optional[str] = None
+    """Human-readable status message"""
 
 
 class RunItem(BaseModel):
@@ -199,8 +165,3 @@ class RunItem(BaseModel):
     """Timestamp when the agent started working on the run (RFC3339)"""
 
     status_message: Optional[StatusMessage] = None
-    """Status message for a run.
-
-    For terminal error states, includes structured error code and retryability info
-    from the platform error catalog.
-    """

src/oz_agent_sdk/types/agent/run_list_params.py

@@ -56,6 +56,18 @@ class RunListParams(TypedDict, total=False):
     skill_spec: str
     """Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")"""
 
+    sort_by: Literal["updated_at", "created_at", "title", "agent"]
+    """Sort field for results.
+
+    - `updated_at`: Sort by last update timestamp (default)
+    - `created_at`: Sort by creation timestamp
+    - `title`: Sort alphabetically by run title
+    - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
+    """
+
+    sort_order: Literal["asc", "desc"]
+    """Sort direction"""
+
     source: RunSourceType
     """Filter by run source type"""
 

src/oz_agent_sdk/types/agent/scheduled_agent_history_item.py

@@ -2,15 +2,34 @@
 
 from typing import Optional
 from datetime import datetime
+from typing_extensions import Literal
 
-from ..scope import Scope
 from ..._models import BaseModel
 from ..user_profile import UserProfile
 from ..ambient_agent_config import AmbientAgentConfig
 from ..cloud_environment_config import CloudEnvironmentConfig
-from .scheduled_agent_history_item import ScheduledAgentHistoryItem
 
-__all__ = ["ScheduledAgentItem"]
+__all__ = ["ScheduledAgentItem", "History", "Scope"]
+
+
+class History(BaseModel):
+    """Scheduler-derived history metadata for a scheduled agent"""
+
+    last_ran: Optional[datetime] = None
+    """Timestamp of the last successful run (RFC3339)"""
+
+    next_run: Optional[datetime] = None
+    """Timestamp of the next scheduled run (RFC3339)"""
+
+
+class Scope(BaseModel):
+    """Ownership scope for a resource (team or personal)"""
+
+    type: Literal["User", "Team"]
+    """Type of ownership ("User" for personal, "Team" for team-owned)"""
+
+    uid: Optional[str] = None
+    """UID of the owning user or team"""
 
 
 class ScheduledAgentItem(BaseModel):
@@ -46,7 +65,7 @@ class ScheduledAgentItem(BaseModel):
     environment: Optional[CloudEnvironmentConfig] = None
     """Configuration for a cloud environment used by scheduled agents"""
 
-    history: Optional[ScheduledAgentHistoryItem] = None
+    history: Optional[History] = None
     """Scheduler-derived history metadata for a scheduled agent"""
 
     last_spawn_error: Optional[str] = None