runs.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as AgentAPI from './agent';
import { APIPromise } from '../../core/api-promise';
import { PagePromise, RunsCursorPage, type RunsCursorPageParams } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

/**
 * Operations for running and managing cloud agents
 */
export class Runs extends APIResource {
  /**
   * Retrieve detailed information about a specific agent run, including the full
   * prompt, session link, and resolved configuration.
   *
   * @example
   * ```ts
   * const runItem = await client.agent.runs.retrieve('runId');
   * ```
   */
  retrieve(runID: string, options?: RequestOptions): APIPromise<RunItem> {
    return this._client.get(path`/agent/runs/${runID}`, options);
  }

  /**
   * Retrieve a paginated list of agent runs with optional filtering. Results default
   * to `sort_by=updated_at` and `sort_order=desc`.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const runItem of client.agent.runs.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: RunListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<RunItemsRunsCursorPage, RunItem> {
    return this._client.getAPIList('/agent/runs', RunsCursorPage<RunItem>, { query, ...options });
  }

  /**
   * 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.
   *
   * @example
   * ```ts
   * const response = await client.agent.runs.cancel('runId');
   * ```
   */
  cancel(runID: string, options?: RequestOptions): APIPromise<string> {
    return this._client.post(path`/agent/runs/${runID}/cancel`, options);
  }

  /**
   * 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.
   *
   * @example
   * ```ts
   * const response =
   *   await client.agent.runs.listHandoffAttachments('runId');
   * ```
   */
  listHandoffAttachments(
    runID: string,
    options?: RequestOptions,
  ): APIPromise<RunListHandoffAttachmentsResponse> {
    return this._client.get(path`/agent/runs/${runID}/handoff/attachments`, options);
  }

  /**
   * 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}`.
   *
   * @example
   * ```ts
   * const response = await client.agent.runs.submitFollowup(
   *   'runId',
   *   { message: 'message' },
   * );
   * ```
   */
  submitFollowup(
    runID: string,
    body: RunSubmitFollowupParams,
    options?: RequestOptions,
  ): APIPromise<unknown> {
    return this._client.post(path`/agent/runs/${runID}/followups`, { body, ...options });
  }
}

export type RunItemsRunsCursorPage = RunsCursorPage<RunItem>;

export type ArtifactItem =
  | ArtifactItem.PlanArtifact
  | ArtifactItem.PullRequestArtifact
  | ArtifactItem.ScreenshotArtifact
  | ArtifactItem.FileArtifact;

export namespace ArtifactItem {
  export interface PlanArtifact {
    /**
     * Type of the artifact
     */
    artifact_type: 'PLAN';

    /**
     * Timestamp when the artifact was created (RFC3339)
     */
    created_at: string;

    data: PlanArtifact.Data;
  }

  export namespace PlanArtifact {
    export interface Data {
      /**
       * Unique identifier for the plan document
       */
      document_uid: string;

      /**
       * Unique identifier for the plan artifact, usable with the artifact retrieval
       * endpoint
       */
      artifact_uid?: string;

      /**
       * Unique identifier for the associated notebook
       */
      notebook_uid?: string;

      /**
       * Title of the plan
       */
      title?: string;

      /**
       * URL to open the plan in Warp Drive
       */
      url?: string;
    }
  }

  export interface PullRequestArtifact {
    /**
     * Type of the artifact
     */
    artifact_type: 'PULL_REQUEST';

    /**
     * Timestamp when the artifact was created (RFC3339)
     */
    created_at: string;

    data: PullRequestArtifact.Data;
  }

  export namespace PullRequestArtifact {
    export interface Data {
      /**
       * Branch name for the pull request
       */
      branch: string;

      /**
       * URL of the pull request
       */
      url: string;
    }
  }

  export interface ScreenshotArtifact {
    /**
     * Type of the artifact
     */
    artifact_type: 'SCREENSHOT';

    /**
     * Timestamp when the artifact was created (RFC3339)
     */
    created_at: string;

    data: ScreenshotArtifact.Data;
  }

  export namespace ScreenshotArtifact {
    export interface Data {
      /**
       * Unique identifier for the screenshot artifact
       */
      artifact_uid: string;

      /**
       * MIME type of the screenshot image
       */
      mime_type: string;

      /**
       * Optional description of the screenshot
       */
      description?: string;
    }
  }

  export interface FileArtifact {
    /**
     * Type of the artifact
     */
    artifact_type: 'FILE';

    /**
     * Timestamp when the artifact was created (RFC3339)
     */
    created_at: string;

    data: FileArtifact.Data;
  }

  export namespace FileArtifact {
    export interface Data {
      /**
       * Unique identifier for the file artifact
       */
      artifact_uid: string;

      /**
       * Last path component of filepath
       */
      filename: string;

      /**
       * Conversation-relative filepath for the uploaded file
       */
      filepath: string;

      /**
       * MIME type of the uploaded file
       */
      mime_type: string;

      /**
       * Optional description of the file
       */
      description?: string;

      /**
       * Size of the uploaded file in bytes
       */
      size_bytes?: number;
    }
  }
}

