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

import { APIResource } from '../core/resource';
import * as AgentsAPI from './agents';
import * as Shared from './shared';
import { APIPromise } from '../core/api-promise';
import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
import { buildHeaders } from '../internal/headers';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

export class WorkflowRuns extends APIResource {
  /**
   * Get details of a specific workflow run including its full state.
   */
  retrieve(runID: string, options?: RequestOptions): APIPromise<WorkflowRun> {
    return this._client.get(path`/workflow-runs/${runID}`, options);
  }

  /**
   * List workflow runs for the project with optional filtering.
   *
   * **Filters:**
   *
   * - `agent_name`: Filter by agent name
   * - `status`: Filter by run status (running, paused, completed, failed)
   * - `identity.*`: Filter by identity fields (e.g., identity.user_id=user_123)
   */
  list(
    query: WorkflowRunListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<WorkflowRunsCursor, WorkflowRun> {
    return this._client.getAPIList('/workflow-runs', Cursor<WorkflowRun>, { query, ...options });
  }

  /**
   * Delete a workflow run. This action cannot be undone.
   */
  delete(runID: string, options?: RequestOptions): APIPromise<void> {
    return this._client.delete(path`/workflow-runs/${runID}`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * Resume a paused workflow run by providing the required action response.
   *
   * **Input:** Pass the action response (e.g. `{ approved: true }` for an approval
   * step). The run must be in `paused` status to be resumed.
   */
  resume(
    runID: string,
    body: WorkflowRunResumeParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<WorkflowRunResumeResponse> {
    return this._client.post(path`/workflow-runs/${runID}/resume`, { body, ...options });
  }
}

export type WorkflowRunsCursor = Cursor<WorkflowRun>;

export interface WorkflowRun {
  /**
   * Unique workflow run ID
   */
  id: string;

  /**
   * Agent name
   */
  agentName: string;

  /**
   * Execution context
   */
  context: { [key: string]: unknown } | null;

  /**
   * When the run was created
   */
  createdAt: string;

  /**
   * Identity fields for run scoping
   */
  identity: { [key: string]: unknown };

  /**
   * Original workflow input
   */
  input: { [key: string]: unknown };

  /**
   * Pending action when paused
   */
  pendingAction: { [key: string]: unknown } | null;

  /**
   * Project ID
   */
  projectId: string;

  /**
   * Full workflow state
   */
  state: { [key: string]: unknown } | null;

  /**
   * Workflow run status
   */
  status: 'running' | 'paused' | 'completed' | 'failed';

  /**
   * When the run was last updated
   */
  updatedAt: string;
}

export interface WorkflowRunResumeResponse {
  /**
   * Workflow run ID
   */
  run_id: string;

  /**
   * Full workflow state (steps, result, etc.)
   */
  state: { [key: string]: unknown };

  /**
   * Workflow run status
   */
  status: string;

  /**
   * Execution reference for tracking
   */
  execution?: AgentsAPI.ExecutionRef;

  /**
   * Pending action details when paused
   */
  pendingAction?: { [key: string]: unknown } | null;
}

export interface WorkflowRunListParams extends CursorParams {
  /**
   * Filter by agent name
   */
  agent_name?: string;

  /**
   * Filter by run status
   */
  status?: 'running' | 'paused' | 'completed' | 'failed';
}

export interface WorkflowRunResumeParams {
  /**
   * Optional context: identity (conversation scoping), attributes (injected into
   * system prompt), and pass-through for tools
   */
  context?: Shared.Context;

  /**
   * Action response input (e.g. { approved: true })
   */
  input?: { [key: string]: unknown };

  /**
   * Enable streaming response (SSE)
   */
  stream?: boolean;
}

export declare namespace WorkflowRuns {
  export {
    type WorkflowRun as WorkflowRun,
    type WorkflowRunResumeResponse as WorkflowRunResumeResponse,
    type WorkflowRunsCursor as WorkflowRunsCursor,
    type WorkflowRunListParams as WorkflowRunListParams,
    type WorkflowRunResumeParams as WorkflowRunResumeParams,
  };
}