uarp-sdk 0.5.7

// Code generated by @uarp/codegen from spec/openapi.json. DO NOT EDIT.
//!
//! Agent execution runs, SSE streaming, HITL, continuation

#![allow(unused_imports, clippy::too_many_arguments)]

use reqwest::Method;
use serde::{Deserialize, Serialize};
use futures_core::Stream;

use crate::client::{Client, Request, NO_BODY, NO_QUERY};
use crate::error::Result;
use crate::generated::models;
use crate::multipart::{field_text, FilePart};
use crate::pagination::CursorGuard;
use crate::sse::EventStream;
use crate::util::encode_path;

/// Query and header parameters for `getRunFeedback`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct GetRunFeedbackParams {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub message_id: Option<String>,
}

/// Query and header parameters for `listRuns`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ListRunsParams {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub agent_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
}

/// Query and header parameters for `streamRunEvents`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct StreamRunEventsParams {
    /// Short-lived SSE/WebSocket token (mint via `POST /api/v1/auth/sse-tokens`) or full API key.
    /// Used by browser EventSource which cannot set Authorization header.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
    /// SSE resumption cursor. The browser's EventSource sets this automatically on reconnect;
    /// servers replay events strictly after this id.
    #[serde(skip)]
    pub last_event_id: Option<String>,
}

/// Query and header parameters for `waitRun`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct WaitRunParams {
    /// Max seconds to wait. Default from server config (e.g. 60).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_sec: Option<i64>,
}

/// Agent execution runs, SSE streaming, HITL, continuation
#[derive(Debug, Clone)]
pub struct RunsApi {
    pub(crate) client: Client,
}

impl Client {
    /// Agent execution runs, SSE streaming, HITL, continuation
    pub fn runs(&self) -> RunsApi {
        RunsApi { client: self.clone() }
    }
}