export interface RunItem {
  /**
   * Timestamp when the run was created (RFC3339)
   */
  created_at: string;

  /**
   * The prompt/instruction for the agent
   */
  prompt: string;

  /**
   * Unique identifier for the run
   */
  run_id: string;

  /**
   * Current state of the run:
   *
   * - QUEUED: Run is waiting to be picked up
   * - PENDING: Run is being prepared
   * - CLAIMED: Run has been claimed by a worker
   * - INPROGRESS: Run is actively being executed
   * - SUCCEEDED: Run completed successfully
   * - FAILED: Run failed
   * - BLOCKED: Run is blocked (e.g., awaiting user input or approval)
   * - ERROR: Run encountered an error
   * - CANCELLED: Run was cancelled by user
   */
  state: RunState;

  /**
   * @deprecated Use run_id instead.
   */
  task_id: string;

  /**
   * Human-readable title for the run
   */
  title: string;

  /**
   * Timestamp when the run was last updated (RFC3339)
   */
  updated_at: string;

  /**
   * Configuration for a cloud agent run
   */
  agent_config?: AgentAPI.AmbientAgentConfig;

  /**
   * Information about the agent skill used for the run. Either full_path or
   * bundled_skill_id will be set, but not both.
   */
  agent_skill?: RunItem.AgentSkill;

  /**
   * Artifacts created during the run (plans, pull requests, etc.)
   */
  artifacts?: Array<ArtifactItem>;

  /**
   * UUID of the conversation associated with the run
   */
  conversation_id?: string;

  creator?: AgentAPI.UserProfile;

  /**
   * Where the run executed:
   *
   * - LOCAL: Executed in the user's local Oz environment
   * - REMOTE: Executed by a remote/cloud worker
   */
  execution_location?: 'LOCAL' | 'REMOTE';

  executor?: AgentAPI.UserProfile;

  /**
   * Whether the sandbox environment is currently running
   */
  is_sandbox_running?: boolean;

  /**
   * UUID of the parent run that spawned this run
   */
  parent_run_id?: string;

  /**
   * Resource usage information for the run
   */
  request_usage?: RunItem.RequestUsage;

  /**
   * Information about the schedule that triggered this run (only present for
   * scheduled runs)
   */
  schedule?: RunItem.Schedule;

  /**
   * Ownership scope for a resource (team or personal)
   */
  scope?: AgentAPI.Scope;

  /**
   * UUID of the shared session (if available)
   */
  session_id?: string;

  /**
   * URL to view the agent session
   */
  session_link?: string;

  /**
   * Source that created the run:
   *
   * - LINEAR: Created from Linear integration
   * - API: Created via the Warp API
   * - SLACK: Created from Slack integration
   * - LOCAL: Created from local CLI/app
   * - SCHEDULED_AGENT: Created by a scheduled agent
   * - WEB_APP: Created from the Warp web app
   * - GITHUB_ACTION: Created from a GitHub action
   * - CLOUD_MODE: Created from a Cloud Mode
   * - CLI: Created from the CLI
   */
  source?: RunSourceType;

  /**
   * Timestamp when the agent started working on the run (RFC3339)
   */
  started_at?: string | null;

  /**
   * Status message for a run. For terminal error states, includes structured error
   * code and retryability info from the platform error catalog.
   */
  status_message?: RunItem.StatusMessage;

  /**
   * URL to the run trigger (e.g. Slack thread, Linear issue, schedule)
   */
  trigger_url?: string;
}

export namespace RunItem {
  /**
   * Information about the agent skill used for the run. Either full_path or
   * bundled_skill_id will be set, but not both.
   */
  export interface AgentSkill {
    /**
     * Unique identifier for bundled skills
     */
    bundled_skill_id?: string;

    /**
     * Description of the skill
     */
    description?: string;

    /**
     * Path to the SKILL.md file (for file-based skills)
     */
    full_path?: string;

    /**
     * Human-readable name of the skill
     */
    name?: string;
  }

  /**
   * Resource usage information for the run
   */
  export interface RequestUsage {
    /**
     * Cost of compute resources for the run
     */
    compute_cost?: number;

    /**
     * Cost of LLM inference for the run
     */
    inference_cost?: number;
  }

  /**
   * Information about the schedule that triggered this run (only present for
   * scheduled runs)
   */
  export interface Schedule {
    /**
     * Cron expression at the time the run was created
     */
    cron_schedule: string;

    /**
     * Unique identifier for the schedule
     */
    schedule_id: string;

    /**
     * Name of the schedule at the time the run was created
     */
    schedule_name: string;
  }

  /**
   * Status message for a run. For terminal error states, includes structured error
   * code and retryability info from the platform error catalog.
   */
  export interface StatusMessage {
    /**
     * Human-readable status message
     */
    message: string;

    /**
     * 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)
     */
    error_code?: AgentAPI.ErrorCode;

    /**
     * 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.
     */
    retryable?: boolean;
  }
}

