# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. from __future__ import annotations from typing import List, Union from datetime import datetime from typing_extensions import Literal import httpx from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given from ..._utils import path_template, maybe_transform, async_maybe_transform from ..._compat import cached_property from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import ( to_raw_response_wrapper, to_streamed_response_wrapper, async_to_raw_response_wrapper, async_to_streamed_response_wrapper, ) from ...pagination import SyncRunsCursorPage, AsyncRunsCursorPage from ...types.agent import RunSourceType, run_list_params, run_submit_followup_params from ..._base_client import AsyncPaginator, make_request_options from ...types.agent.run_item import RunItem from ...types.agent.run_state import RunState from ...types.agent.run_source_type import RunSourceType from ...types.agent.run_list_handoff_attachments_response import RunListHandoffAttachmentsResponse __all__ = ["RunsResource", "AsyncRunsResource"] class RunsResource(SyncAPIResource): """Operations for running and managing cloud agents""" @cached_property def with_raw_response(self) -> RunsResourceWithRawResponse: """ This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content. For more information, see https://www.github.com/warpdotdev/oz-sdk-python#accessing-raw-response-data-eg-headers """ return RunsResourceWithRawResponse(self) @cached_property def with_streaming_response(self) -> RunsResourceWithStreamingResponse: """ An alternative to `.with_raw_response` that doesn't eagerly read the response body. For more information, see https://www.github.com/warpdotdev/oz-sdk-python#with_streaming_response """ return RunsResourceWithStreamingResponse(self) def retrieve( self, run_id: str, *, # 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, ) -> RunItem: """ Retrieve detailed information about a specific agent run, including the full prompt, session link, and resolved configuration. Args: 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return self._get( path_template("/agent/runs/{run_id}", run_id=run_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=RunItem, ) 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, creator: str | Omit = omit, cursor: str | Omit = omit, environment_id: str | Omit = omit, execution_location: Literal["LOCAL", "REMOTE"] | Omit = omit, executor: str | Omit = omit, limit: int | Omit = omit, model_id: str | Omit = omit, name: str | Omit = omit, q: str | Omit = omit, 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, # 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, ) -> SyncRunsCursorPage[RunItem]: """Retrieve a paginated list of agent runs with optional filtering. Results default 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) created_before: Filter runs created before this timestamp (RFC3339 format) creator: Filter by creator UID (user or service account) cursor: Pagination cursor from previous response environment_id: Filter runs by environment ID execution_location: Filter by where the run executed executor: Filter by the user or agent that executed the run. This will often be the same as the creator, but not always: users may delegate tasks to agents. limit: Maximum number of runs to return model_id: Filter by model ID name: Filter by agent config name q: Fuzzy search query across run title, prompt, and skill_spec schedule_id: Filter runs by the scheduled agent ID that created them skill: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec. 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 states. updated_after: Filter runs updated after this timestamp (RFC3339 format) 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_api_list( "/agent/runs", page=SyncRunsCursorPage[RunItem], options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform( { "ancestor_run_id": ancestor_run_id, "artifact_type": artifact_type, "created_after": created_after, "created_before": created_before, "creator": creator, "cursor": cursor, "environment_id": environment_id, "execution_location": execution_location, "executor": executor, "limit": limit, "model_id": model_id, "name": name, "q": q, "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, }, run_list_params.RunListParams, ), ), model=RunItem, ) def cancel( self, run_id: str, *, # 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, ) -> str: """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. Args: 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return self._post( path_template("/agent/runs/{run_id}/cancel", run_id=run_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=str, ) def list_handoff_attachments( self, run_id: str, *, # 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, ) -> RunListHandoffAttachmentsResponse: """ Return fresh presigned download URLs for handoff snapshot files uploaded by the latest ended execution of this run. An empty list is returned when no ended execution exists or no snapshot files were uploaded. This endpoint is useful for third-party harnesses that want to download the snapshot files produced by a previous execution before starting a handoff execution themselves. Args: 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return self._get( path_template("/agent/runs/{run_id}/handoff/attachments", run_id=run_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=RunListHandoffAttachmentsResponse, ) def submit_followup( self, run_id: str, *, message: str, mode: Literal["normal", "plan", "orchestrate"] | 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, ) -> object: """Send a follow-up message to an existing run. The server transparently routes the message based on the current state of the run (still queued, actively running, or ended). A 200 response means the follow-up was accepted; updated run state can be observed via `GET /agent/runs/{runId}`. Args: message: The follow-up message to send to the run. mode: Optional query mode for the follow-up. Defaults to `normal` when omitted. The server does not infer mode from prompt prefixes such as `/plan`. 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return self._post( path_template("/agent/runs/{run_id}/followups", run_id=run_id), body=maybe_transform( { "message": message, "mode": mode, }, run_submit_followup_params.RunSubmitFollowupParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=object, ) class AsyncRunsResource(AsyncAPIResource): """Operations for running and managing cloud agents""" @cached_property def with_raw_response(self) -> AsyncRunsResourceWithRawResponse: """ This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content. For more information, see https://www.github.com/warpdotdev/oz-sdk-python#accessing-raw-response-data-eg-headers """ return AsyncRunsResourceWithRawResponse(self) @cached_property def with_streaming_response(self) -> AsyncRunsResourceWithStreamingResponse: """ An alternative to `.with_raw_response` that doesn't eagerly read the response body. For more information, see https://www.github.com/warpdotdev/oz-sdk-python#with_streaming_response """ return AsyncRunsResourceWithStreamingResponse(self) async def retrieve( self, run_id: str, *, # 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, ) -> RunItem: """ Retrieve detailed information about a specific agent run, including the full prompt, session link, and resolved configuration. Args: 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return await self._get( path_template("/agent/runs/{run_id}", run_id=run_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=RunItem, ) 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, creator: str | Omit = omit, cursor: str | Omit = omit, environment_id: str | Omit = omit, execution_location: Literal["LOCAL", "REMOTE"] | Omit = omit, executor: str | Omit = omit, limit: int | Omit = omit, model_id: str | Omit = omit, name: str | Omit = omit, q: str | Omit = omit, 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, # 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, ) -> AsyncPaginator[RunItem, AsyncRunsCursorPage[RunItem]]: """Retrieve a paginated list of agent runs with optional filtering. Results default 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) created_before: Filter runs created before this timestamp (RFC3339 format) creator: Filter by creator UID (user or service account) cursor: Pagination cursor from previous response environment_id: Filter runs by environment ID execution_location: Filter by where the run executed executor: Filter by the user or agent that executed the run. This will often be the same as the creator, but not always: users may delegate tasks to agents. limit: Maximum number of runs to return model_id: Filter by model ID name: Filter by agent config name q: Fuzzy search query across run title, prompt, and skill_spec schedule_id: Filter runs by the scheduled agent ID that created them skill: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec. 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 states. updated_after: Filter runs updated after this timestamp (RFC3339 format) 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_api_list( "/agent/runs", page=AsyncRunsCursorPage[RunItem], options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform( { "ancestor_run_id": ancestor_run_id, "artifact_type": artifact_type, "created_after": created_after, "created_before": created_before, "creator": creator, "cursor": cursor, "environment_id": environment_id, "execution_location": execution_location, "executor": executor, "limit": limit, "model_id": model_id, "name": name, "q": q, "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, }, run_list_params.RunListParams, ), ), model=RunItem, ) async def cancel( self, run_id: str, *, # 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, ) -> str: """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. Args: 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return await self._post( path_template("/agent/runs/{run_id}/cancel", run_id=run_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=str, ) async def list_handoff_attachments( self, run_id: str, *, # 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, ) -> RunListHandoffAttachmentsResponse: """ Return fresh presigned download URLs for handoff snapshot files uploaded by the latest ended execution of this run. An empty list is returned when no ended execution exists or no snapshot files were uploaded. This endpoint is useful for third-party harnesses that want to download the snapshot files produced by a previous execution before starting a handoff execution themselves. Args: 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return await self._get( path_template("/agent/runs/{run_id}/handoff/attachments", run_id=run_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=RunListHandoffAttachmentsResponse, ) async def submit_followup( self, run_id: str, *, message: str, mode: Literal["normal", "plan", "orchestrate"] | 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, ) -> object: """Send a follow-up message to an existing run. The server transparently routes the message based on the current state of the run (still queued, actively running, or ended). A 200 response means the follow-up was accepted; updated run state can be observed via `GET /agent/runs/{runId}`. Args: message: The follow-up message to send to the run. mode: Optional query mode for the follow-up. Defaults to `normal` when omitted. The server does not infer mode from prompt prefixes such as `/plan`. 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 """ if not run_id: raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}") return await self._post( path_template("/agent/runs/{run_id}/followups", run_id=run_id), body=await async_maybe_transform( { "message": message, "mode": mode, }, run_submit_followup_params.RunSubmitFollowupParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=object, ) class RunsResourceWithRawResponse: def __init__(self, runs: RunsResource) -> None: self._runs = runs self.retrieve = to_raw_response_wrapper( runs.retrieve, ) self.list = to_raw_response_wrapper( runs.list, ) self.cancel = to_raw_response_wrapper( runs.cancel, ) self.list_handoff_attachments = to_raw_response_wrapper( runs.list_handoff_attachments, ) self.submit_followup = to_raw_response_wrapper( runs.submit_followup, ) class AsyncRunsResourceWithRawResponse: def __init__(self, runs: AsyncRunsResource) -> None: self._runs = runs self.retrieve = async_to_raw_response_wrapper( runs.retrieve, ) self.list = async_to_raw_response_wrapper( runs.list, ) self.cancel = async_to_raw_response_wrapper( runs.cancel, ) self.list_handoff_attachments = async_to_raw_response_wrapper( runs.list_handoff_attachments, ) self.submit_followup = async_to_raw_response_wrapper( runs.submit_followup, ) class RunsResourceWithStreamingResponse: def __init__(self, runs: RunsResource) -> None: self._runs = runs self.retrieve = to_streamed_response_wrapper( runs.retrieve, ) self.list = to_streamed_response_wrapper( runs.list, ) self.cancel = to_streamed_response_wrapper( runs.cancel, ) self.list_handoff_attachments = to_streamed_response_wrapper( runs.list_handoff_attachments, ) self.submit_followup = to_streamed_response_wrapper( runs.submit_followup, ) class AsyncRunsResourceWithStreamingResponse: def __init__(self, runs: AsyncRunsResource) -> None: self._runs = runs self.retrieve = async_to_streamed_response_wrapper( runs.retrieve, ) self.list = async_to_streamed_response_wrapper( runs.list, ) self.cancel = async_to_streamed_response_wrapper( runs.cancel, ) self.list_handoff_attachments = async_to_streamed_response_wrapper( runs.list_handoff_attachments, ) self.submit_followup = async_to_streamed_response_wrapper( runs.submit_followup, )