use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex, RwLock};
use std::task::{Context, Poll};
use std::time::Duration;
use futures_core::Stream;
use serde::Deserialize;
use serde_json::{Map, Value, json};
use tokio::sync::Mutex as AsyncMutex;
use tokio_stream::StreamExt;
use tokio_stream::wrappers::UnboundedReceiverStream;
use crate::config::CodexConfig;
use crate::error::{Error, Result, is_retryable_error};
use crate::options::{
ThreadForkOptions, ThreadListOptions, ThreadResumeOptions, ThreadStartOptions, TurnOptions,
apply_approval_mode, apply_sandbox_mode, apply_sandbox_policy, serialize_options,
};
use crate::transport::{NotificationReceiver, Transport};
use crate::types::{
AccountLoginCompletedNotification, CancelLoginAccountResponse, GetAccountResponse,
InitializeResponse, Input, ModelListResponse, Notification, NotificationPayload, RetryPolicy,
ServerInfo, ThreadArchiveResponse, ThreadCompactStartResponse, ThreadData, ThreadListResponse,
ThreadReadResponse, ThreadSetNameResponse, Turn, TurnInterruptResponse, TurnResult,
TurnSteerResponse,
};
#[derive(Debug, Default)]
struct ClientState {
transport: RwLock<Option<Transport>>,
metadata: RwLock<Option<InitializeResponse>>,
initialize_lock: AsyncMutex<()>,
}
#[derive(Clone, Debug)]
pub struct AsyncCodex {
config: Arc<CodexConfig>,
state: Arc<ClientState>,
}
impl AsyncCodex {
pub fn new(config: CodexConfig) -> Self {
Self {
config: Arc::new(config),
state: Arc::new(ClientState::default()),
}
}
pub fn with_defaults() -> Self {
Self::new(CodexConfig::default())
}
pub async fn connect(config: CodexConfig) -> Result<Self> {
let client = Self::new(config);
client.start().await?;
Ok(client)
}
pub async fn start(&self) -> Result<()> {
self.transport().await.map(|_| ())
}
pub fn metadata(&self) -> Result<InitializeResponse> {
self.state
.metadata
.read()
.expect("metadata lock poisoned")
.clone()
.ok_or_else(|| {
Error::InvalidConfiguration(
"AsyncCodex is not initialized; call start() or an API method first".into(),
)
})
}
pub async fn close(&self) -> Result<()> {
let _initializing = self.state.initialize_lock.lock().await;
let transport = self
.state
.transport
.write()
.expect("transport lock poisoned")
.take();
self.state
.metadata
.write()
.expect("metadata lock poisoned")
.take();
if let Some(transport) = transport {
transport.close().await?;
}
Ok(())
}
pub async fn login_api_key(&self, api_key: impl Into<String>) -> Result<()> {
let _: LoginStartResponse = self
.request(
"account/login/start",
Some(json!({"type": "apiKey", "apiKey": api_key.into()})),
)
.await?;
Ok(())
}
pub async fn login_chatgpt(&self) -> Result<AsyncChatgptLoginHandle> {
let response: LoginStartResponse = self
.request("account/login/start", Some(json!({"type": "chatgpt"})))
.await?;
let LoginStartResponse::Chatgpt { login_id, auth_url } = response else {
return Err(Error::InvalidResponse {
method: "account/login/start",
message: format!("expected chatgpt response, got {response:?}"),
});
};
let receiver = self.transport().await?.subscribe_login(&login_id)?;
Ok(AsyncChatgptLoginHandle {
codex: self.clone(),
login_id,
auth_url,
receiver: Mutex::new(Some(receiver)),
})
}
pub async fn login_chatgpt_device_code(&self) -> Result<AsyncDeviceCodeLoginHandle> {
let response: LoginStartResponse = self
.request(
"account/login/start",
Some(json!({"type": "chatgptDeviceCode"})),
)
.await?;
let LoginStartResponse::ChatgptDeviceCode {
login_id,
verification_url,
user_code,
} = response
else {
return Err(Error::InvalidResponse {
method: "account/login/start",
message: format!("expected chatgptDeviceCode response, got {response:?}"),
});
};
let receiver = self.transport().await?.subscribe_login(&login_id)?;
Ok(AsyncDeviceCodeLoginHandle {
codex: self.clone(),
login_id,
verification_url,
user_code,
receiver: Mutex::new(Some(receiver)),
})
}
pub async fn account(&self) -> Result<GetAccountResponse> {
self.account_with_refresh(false).await
}
pub async fn account_with_refresh(&self, refresh_token: bool) -> Result<GetAccountResponse> {
self.request("account/read", Some(json!({"refreshToken": refresh_token})))
.await
}
pub async fn logout(&self) -> Result<()> {
let _: EmptyObject = self.request("account/logout", None).await?;
Ok(())
}
pub async fn thread_start(&self) -> Result<AsyncThread> {
self.thread_start_with(&ThreadStartOptions::default()).await
}
pub async fn thread_start_with(&self, options: &ThreadStartOptions) -> Result<AsyncThread> {
let mut params = serialize_options(options)?;
apply_approval_mode(&mut params, Some(options.approval_mode));
apply_sandbox_mode(&mut params, options.sandbox);
let response: ThreadEnvelope = self
.request("thread/start", Some(Value::Object(params)))
.await?;
Ok(AsyncThread {
codex: self.clone(),
id: response.thread.id,
})
}
pub async fn thread_list(&self) -> Result<ThreadListResponse> {
self.thread_list_with(&ThreadListOptions::default()).await
}
pub async fn thread_list_with(
&self,
options: &ThreadListOptions,
) -> Result<ThreadListResponse> {
self.request(
"thread/list",
Some(Value::Object(serialize_options(options)?)),
)
.await
}
pub async fn thread_resume(&self, thread_id: impl Into<String>) -> Result<AsyncThread> {
self.thread_resume_with(thread_id, &ThreadResumeOptions::default())
.await
}
pub async fn thread_resume_with(
&self,
thread_id: impl Into<String>,
options: &ThreadResumeOptions,
) -> Result<AsyncThread> {
let mut params = serialize_options(options)?;
apply_approval_mode(&mut params, options.approval_mode);
apply_sandbox_mode(&mut params, options.sandbox);
params.insert("threadId".into(), Value::String(thread_id.into()));
let response: ThreadEnvelope = self
.request("thread/resume", Some(Value::Object(params)))
.await?;
Ok(AsyncThread {
codex: self.clone(),
id: response.thread.id,
})
}
pub async fn thread_fork(&self, thread_id: impl Into<String>) -> Result<AsyncThread> {
self.thread_fork_with(thread_id, &ThreadForkOptions::default())
.await
}
pub async fn thread_fork_with(
&self,
thread_id: impl Into<String>,
options: &ThreadForkOptions,
) -> Result<AsyncThread> {
let mut params = serialize_options(options)?;
apply_approval_mode(&mut params, options.approval_mode);
apply_sandbox_mode(&mut params, options.sandbox);
params.insert("threadId".into(), Value::String(thread_id.into()));
let response: ThreadEnvelope = self
.request("thread/fork", Some(Value::Object(params)))
.await?;
Ok(AsyncThread {
codex: self.clone(),
id: response.thread.id,
})
}
pub async fn thread_archive(
&self,
thread_id: impl Into<String>,
) -> Result<ThreadArchiveResponse> {
self.request(
"thread/archive",
Some(json!({"threadId": thread_id.into()})),
)
.await
}
pub async fn thread_unarchive(&self, thread_id: impl Into<String>) -> Result<AsyncThread> {
let response: ThreadEnvelope = self
.request(
"thread/unarchive",
Some(json!({"threadId": thread_id.into()})),
)
.await?;
Ok(AsyncThread {
codex: self.clone(),
id: response.thread.id,
})
}
pub async fn models(&self) -> Result<ModelListResponse> {
self.models_including_hidden(false).await
}
pub async fn models_including_hidden(&self, include_hidden: bool) -> Result<ModelListResponse> {
self.request("model/list", Some(json!({"includeHidden": include_hidden})))
.await
}
pub async fn next_notification(&self) -> Result<Notification> {
self.transport().await?.next_global_notification().await
}
async fn request<T: serde::de::DeserializeOwned>(
&self,
method: &'static str,
params: Option<Value>,
) -> Result<T> {
self.transport().await?.request(method, params).await
}
async fn transport(&self) -> Result<Transport> {
if let Some(transport) = self
.state
.transport
.read()
.expect("transport lock poisoned")
.clone()
{
return Ok(transport);
}
let _initializing = self.state.initialize_lock.lock().await;
if let Some(transport) = self
.state
.transport
.read()
.expect("transport lock poisoned")
.clone()
{
return Ok(transport);
}
let transport = Transport::start(&self.config)?;
let initialized = async {
let metadata: InitializeResponse = transport
.request(
"initialize",
Some(json!({
"clientInfo": {
"name": self.config.client_name,
"title": self.config.client_title,
"version": self.config.client_version,
},
"capabilities": {
"experimentalApi": self.config.experimental_api,
},
})),
)
.await?;
transport.notify("initialized", None).await?;
validate_initialize_metadata(metadata)
}
.await;
match initialized {
Ok(metadata) => {
*self.state.metadata.write().expect("metadata lock poisoned") = Some(metadata);
*self
.state
.transport
.write()
.expect("transport lock poisoned") = Some(transport.clone());
Ok(transport)
}
Err(error) => {
let _ = transport.close().await;
Err(error)
}
}
}
}
impl Default for AsyncCodex {
fn default() -> Self {
Self::with_defaults()
}
}
#[derive(Clone, Debug)]
pub struct AsyncThread {
codex: AsyncCodex,
pub id: String,
}
impl AsyncThread {
pub async fn run(&self, input: impl Into<Input>) -> Result<TurnResult> {
self.run_with(input, &TurnOptions::default()).await
}
pub async fn run_with(
&self,
input: impl Into<Input>,
options: &TurnOptions,
) -> Result<TurnResult> {
self.turn_with(input, options).await?.run().await
}
pub async fn turn(&self, input: impl Into<Input>) -> Result<AsyncTurnHandle> {
self.turn_with(input, &TurnOptions::default()).await
}
pub async fn turn_with(
&self,
input: impl Into<Input>,
options: &TurnOptions,
) -> Result<AsyncTurnHandle> {
let transport = self.codex.transport().await?;
let mut params = serialize_options(options)?;
apply_approval_mode(&mut params, options.approval_mode);
apply_sandbox_policy(&mut params, options.sandbox);
params.insert("threadId".into(), Value::String(self.id.clone()));
params.insert("input".into(), serde_json::to_value(input.into())?);
let response: TurnStartResponse = transport
.request("turn/start", Some(Value::Object(params)))
.await?;
let receiver = transport.subscribe_turn(&response.turn.id)?;
Ok(AsyncTurnHandle {
codex: self.codex.clone(),
thread_id: self.id.clone(),
id: response.turn.id,
receiver: Mutex::new(Some(receiver)),
})
}
pub async fn read(&self) -> Result<ThreadReadResponse> {
self.read_with_turns(false).await
}
pub async fn read_with_turns(&self, include_turns: bool) -> Result<ThreadReadResponse> {
self.codex
.request(
"thread/read",
Some(json!({"threadId": self.id, "includeTurns": include_turns})),
)
.await
}
pub async fn set_name(&self, name: impl Into<String>) -> Result<ThreadSetNameResponse> {
self.codex
.request(
"thread/name/set",
Some(json!({"threadId": self.id, "name": name.into()})),
)
.await
}
pub async fn compact(&self) -> Result<ThreadCompactStartResponse> {
self.codex
.request("thread/compact/start", Some(json!({"threadId": self.id})))
.await
}
}
#[derive(Debug)]
pub struct AsyncTurnHandle {
codex: AsyncCodex,
pub thread_id: String,
pub id: String,
receiver: Mutex<Option<NotificationReceiver>>,
}
impl AsyncTurnHandle {
pub async fn steer(&self, input: impl Into<Input>) -> Result<TurnSteerResponse> {
self.codex
.request(
"turn/steer",
Some(json!({
"threadId": self.thread_id,
"expectedTurnId": self.id,
"input": input.into(),
})),
)
.await
}
pub async fn interrupt(&self) -> Result<TurnInterruptResponse> {
self.codex
.request(
"turn/interrupt",
Some(json!({"threadId": self.thread_id, "turnId": self.id})),
)
.await
}
pub fn stream(&self) -> Result<TurnStream> {
let receiver = self
.receiver
.lock()
.expect("turn receiver lock poisoned")
.take()
.ok_or(Error::StreamConsumed)?;
let transport = self
.codex
.state
.transport
.read()
.expect("transport lock poisoned")
.clone()
.ok_or_else(|| Error::TransportClosed("client is not running".into()))?;
Ok(TurnStream {
receiver: UnboundedReceiverStream::new(receiver),
transport,
turn_id: self.id.clone(),
completed: false,
})
}
pub async fn run(&self) -> Result<TurnResult> {
let mut stream = self.stream()?;
let mut events = Vec::new();
while let Some(event) = stream.next().await {
events.push(event?);
}
TurnResult::from_events(&self.id, events)
}
}
impl Drop for AsyncTurnHandle {
fn drop(&mut self) {
let receiver_is_pending = self
.receiver
.get_mut()
.expect("turn receiver lock poisoned")
.is_some();
if receiver_is_pending {
if let Some(transport) = self
.codex
.state
.transport
.read()
.expect("transport lock poisoned")
.as_ref()
{
transport.unsubscribe_turn(&self.id);
}
}
}
}
#[derive(Debug)]
pub struct TurnStream {
receiver: UnboundedReceiverStream<Result<Notification>>,
transport: Transport,
turn_id: String,
completed: bool,
}
impl Stream for TurnStream {
type Item = Result<Notification>;
fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
if self.completed {
return Poll::Ready(None);
}
match Pin::new(&mut self.receiver).poll_next(context) {
Poll::Ready(Some(Ok(notification))) => {
if matches!(
¬ification.payload,
NotificationPayload::TurnCompleted(value) if value.turn.id == self.turn_id
) {
self.completed = true;
}
Poll::Ready(Some(Ok(notification)))
}
value => value,
}
}
}
impl Drop for TurnStream {
fn drop(&mut self) {
self.transport.unsubscribe_turn(&self.turn_id);
}
}
#[derive(Debug)]
pub struct AsyncChatgptLoginHandle {
codex: AsyncCodex,
pub login_id: String,
pub auth_url: String,
receiver: Mutex<Option<NotificationReceiver>>,
}
impl AsyncChatgptLoginHandle {
pub async fn wait(&self) -> Result<AccountLoginCompletedNotification> {
wait_for_login(&self.codex, &self.login_id, &self.receiver).await
}
pub async fn cancel(&self) -> Result<CancelLoginAccountResponse> {
let response = self
.codex
.request(
"account/login/cancel",
Some(json!({"loginId": self.login_id})),
)
.await?;
unsubscribe_login(&self.codex, &self.login_id);
Ok(response)
}
}
impl Drop for AsyncChatgptLoginHandle {
fn drop(&mut self) {
unsubscribe_login_if_pending(&self.codex, &self.login_id, &mut self.receiver);
}
}
#[derive(Debug)]
pub struct AsyncDeviceCodeLoginHandle {
codex: AsyncCodex,
pub login_id: String,
pub verification_url: String,
pub user_code: String,
receiver: Mutex<Option<NotificationReceiver>>,
}
impl AsyncDeviceCodeLoginHandle {
pub async fn wait(&self) -> Result<AccountLoginCompletedNotification> {
wait_for_login(&self.codex, &self.login_id, &self.receiver).await
}
pub async fn cancel(&self) -> Result<CancelLoginAccountResponse> {
let response = self
.codex
.request(
"account/login/cancel",
Some(json!({"loginId": self.login_id})),
)
.await?;
unsubscribe_login(&self.codex, &self.login_id);
Ok(response)
}
}
impl Drop for AsyncDeviceCodeLoginHandle {
fn drop(&mut self) {
unsubscribe_login_if_pending(&self.codex, &self.login_id, &mut self.receiver);
}
}
async fn wait_for_login(
codex: &AsyncCodex,
login_id: &str,
receiver: &Mutex<Option<NotificationReceiver>>,
) -> Result<AccountLoginCompletedNotification> {
let _subscription = LoginSubscription::new(codex, login_id);
let mut receiver = receiver
.lock()
.expect("login receiver lock poisoned")
.take()
.ok_or(Error::StreamConsumed)?;
while let Some(event) = receiver.recv().await {
let event = event?;
if let NotificationPayload::AccountLoginCompleted(completed) = event.payload {
if completed.login_id.as_deref() == Some(login_id) {
return Ok(completed);
}
}
}
Err(Error::TransportClosed(
"login notification stream stopped".into(),
))
}
struct LoginSubscription {
transport: Option<Transport>,
login_id: String,
}
impl LoginSubscription {
fn new(codex: &AsyncCodex, login_id: &str) -> Self {
Self {
transport: codex
.state
.transport
.read()
.expect("transport lock poisoned")
.clone(),
login_id: login_id.to_owned(),
}
}
}
impl Drop for LoginSubscription {
fn drop(&mut self) {
if let Some(transport) = &self.transport {
transport.unsubscribe_login(&self.login_id);
}
}
}
fn unsubscribe_login(codex: &AsyncCodex, login_id: &str) {
if let Some(transport) = codex
.state
.transport
.read()
.expect("transport lock poisoned")
.as_ref()
{
transport.unsubscribe_login(login_id);
}
}
fn unsubscribe_login_if_pending(
codex: &AsyncCodex,
login_id: &str,
receiver: &mut Mutex<Option<NotificationReceiver>>,
) {
let receiver_is_pending = receiver
.get_mut()
.expect("login receiver lock poisoned")
.is_some();
if receiver_is_pending {
unsubscribe_login(codex, login_id);
}
}
pub async fn retry_on_overload<T, F, Fut>(policy: RetryPolicy, mut operation: F) -> Result<T>
where
F: FnMut() -> Fut,
Fut: Future<Output = Result<T>>,
{
if policy.max_attempts == 0 {
return Err(Error::InvalidConfiguration(
"max_attempts must be at least 1".into(),
));
}
let mut delay = policy.initial_delay;
for attempt in 1..=policy.max_attempts {
match operation().await {
Ok(value) => return Ok(value),
Err(error) if attempt < policy.max_attempts && is_retryable_error(&error) => {
let capped = delay.min(policy.max_delay);
let jitter = capped.as_secs_f64()
* policy.jitter_ratio
* (rand::random::<f64>() * 2.0 - 1.0);
let sleep = (capped.as_secs_f64() + jitter).max(0.0);
if sleep > 0.0 {
tokio::time::sleep(Duration::from_secs_f64(sleep)).await;
}
delay = (delay * 2).min(policy.max_delay);
}
Err(error) => return Err(error),
}
}
unreachable!("nonzero retry policy always returns from the loop")
}
fn validate_initialize_metadata(mut response: InitializeResponse) -> Result<InitializeResponse> {
let user_agent = response.user_agent.as_deref().unwrap_or("").trim();
let mut server_name = response
.server_info
.as_ref()
.and_then(|server| server.name.as_deref())
.map(str::trim)
.filter(|value| !value.is_empty());
let mut server_version = response
.server_info
.as_ref()
.and_then(|server| server.version.as_deref())
.map(str::trim)
.filter(|value| !value.is_empty());
let parsed = split_user_agent(user_agent);
server_name = server_name.or(parsed.0.as_deref());
server_version = server_version.or(parsed.1.as_deref());
if user_agent.is_empty() || server_name.is_none() || server_version.is_none() {
return Err(Error::InvalidResponse {
method: "initialize",
message: format!(
"missing required metadata (user_agent={user_agent:?}, server_name={server_name:?}, server_version={server_version:?})"
),
});
}
response.server_info = Some(ServerInfo {
name: server_name.map(str::to_owned),
version: server_version.map(str::to_owned),
});
Ok(response)
}
fn split_user_agent(user_agent: &str) -> (Option<String>, Option<String>) {
let user_agent = user_agent.trim();
if user_agent.is_empty() {
return (None, None);
}
if let Some((name, version)) = user_agent.split_once('/') {
return (
(!name.is_empty()).then(|| name.to_owned()),
(!version.is_empty()).then(|| version.to_owned()),
);
}
if let Some((name, version)) = user_agent.split_once(char::is_whitespace) {
return (Some(name.into()), Some(version.trim().into()));
}
(Some(user_agent.into()), None)
}
#[derive(Debug, Deserialize)]
#[serde(tag = "type")]
enum LoginStartResponse {
#[serde(rename = "apiKey")]
ApiKey,
#[serde(rename = "chatgpt")]
Chatgpt {
#[serde(rename = "loginId")]
login_id: String,
#[serde(rename = "authUrl")]
auth_url: String,
},
#[serde(rename = "chatgptDeviceCode")]
ChatgptDeviceCode {
#[serde(rename = "loginId")]
login_id: String,
#[serde(rename = "verificationUrl")]
verification_url: String,
#[serde(rename = "userCode")]
user_code: String,
},
#[serde(rename = "chatgptAuthTokens")]
ChatgptAuthTokens,
}
#[derive(Debug, Deserialize)]
struct ThreadEnvelope {
thread: ThreadData,
}
#[derive(Debug, Deserialize)]
struct TurnStartResponse {
turn: Turn,
}
#[derive(Debug, Deserialize)]
struct EmptyObject {
#[serde(flatten)]
_extra: Map<String, Value>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn splits_supported_user_agent_shapes() {
assert_eq!(
split_user_agent("codex-cli/1.2.3"),
(Some("codex-cli".into()), Some("1.2.3".into()))
);
assert_eq!(
split_user_agent("codex-cli 1.2.3"),
(Some("codex-cli".into()), Some("1.2.3".into()))
);
assert_eq!(split_user_agent("codex"), (Some("codex".into()), None));
assert_eq!(split_user_agent(""), (None, None));
}
#[test]
fn validates_and_backfills_initialize_metadata() {
let response = validate_initialize_metadata(InitializeResponse {
user_agent: Some("codex-cli/1.2.3".into()),
..InitializeResponse::default()
})
.unwrap();
assert_eq!(
response.server_info.unwrap().name.as_deref(),
Some("codex-cli")
);
assert!(validate_initialize_metadata(InitializeResponse::default()).is_err());
}
#[test]
fn default_async_client_is_lazy() {
let explicit = AsyncCodex::with_defaults();
let defaulted = AsyncCodex::default();
assert!(matches!(
explicit.metadata(),
Err(Error::InvalidConfiguration(_))
));
assert!(matches!(
defaulted.metadata(),
Err(Error::InvalidConfiguration(_))
));
}
#[tokio::test]
async fn login_wait_reports_a_closed_notification_channel() {
let client = AsyncCodex::default();
let (sender, receiver) = tokio::sync::mpsc::unbounded_channel();
drop(sender);
assert!(matches!(
wait_for_login(&client, "login-1", &Mutex::new(Some(receiver))).await,
Err(Error::TransportClosed(message))
if message == "login notification stream stopped"
));
}
#[tokio::test(start_paused = true)]
async fn retry_retries_overload_and_rejects_invalid_policy() {
let mut attempts = 0;
let value = retry_on_overload(
RetryPolicy {
max_attempts: 3,
initial_delay: Duration::ZERO,
max_delay: Duration::ZERO,
jitter_ratio: 0.0,
},
|| {
attempts += 1;
async move {
if attempts < 3 {
Err(Error::JsonRpc(crate::JsonRpcError::new(
-32001,
"busy".into(),
Some(json!("server_overloaded")),
)))
} else {
Ok(42)
}
}
},
)
.await
.unwrap();
assert_eq!(value, 42);
assert_eq!(attempts, 3);
assert!(
retry_on_overload(
RetryPolicy {
max_attempts: 0,
..RetryPolicy::default()
},
|| async { Ok::<_, Error>(()) },
)
.await
.is_err()
);
let exhausted = retry_on_overload(
RetryPolicy {
max_attempts: 2,
initial_delay: Duration::from_millis(1),
max_delay: Duration::from_millis(2),
jitter_ratio: 0.0,
},
|| async {
Err::<(), _>(Error::JsonRpc(crate::JsonRpcError::new(
-32001,
"busy".into(),
Some(json!("server_overloaded")),
)))
},
)
.await;
assert!(matches!(exhausted, Err(Error::JsonRpc(_))));
let non_retryable = retry_on_overload(RetryPolicy::default(), || async {
Err::<(), _>(Error::InvalidConfiguration("stop".into()))
})
.await;
assert!(matches!(
non_retryable,
Err(Error::InvalidConfiguration(message)) if message == "stop"
));
}
}