openagents_sdk::chats

Current

pub struct Current {
    pub turn: Turn,
    pub outcome: String,
    pub working: bool,
}

The latest turn in a chat, its outcome, and whether it's still working.

Event

pub enum Event {
    Text {
        request_id: String,
        index: usize,
        role: crate::MessageRole,
        text: String,
        replace: bool,
    },
    Tool {
        request_id: String,
        index: usize,
        role: crate::MessageRole,
        text: String,
        replace: bool,
    },
    Cards { request_id: String, cards: Value },
    Done { request_id: String, outcome: String, revision: u64 },
    Error { request_id: String, error: Refusal },
}

One event of a turn's stream: message text, tool output, cards, the end, or an error.

pub fn request_id(&self) -> &str

Filing

pub struct Filing {
    pub pinned: bool,
    pub archived: bool,
}

Whether a chat is pinned and archived, as the service reports it after [set_pinned] or [set_archived].

Refusal

pub struct Refusal {
    pub code: RefusalCode,
    pub message: String,
    pub retry_after_ms: Option<u64>,
}

A refused turn: its code, a message to show, and when to try again.

RefusalCode

pub enum RefusalCode {
    QuotaExhausted,
    RateLimited,
    Busy,
    Unavailable,
    Timeout,
    AccessLost,
    StreamTimeout,
    Other(String),
}

Why the service refused or ended a turn.

Send

pub struct Send {}

A retained retry identity, bound to one chat, account and deployment.

pub fn new(chat: ChatRef, text: String) -> Result<Self, Error>

pub fn first(client: &Client, session: &Session, text: String) -> Result<Self, Error>

pub fn with_id(chat: ChatRef, request_id: String, text: String) -> Result<Self, Error>

pub fn turn(&self) -> Turn

pub fn request_id(&self) -> &str

pub fn chat(&self) -> &ChatRef

pub fn text(&self) -> &str

Stopped

pub struct Stopped {
    pub request_id: String,
    pub stopped: bool,
    pub finished: bool,
}

The service's answer to a stop request.

Stream

pub struct Stream {}

The events of one turn, read in order with [Stream::next].

pub async fn next(&mut self) -> Result<Option<Event>, Error>

Turn

pub struct Turn {}

A cloud turn in one account chat, including turns started on another device.

pub fn new(chat: ChatRef, request_id: String) -> Result<Self, Error>

pub fn chat(&self) -> &ChatRef

pub fn request_id(&self) -> &str

current

pub async fn current(
    client: &Client,
    session: &Session,
    chat: &ChatRef,
    cancel: &CancellationToken,
) -> Result<Option<Current>, Error>

Find the latest turn, including a turn sent from the web or another app.

Calls GET /v1/threads/{id}

send

pub async fn send(
    client: &Client,
    session: &Session,
    message: &Send,
    cancel: &CancellationToken,
) -> Result<(), Error>

Submit the retained message. Cancellation can leave an accepted turn; retry this same Send.

Calls POST /v1/threads/{id}/messages

set_archived

pub async fn set_archived(
    client: &Client,
    session: &Session,
    chat: &ChatRef,
    archived: bool,
    cancel: &CancellationToken,
) -> Result<Filing, Error>

Archive the chat (true) or restore it (false), as the web's sidebar does (PATCH /v1/threads/{id}). Archiving also removes the cloud computers that ran it. Repeating the call changes nothing more.

set_pinned

pub async fn set_pinned(
    client: &Client,
    session: &Session,
    chat: &ChatRef,
    pinned: bool,
    cancel: &CancellationToken,
) -> Result<Filing, Error>

Pin the chat (true) or unpin it (false), as the web's sidebar does (PATCH /v1/threads/{id}). A new pin goes after every earlier one. Repeating the call changes nothing more.

start

pub async fn start(
    client: &Client,
    session: &Session,
    message: &Send,
    cancel: &CancellationToken,
) -> Result<(), Error>

Start the new chat [Send::first] made (POST /v1/threads). Retrying the same Send after an uncertain response starts it once.

Calls POST /v1/threads

stop

pub async fn stop(
    client: &Client,
    session: &Session,
    message: &Turn,
    cancel: &CancellationToken,
) -> Result<Stopped, Error>

Stop this request only. A late stop never cancels a newer turn.

Calls POST /v1/threads/{id}/stop

stream

pub async fn stream(
    client: &Client,
    session: &Session,
    message: &Turn,
    cancel: &CancellationToken,
) -> Result<Stream, Error>

Reconnecting starts with replacements of the current request's messages, then deltas. Apply by message index; never append a replacement twice.