/**
 * Source that created the run:
 *
 * - LINEAR: Created from Linear integration
 * - API: Created via the Warp API
 * - SLACK: Created from Slack integration
 * - LOCAL: Created from local CLI/app
 * - SCHEDULED_AGENT: Created by a scheduled agent
 * - WEB_APP: Created from the Warp web app
 * - GITHUB_ACTION: Created from a GitHub action
 * - CLOUD_MODE: Created from a Cloud Mode
 * - CLI: Created from the CLI
 */
export type RunSourceType =
  | 'LINEAR'
  | 'API'
  | 'SLACK'
  | 'LOCAL'
  | 'SCHEDULED_AGENT'
  | 'WEB_APP'
  | 'GITHUB_ACTION'
  | 'CLOUD_MODE'
  | 'CLI';

/**
 * Current state of the run:
 *
 * - QUEUED: Run is waiting to be picked up
 * - PENDING: Run is being prepared
 * - CLAIMED: Run has been claimed by a worker
 * - INPROGRESS: Run is actively being executed
 * - SUCCEEDED: Run completed successfully
 * - FAILED: Run failed
 * - BLOCKED: Run is blocked (e.g., awaiting user input or approval)
 * - ERROR: Run encountered an error
 * - CANCELLED: Run was cancelled by user
 */
export type RunState =
  | 'QUEUED'
  | 'PENDING'
  | 'CLAIMED'
  | 'INPROGRESS'
  | 'SUCCEEDED'
  | 'FAILED'
  | 'BLOCKED'
  | 'ERROR'
  | 'CANCELLED';

/**
 * The ID of the cancelled run
 */
export type RunCancelResponse = string;

/**
 * Response body for listing handoff snapshot attachments.
 */
export interface RunListHandoffAttachmentsResponse {
  /**
   * Handoff snapshot attachments exposed by the latest ended execution. Empty when
   * no ended execution exists or no files were uploaded.
   */
  attachments: Array<RunListHandoffAttachmentsResponse.Attachment>;
}

export namespace RunListHandoffAttachmentsResponse {
  /**
   * A handoff snapshot attachment exposed for download.
   */
  export interface Attachment {
    /**
     * Identifier for the snapshot attachment within the run.
     */
    attachment_id: string;

    /**
     * Time-limited signed URL to download the snapshot attachment.
     */
    download_url: string;

    /**
     * Original filename of the snapshot attachment.
     */
    filename: string;

    /**
     * MIME type of the snapshot attachment, if known.
     */
    mime_type?: string;
  }
}

export type RunSubmitFollowupResponse = unknown;

export interface RunListParams extends RunsCursorPageParams {
  /**
   * Filter runs by ancestor run ID. The referenced run must exist and be accessible
   * to the caller.
   */
  ancestor_run_id?: string;

  /**
   * Filter runs by artifact type
   */
  artifact_type?: 'PLAN' | 'PULL_REQUEST' | 'SCREENSHOT' | 'FILE';

  /**
   * Filter runs created after this timestamp (RFC3339 format)
   */
  created_after?: string;

  /**
   * Filter runs created before this timestamp (RFC3339 format)
   */
  created_before?: string;

  /**
   * Filter by creator UID (user or service account)
   */
  creator?: string;

  /**
   * Filter runs by environment ID
   */
  environment_id?: string;

  /**
   * Filter by where the run executed
   */
  execution_location?: 'LOCAL' | 'REMOTE';

  /**
   * 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.
   */
  executor?: string;

  /**
   * Filter by model ID
   */
  model_id?: string;

  /**
   * Filter by agent config name
   */
  name?: string;

  /**
   * Fuzzy search query across run title, prompt, and skill_spec
   */
  q?: string;

  /**
   * Filter runs by the scheduled agent ID that created them
   */
  schedule_id?: string;

  /**
   * Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for
   * skill_spec.
   */
  skill?: string;

  /**
   * Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
   */
  skill_spec?: string;

  /**
   * 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_by?: 'updated_at' | 'created_at' | 'title' | 'agent';

  /**
   * Sort direction
   */
  sort_order?: 'asc' | 'desc';

  /**
   * Filter by run source type
   */
  source?: RunSourceType;

  /**
   * Filter by run state. Can be specified multiple times to match any of the given
   * states.
   */
  state?: Array<RunState>;

  /**
   * Filter runs updated after this timestamp (RFC3339 format)
   */
  updated_after?: string;
}

export interface RunSubmitFollowupParams {
  /**
   * The follow-up message to send to the run.
   */
  message: string;

  /**
   * Optional query mode for the follow-up. Defaults to `normal` when omitted. The
   * server does not infer mode from prompt prefixes such as `/plan`.
   */
  mode?: 'normal' | 'plan' | 'orchestrate';
}

export declare namespace Runs {
  export {
    type ArtifactItem as ArtifactItem,
    type RunItem as RunItem,
    type RunSourceType as RunSourceType,
    type RunState as RunState,
    type RunCancelResponse as RunCancelResponse,
    type RunListHandoffAttachmentsResponse as RunListHandoffAttachmentsResponse,
    type RunSubmitFollowupResponse as RunSubmitFollowupResponse,
    type RunItemsRunsCursorPage as RunItemsRunsCursorPage,
    type RunListParams as RunListParams,
    type RunSubmitFollowupParams as RunSubmitFollowupParams,
  };
}