impl RunsApi {
    /// Approve a pending tool call (HITL)
    ///
    /// `POST /api/v1/runs/{runId}/approve`
    ///
    /// Required scopes: `runs:create`.
    pub async fn approve_run(&self, run_id: &str) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/approve", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Cancel a run
    ///
    /// `POST /api/v1/runs/{runId}/cancel`
    ///
    /// Required scopes: `runs:create`.
    pub async fn cancel(&self, run_id: &str) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/cancel", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Continue a run from a continuation token
    ///
    /// Decodes the token, loads the checkpoint, and re-schedules the run.
    ///
    /// `POST /api/v1/runs/{runId}/continue`
    ///
    /// Required scopes: `runs:create`.
    pub async fn continue_run(&self, run_id: &str, body: &models::ContinueRunRequest) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/continue", encode_path(run_id)),
                query: NO_QUERY,
                body: Some(body),
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Create and schedule a run
    ///
    /// Creates a run and schedules it for execution. Recommended: send Idempotency-Key header to
    /// avoid duplicate runs on retries; a repeated request with the same key returns the cached 202
    /// response (same run_id). Pin a specific agent version with `version` to bypass the head
    /// pointer.
    ///
    /// `POST /api/v1/runs`
    ///
    /// Required scopes: `runs:create`.
    pub async fn create(&self, body: &models::CreateRunRequest) -> Result<models::Run> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: "/api/v1/runs".to_string(),
                query: NO_QUERY,
                body: Some(body),
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Create checkpoint for a run
    ///
    /// `POST /api/v1/runs/{runId}/checkpoint`
    ///
    /// Required scopes: `runs:create`.
    pub async fn create_run_checkpoint(&self, run_id: &str) -> Result<serde_json::Map<String, serde_json::Value>> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/checkpoint", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Export run events as JSONL
    ///
    /// `GET /api/v1/runs/{runId}/events/export`
    ///
    /// Required scopes: `runs:read`.
    pub async fn export_run_events(&self, run_id: &str) -> Result<String> {
        self.client
            .request_text(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/events/export", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// Get run status and result
    ///
    /// `GET /api/v1/runs/{runId}`
    ///
    /// Required scopes: `runs:read`.
    pub async fn get(&self, run_id: &str) -> Result<models::Run> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// Get audit trail for a run
    ///
    /// `GET /api/v1/runs/{runId}/audit-log`
    ///
    /// Required scopes: `runs:read`.
    pub async fn get_run_audit_log(&self, run_id: &str) -> Result<serde_json::Map<String, serde_json::Value>> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/audit-log", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// Get user feedback for a run
    ///
    /// `GET /api/v1/runs/{runId}/feedback`
    ///
    /// Required scopes: `runs:read`.
    pub async fn get_run_feedback(&self, run_id: &str, params: &GetRunFeedbackParams) -> Result<serde_json::Map<String, serde_json::Value>> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/feedback", encode_path(run_id)),
                query: Some(params),
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// Get run queue position
    ///
    /// `GET /api/v1/runs/{runId}/queue-position`
    ///
    /// Required scopes: `runs:read`.
    pub async fn get_run_queue_position(&self, run_id: &str) -> Result<models::GetRunQueuePositionResponse> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/queue-position", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// List steps for a run
    ///
    /// Returns the ordered list of steps executed during a run, with per-step metrics including
    /// tokens, cost, and tool calls.
    ///
    /// `GET /api/v1/runs/{runId}/steps`
    ///
    /// Required scopes: `runs:read`.
    pub async fn get_run_steps(&self, run_id: &str) -> Result<models::GetRunStepsResponse> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/steps", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// List all runs for tenant
    ///
    /// `GET /api/v1/runs`
    ///
    /// Required scopes: `runs:read`.
    pub async fn list(&self, params: &ListRunsParams) -> Result<models::ListRunsResponse> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: "/api/v1/runs".to_string(),
                query: Some(params),
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// Stream every item returned by `listRuns`, following the `cursor` cursor until the server
    /// reports no further pages.
    pub fn list_all<'a>(&'a self, params: &'a ListRunsParams) -> impl Stream<Item = Result<serde_json::Map<String, serde_json::Value>>> + 'a {
        async_stream::try_stream! {
            let mut guard = CursorGuard::new();
            let mut cursor = params.cursor.clone();
            loop {
                let mut page_params = params.clone();
                page_params.cursor = cursor.clone();
                let page = self.list(&page_params).await?;
                let items = page.items.unwrap_or_default();
                let was_empty = items.is_empty();
                for item in items {
                    yield item;
                }
                match guard.advance(page.cursor, page.has_more, was_empty) {
                    Some(next) => cursor = Some(next),
                    None => break,
                }
            }
        }
    }

    /// List run artifacts
    ///
    /// `GET /api/v1/runs/{runId}/artifacts`
    ///
    /// Required scopes: `runs:read`.
    pub async fn list_run_artifacts(&self, run_id: &str) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/artifacts", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// List checkpoints for a run
    ///
    /// `GET /api/v1/runs/{runId}/checkpoints`
    ///
    /// Required scopes: `runs:read`.
    pub async fn list_run_checkpoints(&self, run_id: &str) -> Result<models::ListRunCheckpointsResponse> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/checkpoints", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }

    /// Pause a run
    ///
    /// `POST /api/v1/runs/{runId}/pause`
    ///
    /// Required scopes: `runs:create`.
    pub async fn pause_run(&self, run_id: &str) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/pause", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Reject a pending tool call (HITL)
    ///
    /// `POST /api/v1/runs/{runId}/reject`
    ///
    /// Required scopes: `runs:create`.
    pub async fn reject_run(&self, run_id: &str, body: &models::RejectRunRequest) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/reject", encode_path(run_id)),
                query: NO_QUERY,
                body: Some(body),
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Replay a run for determinism check
    ///
    /// `POST /api/v1/runs/{runId}/replay`
    ///
    /// Required scopes: `runs:read`.
    pub async fn replay_run(&self, run_id: &str) -> Result<serde_json::Map<String, serde_json::Value>> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/replay", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Send user input response to a paused run
    ///
    /// `POST /api/v1/runs/{runId}/respond`
    ///
    /// Required scopes: `runs:create`.
    pub async fn respond_to_run(&self, run_id: &str, body: &models::RespondToRunRequest) -> Result<models::RespondToRunResponse> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/respond", encode_path(run_id)),
                query: NO_QUERY,
                body: Some(body),
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Resume a run
    ///
    /// `POST /api/v1/runs/{runId}/resume`
    ///
    /// Required scopes: `runs:create`.
    pub async fn resume(&self, run_id: &str) -> Result<serde_json::Value> {
        self.client
            .request_json(Request {
                method: Method::POST,
                path: format!("/api/v1/runs/{}/resume", encode_path(run_id)),
                query: NO_QUERY,
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Save user feedback/reaction for a run
    ///
    /// `PUT /api/v1/runs/{runId}/feedback`
    ///
    /// Required scopes: `runs:create`.
    pub async fn set_run_feedback(&self, run_id: &str, body: &serde_json::Map<String, serde_json::Value>) -> Result<serde_json::Map<String, serde_json::Value>> {
        self.client
            .request_json(Request {
                method: Method::PUT,
                path: format!("/api/v1/runs/{}/feedback", encode_path(run_id)),
                query: NO_QUERY,
                body: Some(body),
                headers: Vec::new(),
                idempotent: true,
            })
            .await
    }

    /// Stream run events via SSE
    ///
    /// Real-time event stream for a run. Supports `Last-Event-ID` header (or `?last_event_id=`) for
    /// reconnection. Stream closes when run reaches terminal status. Each event payload includes
    /// `stream_type`: lifecycle (run.*), assistant (llm.chunk), tool (tool.*), or other — use it to
    /// filter client-side. Browsers using EventSource (which cannot set Authorization headers)
    /// should mint a 60-s SSE token via `POST /api/v1/auth/sse-tokens` and pass it as `?token=`.
    ///
    /// `GET /api/v1/runs/{runId}/events`
    ///
    /// Required scopes: `events:read`.
    ///
    /// Returns a server-sent event stream.
    pub fn stream_run_events(&self, run_id: &str, params: &StreamRunEventsParams) -> EventStream {
        let mut headers: Vec<(&'static str, String)> = Vec::new();
        if let Some(value) = &params.last_event_id {
            headers.push(("Last-Event-ID", value.clone()));
        }
        self.client.request_stream(
            &format!("/api/v1/runs/{}/events", encode_path(run_id)),
            Some(params),
            headers,
        )
    }

    /// Wait for run to reach terminal status
    ///
    /// If the run is already completed, failed, cancelled, timeout, or guardrail_blocked, returns
    /// 200 with the run immediately. Otherwise polls until terminal status or timeout_sec. On
    /// timeout returns 202 with status still_running.
    ///
    /// `GET /api/v1/runs/{runId}/wait`
    ///
    /// Required scopes: `runs:read`.
    pub async fn wait_run(&self, run_id: &str, params: &WaitRunParams) -> Result<models::Run> {
        self.client
            .request_json(Request {
                method: Method::GET,
                path: format!("/api/v1/runs/{}/wait", encode_path(run_id)),
                query: Some(params),
                body: NO_BODY,
                headers: Vec::new(),
                idempotent: false,
            })
            .await
    }
}