Add durable user-message queue dispatch (#37204)

## What changed

- Add a storage-neutral queue extension for listing, adding, editing, reordering, deleting, and explicitly starting queued user messages.
- Dispatch queued messages in FIFO order when a thread becomes idle after a completed turn, while leaving them queued after interruptions or failures.
- Wait for user input to be persisted before removing its queue item, and report hook rejection, task termination, and persistence failures distinctly.
- Snapshot local image and audio attachments into validated data URLs before storing them, enforce input limits, and emit `ThreadQueueChanged` events after mutations.

## Testing

- Cover queue mutations, automatic and explicit dispatch, interruption and failure behavior, hook rejection, invalid records, input limits, and local attachment snapshotting.

GitOrigin-RevId: 14f39d7c8cbaccb767a6da84b82cced0edfcb4b9
This commit is contained in:
efrazer-oai
2026-08-06 03:11:42 +00:00
committed by copyberry
parent 70b4653232
commit bc8b25ea02
42 changed files with 2114 additions and 140 deletions
+6
View File
@@ -0,0 +1,6 @@
load("//:defs.bzl", "codex_rust_crate")
codex_rust_crate(
name = "queue",
crate_name = "codex_queue_extension",
)
+34
View File
@@ -0,0 +1,34 @@
[package]
edition.workspace = true
license.workspace = true
name = "codex-queue-extension"
version.workspace = true
[lib]
name = "codex_queue_extension"
path = "src/lib.rs"
test = false
doctest = false
[lints]
workspace = true
[dependencies]
codex-core = { workspace = true }
codex-extension-api = { workspace = true }
codex-protocol = { workspace = true }
codex-thread-store = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
tokio = { workspace = true, features = ["rt", "sync", "time"] }
tracing = { workspace = true }
uuid = { workspace = true, features = ["v7"] }
[dev-dependencies]
anyhow = { workspace = true }
codex-state = { workspace = true }
codex-utils-absolute-path = { workspace = true }
core_test_support = { workspace = true }
pretty_assertions = { workspace = true }
tempfile = { workspace = true }
tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+19
View File
@@ -0,0 +1,19 @@
//! Durable, storage-neutral user-message queue and idle dispatch.
use std::sync::Arc;
use codex_extension_api::ExtensionRegistryBuilder;
mod service;
pub use service::QueueServiceError;
pub use service::QueuedItem;
pub use service::QueuedItemService;
/// Registers the caller-owned queue before lower-priority idle contributors.
pub fn install<C>(registry: &mut ExtensionRegistryBuilder<C>, service: Arc<QueuedItemService>)
where
C: Send + Sync + 'static,
{
registry.thread_lifecycle_contributor(service);
}
+394
View File
@@ -0,0 +1,394 @@
use std::collections::BTreeMap;
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::Mutex as StdMutex;
use std::sync::Weak;
use codex_core::CodexThread;
use codex_core::ThreadManager;
use codex_core::TryStartTurnIfIdleRejectionReason;
use codex_core::TurnInput;
use codex_core::UserMessageAdmission;
use codex_core::UserMessageAdmissionError;
use codex_extension_api::ExtensionEventSink;
use codex_extension_api::ExtensionFuture;
use codex_extension_api::ThreadIdleCause;
use codex_extension_api::ThreadIdleInput;
use codex_extension_api::ThreadLifecycleContributor;
use codex_protocol::ThreadId;
use codex_protocol::error::CodexErr;
use codex_protocol::models::snapshot_local_user_input;
use codex_protocol::protocol::AgentStatus;
use codex_protocol::protocol::Event;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::Op;
use codex_protocol::protocol::ThreadQueueChangedEvent;
use codex_protocol::protocol::ThreadSettingsOverrides;
use codex_protocol::protocol::W3cTraceContext;
use codex_protocol::user_input::MAX_USER_INPUT_TEXT_CHARS;
use codex_protocol::user_input::UserInput;
use codex_thread_store::MAX_QUEUE_ITEMS;
use codex_thread_store::QueueStore;
use codex_thread_store::QueuedUserSubmissionRecord;
use codex_thread_store::ThreadStoreError;
use thiserror::Error;
use tokio::sync::Mutex;
use tokio::sync::OwnedMutexGuard;
use uuid::Uuid;
/// One user message waiting to start on its thread.
#[derive(Clone, Debug, PartialEq)]
pub struct QueuedItem {
pub id: String,
pub input: TurnInput,
}
#[derive(Debug, Error)]
pub enum QueueServiceError {
#[error("queue storage failed: {0}")]
Storage(#[from] ThreadStoreError),
#[error("queued item payload is invalid: {0}")]
InvalidPayload(#[from] serde_json::Error),
#[error("local queued attachment is invalid: {0}")]
InvalidAttachment(#[from] std::io::Error),
#[error("queued user message could not be admitted: {0}")]
Admission(#[from] CodexErr),
#[error("only user input can be added to the user-message queue")]
InvalidInput,
#[error(
"queued user input exceeds the maximum length of {MAX_USER_INPUT_TEXT_CHARS} characters ({actual_chars} provided)"
)]
InputTooLarge { actual_chars: usize },
}
#[derive(Clone)]
pub struct QueuedItemService {
queue: Arc<dyn QueueStore>,
thread_manager: Weak<ThreadManager>,
event_sink: Arc<dyn ExtensionEventSink>,
dispatch_locks: Arc<StdMutex<HashMap<ThreadId, Weak<Mutex<()>>>>>,
}
impl QueuedItemService {
pub fn new(
queue: Arc<dyn QueueStore>,
thread_manager: Weak<ThreadManager>,
event_sink: Arc<dyn ExtensionEventSink>,
) -> Self {
Self {
queue,
thread_manager,
event_sink,
dispatch_locks: Arc::new(StdMutex::new(HashMap::new())),
}
}
fn dispatch_lock(&self, thread_id: ThreadId) -> Arc<Mutex<()>> {
let mut locks = self
.dispatch_locks
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
locks.retain(|_, lock| lock.strong_count() != 0);
if let Some(lock) = locks.get(&thread_id).and_then(Weak::upgrade) {
return lock;
}
let lock = Arc::new(Mutex::new(()));
locks.insert(thread_id, Arc::downgrade(&lock));
lock
}
async fn dispatch_guard(&self, thread_id: ThreadId) -> OwnedMutexGuard<()> {
self.dispatch_lock(thread_id).lock_owned().await
}
pub async fn enqueue(
&self,
thread_id: ThreadId,
input: TurnInput,
) -> Result<QueuedItem, QueueServiceError> {
let input = prepare_queued_user_input(input).await?;
let payload = serde_json::to_string(&input)?;
let item = queued_item_from_record(self.queue.enqueue(thread_id, payload).await?)?;
self.emit_changed(thread_id);
self.wake_if_loaded(thread_id).await;
Ok(item)
}
pub async fn list(&self, thread_id: ThreadId) -> Result<Vec<QueuedItem>, QueueServiceError> {
self.queue
.list_page(thread_id, /*offset*/ 0, MAX_QUEUE_ITEMS)
.await?
.into_iter()
.map(queued_item_from_record)
.collect()
}
pub async fn update(
&self,
thread_id: ThreadId,
queued_item_id: String,
mut input: TurnInput,
) -> Result<Option<QueuedItem>, QueueServiceError> {
let _dispatch_guard = self.dispatch_guard(thread_id).await;
if let TurnInput::UserInput { client_id, .. } = &mut input
&& client_id.is_none()
{
*client_id = self
.list(thread_id)
.await?
.into_iter()
.find_map(|item| match item {
QueuedItem {
id,
input: TurnInput::UserInput { client_id, .. },
} if id == queued_item_id => client_id,
_ => None,
});
}
let input = prepare_queued_user_input(input).await?;
let payload = serde_json::to_string(&input)?;
let item = self
.queue
.update(thread_id, queued_item_id, payload)
.await?
.map(queued_item_from_record)
.transpose()?;
if item.is_some() {
self.emit_changed(thread_id);
}
Ok(item)
}
pub async fn delete(
&self,
thread_id: ThreadId,
queued_item_id: String,
) -> Result<bool, QueueServiceError> {
let _dispatch_guard = self.dispatch_guard(thread_id).await;
self.delete_locked(thread_id, queued_item_id).await
}
async fn delete_locked(
&self,
thread_id: ThreadId,
queued_item_id: String,
) -> Result<bool, QueueServiceError> {
let deleted = self.queue.delete(thread_id, queued_item_id).await?;
if deleted {
self.emit_changed(thread_id);
}
Ok(deleted)
}
pub async fn reorder(
&self,
thread_id: ThreadId,
ordered_ids: Vec<String>,
) -> Result<(), QueueServiceError> {
let _dispatch_guard = self.dispatch_guard(thread_id).await;
self.queue.reorder(thread_id, ordered_ids).await?;
self.emit_changed(thread_id);
Ok(())
}
/// Starts or steers the exact queued message and removes it after admission.
pub async fn start(
&self,
thread: &CodexThread,
queued_item_id: String,
trace: Option<W3cTraceContext>,
) -> Result<UserMessageAdmission, QueueServiceError> {
let thread_id = thread.session_configured().thread_id;
let _dispatch_guard = self.dispatch_guard(thread_id).await;
let item = self
.list(thread_id)
.await?
.into_iter()
.find(|item| item.id == queued_item_id)
.ok_or_else(|| ThreadStoreError::InvalidRequest {
message: format!("queued item not found: {queued_item_id}"),
})?;
let TurnInput::UserInput { content, client_id } = item.input else {
return Err(QueueServiceError::InvalidInput);
};
let admission = thread
.submit_user_input_and_wait_for_persisted_admission(
Op::UserInput {
items: content,
final_output_json_schema: None,
responsesapi_client_metadata: None,
additional_context: BTreeMap::new(),
thread_settings: ThreadSettingsOverrides::default(),
},
trace,
client_id,
)
.await;
let admission = match admission {
Ok(admission) => admission,
Err(error) => {
if matches!(&error, UserMessageAdmissionError::RejectedByHook) {
self.delete_locked(thread_id, queued_item_id).await?;
}
return Err(QueueServiceError::Admission(error.into()));
}
};
self.delete_locked(thread_id, queued_item_id).await?;
Ok(admission)
}
async fn dispatch_if_idle(&self, thread_id: ThreadId) -> Result<(), QueueServiceError> {
let Some(manager) = self.thread_manager.upgrade() else {
return Ok(());
};
let Ok(thread) = manager.get_thread(thread_id).await else {
return Ok(());
};
loop {
let Some(record) = self
.queue
.list_page(thread_id, /*offset*/ 0, /*limit*/ 1)
.await?
.into_iter()
.next()
else {
return Ok(());
};
let queued_item_id = record.id.clone();
let input = match serde_json::from_str::<TurnInput>(&record.payload) {
Ok(input) => input,
Err(error) => {
tracing::warn!(%queued_item_id, %error, "discarding invalid queued item");
self.delete_locked(thread_id, queued_item_id).await?;
continue;
}
};
if !matches!(input, TurnInput::UserInput { .. }) {
tracing::warn!(%queued_item_id, "discarding non-user queued input");
self.delete_locked(thread_id, queued_item_id).await?;
continue;
}
if let Err(error) = thread.try_start_turn_if_idle(vec![input]).await {
if error.reason() == TryStartTurnIfIdleRejectionReason::RejectedByHook {
self.delete_locked(thread_id, queued_item_id).await?;
continue;
}
tracing::warn!(
%thread_id,
%queued_item_id,
reason = ?error.reason(),
"core could not start queued user input"
);
return Ok(());
}
self.delete_locked(thread_id, queued_item_id).await?;
return Ok(());
}
}
async fn wake_if_loaded(&self, thread_id: ThreadId) {
let Some(manager) = self.thread_manager.upgrade() else {
return;
};
if let Ok(thread) = manager.get_thread(thread_id).await
&& !matches!(thread.agent_status().await, AgentStatus::Interrupted)
{
thread
.emit_thread_idle_lifecycle_if_idle(ThreadIdleCause::Completed)
.await;
}
}
fn emit_changed(&self, thread_id: ThreadId) {
self.event_sink.emit(Event {
id: Uuid::now_v7().to_string(),
msg: EventMsg::ThreadQueueChanged(ThreadQueueChangedEvent { thread_id }),
});
}
}
async fn prepare_queued_user_input(mut input: TurnInput) -> Result<TurnInput, QueueServiceError> {
validate_queued_user_input(&input)?;
let TurnInput::UserInput { content, client_id } = &mut input else {
return Err(QueueServiceError::InvalidInput);
};
client_id.get_or_insert_with(|| Uuid::now_v7().to_string());
if !content.iter().any(|item| {
matches!(
item,
UserInput::LocalImage { .. } | UserInput::LocalAudio { .. }
)
}) {
return Ok(input);
}
tokio::task::spawn_blocking(move || {
let mut input = input;
if let TurnInput::UserInput { content, .. } = &mut input {
for item in content {
snapshot_local_user_input(item)?;
}
}
Ok::<TurnInput, std::io::Error>(input)
})
.await
.map_err(|error| QueueServiceError::InvalidAttachment(std::io::Error::other(error)))?
.map_err(QueueServiceError::InvalidAttachment)
}
fn validate_queued_user_input(input: &TurnInput) -> Result<(), QueueServiceError> {
let TurnInput::UserInput { content, .. } = input else {
return Err(QueueServiceError::InvalidInput);
};
if content.is_empty() {
return Err(QueueServiceError::InvalidInput);
}
let actual_chars: usize = content
.iter()
.filter_map(|item| match item {
UserInput::Text { text, .. } => Some(text.chars().count()),
_ => None,
})
.sum();
if actual_chars > MAX_USER_INPUT_TEXT_CHARS {
return Err(QueueServiceError::InputTooLarge { actual_chars });
}
Ok(())
}
impl<C> ThreadLifecycleContributor<C> for QueuedItemService
where
C: Send + Sync + 'static,
{
fn on_thread_idle<'a>(&'a self, input: ThreadIdleInput<'a>) -> ExtensionFuture<'a, ()> {
Box::pin(async move {
if input.cause != ThreadIdleCause::Completed {
return;
}
let Ok(thread_id) = ThreadId::from_string(input.thread_store.level_id()) else {
tracing::warn!(
level_id = input.thread_store.level_id(),
"queue extension received an invalid thread id"
);
return;
};
let _guard = self.dispatch_guard(thread_id).await;
if let Err(error) = self.dispatch_if_idle(thread_id).await {
tracing::warn!(%thread_id, %error, "failed to dispatch queued user input");
}
})
}
}
fn queued_item_from_record(
record: QueuedUserSubmissionRecord,
) -> Result<QueuedItem, QueueServiceError> {
Ok(QueuedItem {
id: record.id,
input: serde_json::from_str::<TurnInput>(&record.payload)?,
})
}
+756
View File
@@ -0,0 +1,756 @@
use std::path::Path;
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::OnceLock;
use std::sync::Weak;
use std::time::Duration;
use anyhow::Context;
use codex_core::TurnInput;
use codex_core::UserMessageAdmission;
use codex_extension_api::ExtensionData;
use codex_extension_api::ExtensionEventSink;
use codex_extension_api::ExtensionFuture;
use codex_extension_api::ExtensionRegistry;
use codex_extension_api::ExtensionRegistryBuilder;
use codex_extension_api::ExtensionWarning;
use codex_extension_api::NoopExtensionEventSink;
use codex_extension_api::ThreadIdleCause;
use codex_extension_api::ThreadIdleInput;
use codex_extension_api::ThreadLifecycleContributor;
use codex_protocol::ThreadId;
use codex_protocol::items::TurnItem;
use codex_protocol::models::ImageDetail;
use codex_protocol::models::ResponseItem;
use codex_protocol::protocol::Event;
use codex_protocol::protocol::EventMsg;
use codex_protocol::user_input::MAX_USER_INPUT_TEXT_CHARS;
use codex_protocol::user_input::UserInput;
use codex_queue_extension::QueueServiceError;
use codex_queue_extension::QueuedItemService;
use codex_state::SqliteConfig;
use codex_state::StateRuntime;
use codex_thread_store::LocalQueueStore;
use codex_thread_store::QueueStore;
use codex_thread_store::ThreadStoreError;
use codex_utils_absolute_path::test_support::PathExt;
use core_test_support::hooks::trust_discovered_hooks;
use core_test_support::responses;
use core_test_support::responses::start_mock_server;
use core_test_support::test_codex::TestCodex;
use core_test_support::test_codex::test_codex;
use core_test_support::wait_for_event_match;
use pretty_assertions::assert_eq;
use tempfile::TempDir;
const TINY_PNG_BYTES: &[u8] = &[
137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82, 0, 0, 0, 1, 0, 0, 0, 1, 8, 6, 0,
0, 0, 31, 21, 196, 137, 0, 0, 0, 11, 73, 68, 65, 84, 120, 156, 99, 96, 0, 2, 0, 0, 5, 0, 1,
122, 94, 171, 63, 0, 0, 0, 0, 73, 69, 78, 68, 174, 66, 96, 130,
];
const TINY_PNG_DATA_URL: &str = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=";
#[derive(Default)]
struct RecordingEventSink {
events: Mutex<Vec<Event>>,
}
impl ExtensionEventSink for RecordingEventSink {
fn emit(&self, event: Event) {
self.events
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push(event);
}
fn emit_warning(&self, _warning: ExtensionWarning) {}
}
#[derive(Default)]
struct InstalledQueue(OnceLock<Arc<QueuedItemService>>);
impl ThreadLifecycleContributor<codex_core::config::Config> for InstalledQueue {
fn on_thread_idle<'a>(&'a self, input: ThreadIdleInput<'a>) -> ExtensionFuture<'a, ()> {
match self.0.get() {
Some(service) => <QueuedItemService as ThreadLifecycleContributor<
codex_core::config::Config,
>>::on_thread_idle(service.as_ref(), input),
None => Box::pin(async {}),
}
}
}
fn registered_queue_extensions() -> (
Arc<InstalledQueue>,
Arc<ExtensionRegistry<codex_core::config::Config>>,
) {
let installed = Arc::new(InstalledQueue::default());
let mut extensions = ExtensionRegistryBuilder::new();
extensions.thread_lifecycle_contributor(installed.clone());
(installed, Arc::new(extensions.build()))
}
fn install_registered_queue(
test: &TestCodex,
installed: &InstalledQueue,
) -> anyhow::Result<Arc<QueuedItemService>> {
let service = Arc::new(QueuedItemService::new(
loaded_thread_queue(test)?,
Arc::downgrade(&test.thread_manager),
Arc::new(NoopExtensionEventSink),
));
assert!(installed.0.set(Arc::clone(&service)).is_ok());
Ok(service)
}
fn write_rejecting_prompt_hook(home: &Path) {
let script_path = home.join("queue_prompt_hook.py");
let log_path = home.join("queue_prompt_hook.log");
let script = format!(
r#"import json
from pathlib import Path
import sys
payload = json.load(sys.stdin)
with Path(r"{log_path}").open("a", encoding="utf-8") as log:
log.write(payload["prompt"] + "\n")
if payload["prompt"] == "blocked":
print(json.dumps({{"decision": "block", "reason": "blocked by queue hook"}}))
"#,
log_path = log_path.display(),
);
std::fs::write(&script_path, script)
.unwrap_or_else(|error| panic!("write queue hook script: {error}"));
let hooks = serde_json::json!({
"hooks": {
"UserPromptSubmit": [{
"hooks": [{
"type": "command",
"command": format!("python3 {}", script_path.display()),
}]
}]
}
});
std::fs::write(home.join("hooks.json"), hooks.to_string())
.unwrap_or_else(|error| panic!("write queue hooks: {error}"));
}
async fn test_queue() -> anyhow::Result<(Arc<dyn QueueStore>, TempDir)> {
let home = tempfile::tempdir()?;
let sqlite = SqliteConfig::new_for_testing(home.path().abs());
let runtime = StateRuntime::init(sqlite.clone(), "test-provider".to_string()).await?;
let queue: Arc<dyn QueueStore> = Arc::new(LocalQueueStore::new(runtime));
Ok((queue, home))
}
fn loaded_thread_queue(test: &TestCodex) -> anyhow::Result<Arc<dyn QueueStore>> {
let runtime = test.codex.state_db().context("state runtime unavailable")?;
Ok(Arc::new(LocalQueueStore::new(runtime)))
}
fn user_input(text: &str) -> TurnInput {
TurnInput::UserInput {
content: vec![UserInput::Text {
text: text.to_string(),
text_elements: Vec::new(),
}],
client_id: None,
}
}
fn structured_user_input(text: &str) -> TurnInput {
TurnInput::UserInput {
content: vec![UserInput::Text {
text: text.to_string(),
text_elements: Vec::new(),
}],
client_id: Some("stable-client-message".to_string()),
}
}
fn user_input_with_media(text: &str, image: UserInput, audio: UserInput) -> TurnInput {
let mut input = structured_user_input(text);
if let TurnInput::UserInput { content, .. } = &mut input {
content.extend([image, audio]);
}
input
}
async fn emit_idle(service: &QueuedItemService, thread_id: ThreadId) {
emit_idle_with_cause(service, thread_id, ThreadIdleCause::Completed).await;
}
async fn emit_idle_with_cause(
service: &QueuedItemService,
thread_id: ThreadId,
cause: ThreadIdleCause,
) {
let session_store = ExtensionData::new("session");
let thread_store = ExtensionData::new(thread_id.to_string());
<QueuedItemService as ThreadLifecycleContributor<()>>::on_thread_idle(
service,
ThreadIdleInput {
cause,
session_store: &session_store,
thread_store: &thread_store,
},
)
.await;
}
#[tokio::test]
async fn queued_input_and_unique_event_ids_round_trip() -> anyhow::Result<()> {
let (queue, _home) = test_queue().await?;
let sink = Arc::new(RecordingEventSink::default());
let event_sink: Arc<dyn ExtensionEventSink> = sink.clone();
let service = QueuedItemService::new(queue, Weak::new(), event_sink);
let thread_id = ThreadId::new();
let input = structured_user_input("structured message");
let first = service.enqueue(thread_id, input.clone()).await?;
let second = service.enqueue(thread_id, user_input("next")).await?;
let TurnInput::UserInput {
client_id: Some(generated_client_id),
..
} = &second.input
else {
anyhow::bail!("queued message did not receive a client message id");
};
assert_eq!(
7,
uuid::Uuid::parse_str(generated_client_id)?.get_version_num()
);
assert_eq!(vec![first.clone(), second], service.list(thread_id).await?);
assert_eq!(input, first.input);
let events = sink
.events
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
assert_eq!(2, events.len());
for event in events.iter() {
let EventMsg::ThreadQueueChanged(change) = &event.msg else {
anyhow::bail!("event is not a queue change");
};
assert_eq!(
serde_json::json!({ "threadId": thread_id }),
serde_json::to_value(change)?
);
}
assert_ne!(events[0].id, events[1].id);
Ok(())
}
#[tokio::test]
async fn editing_reordering_and_deleting_preserve_queue_identity() -> anyhow::Result<()> {
let (queue, _home) = test_queue().await?;
let service = QueuedItemService::new(queue, Weak::new(), Arc::new(NoopExtensionEventSink));
let thread_id = ThreadId::new();
let first = service
.enqueue(thread_id, structured_user_input("first"))
.await?;
let second = service.enqueue(thread_id, user_input("second")).await?;
let edited = service
.update(thread_id, first.id.clone(), user_input("edited"))
.await?
.context("queued item missing")?;
assert_eq!(first.id, edited.id);
let TurnInput::UserInput { client_id, .. } = &edited.input else {
anyhow::bail!("edited queue item does not contain user input");
};
assert_eq!(Some("stable-client-message"), client_id.as_deref());
assert!(matches!(
service.reorder(thread_id, vec![first.id.clone()]).await,
Err(QueueServiceError::Storage(
ThreadStoreError::InvalidRequest { .. }
))
));
service
.reorder(thread_id, vec![second.id.clone(), first.id.clone()])
.await?;
assert_eq!(
vec![second.clone(), edited.clone()],
service.list(thread_id).await?
);
assert!(service.delete(thread_id, second.id).await?);
assert_eq!(vec![edited], service.list(thread_id).await?);
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn starting_a_selected_item_preserves_the_remaining_queue() -> anyhow::Result<()> {
let server = start_mock_server().await;
let response =
responses::mount_sse_once(&server, responses::sse_completed("selected-turn")).await;
let test = test_codex().build_with_auto_env(&server).await?;
let thread_id = test.session_configured.thread_id;
let queue = loaded_thread_queue(&test)?;
let service = QueuedItemService::new(queue, Weak::new(), Arc::new(NoopExtensionEventSink));
let first = service.enqueue(thread_id, user_input("first")).await?;
let second = service
.enqueue(thread_id, structured_user_input("second"))
.await?;
let admission = service
.start(test.codex.as_ref(), second.id.clone(), /*trace*/ None)
.await?;
assert!(matches!(admission, UserMessageAdmission::Started { .. }));
assert_eq!(vec![first], service.list(thread_id).await?);
wait_for_event_match(test.codex.as_ref(), |event| match event {
EventMsg::TurnComplete(_) => Some(()),
_ => None,
})
.await;
assert_eq!(
Some("second"),
response
.single_request()
.message_input_texts("user")
.last()
.map(String::as_str)
);
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn stopped_turns_leave_queued_messages_in_place() -> anyhow::Result<()> {
let server = start_mock_server().await;
let test = test_codex().build_with_auto_env(&server).await?;
let thread_id = test.session_configured.thread_id;
let queue = loaded_thread_queue(&test)?;
let service = QueuedItemService::new(
queue,
Arc::downgrade(&test.thread_manager),
Arc::new(NoopExtensionEventSink),
);
let queued = service
.enqueue(thread_id, user_input("keep queued after stopping"))
.await?;
for cause in [ThreadIdleCause::Interrupted, ThreadIdleCause::Failed] {
emit_idle_with_cause(&service, thread_id, cause).await;
assert_eq!(vec![queued.clone()], service.list(thread_id).await?);
}
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn registered_queue_lifecycle_starts_messages_in_fifo_order() -> anyhow::Result<()> {
let server = start_mock_server().await;
let responses = responses::mount_sse_sequence(
&server,
["turn-a", "turn-b", "turn-c"]
.into_iter()
.map(responses::sse_completed)
.collect(),
)
.await;
let (installed, extensions) = registered_queue_extensions();
let test = test_codex()
.with_extensions(extensions)
.with_config(|config| config.include_environment_context = false)
.build_with_auto_env(&server)
.await?;
let thread_id = test.session_configured.thread_id;
let staging = QueuedItemService::new(
loaded_thread_queue(&test)?,
Weak::new(),
Arc::new(NoopExtensionEventSink),
);
for prompt in ["B", "C"] {
staging.enqueue(thread_id, user_input(prompt)).await?;
}
let queue = install_registered_queue(&test, installed.as_ref())?;
tokio::time::timeout(Duration::from_secs(10), async {
test.submit_text_turn("A").await?;
for _ in 0..2 {
wait_for_event_match(test.codex.as_ref(), |event| {
matches!(event, EventMsg::TurnComplete(_)).then_some(())
})
.await;
}
anyhow::Ok(())
})
.await??;
let prompts = responses
.requests()
.into_iter()
.map(|request| {
request
.message_input_texts("user")
.pop()
.context("model request has no user input")
})
.collect::<anyhow::Result<Vec<_>>>()?;
assert_eq!(vec!["A", "B", "C"], prompts);
assert!(queue.list(thread_id).await?.is_empty());
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn rejected_queue_messages_are_consumed_without_retrying_or_blocking_followups()
-> anyhow::Result<()> {
let server = start_mock_server().await;
let responses = responses::mount_sse_sequence(
&server,
["initial-turn", "following-turn"]
.into_iter()
.map(responses::sse_completed)
.collect(),
)
.await;
let (installed, extensions) = registered_queue_extensions();
let test = test_codex()
.with_extensions(extensions)
.with_pre_build_hook(write_rejecting_prompt_hook)
.with_config(trust_discovered_hooks)
.with_config(|config| config.include_environment_context = false)
.build_with_auto_env(&server)
.await?;
let thread_id = test.session_configured.thread_id;
let staging = QueuedItemService::new(
loaded_thread_queue(&test)?,
Weak::new(),
Arc::new(NoopExtensionEventSink),
);
for prompt in ["blocked", "C"] {
staging.enqueue(thread_id, user_input(prompt)).await?;
}
let queue = install_registered_queue(&test, installed.as_ref())?;
tokio::time::timeout(Duration::from_secs(10), async {
test.submit_text_turn("A").await?;
for _ in 0..2 {
wait_for_event_match(test.codex.as_ref(), |event| {
matches!(event, EventMsg::TurnComplete(_)).then_some(())
})
.await;
}
anyhow::Ok(())
})
.await??;
let prompts = responses
.requests()
.into_iter()
.map(|request| {
request
.message_input_texts("user")
.pop()
.context("model request has no user input")
})
.collect::<anyhow::Result<Vec<_>>>()?;
assert_eq!(vec!["A", "C"], prompts);
let hook_log = std::fs::read_to_string(test.codex_home_path().join("queue_prompt_hook.log"))?;
assert_eq!(
vec!["A", "blocked", "C"],
hook_log.lines().collect::<Vec<_>>()
);
assert!(queue.list(thread_id).await?.is_empty());
let rejected = staging.enqueue(thread_id, user_input("blocked")).await?;
let error = tokio::time::timeout(
Duration::from_secs(10),
queue.start(test.codex.as_ref(), rejected.id, /*trace*/ None),
)
.await?
.expect_err("explicitly started blocked input should be rejected");
assert!(matches!(
error,
QueueServiceError::Admission(error)
if matches!(
error.details(),
codex_protocol::error::CodexErrorDetails::InvalidRequest(message)
if message == "user message was rejected by a hook"
)
));
assert!(queue.list(thread_id).await?.is_empty());
let hook_log = std::fs::read_to_string(test.codex_home_path().join("queue_prompt_hook.log"))?;
assert_eq!(
vec!["A", "blocked", "C", "blocked"],
hook_log.lines().collect::<Vec<_>>()
);
assert_eq!(2, responses.requests().len());
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn local_attachments_are_snapshotted_before_enqueue_and_update() -> anyhow::Result<()> {
let (queue, home) = test_queue().await?;
let service = QueuedItemService::new(
Arc::clone(&queue),
Weak::new(),
Arc::new(NoopExtensionEventSink),
);
let thread_id = ThreadId::new();
let image_path = home.path().join("queued.png");
let audio_path = home.path().join("queued.mp3");
std::fs::write(&image_path, TINY_PNG_BYTES)?;
std::fs::write(&audio_path, b"audio")?;
let queued_input = user_input_with_media(
"queued attachments",
UserInput::LocalImage {
path: image_path.clone(),
detail: Some(ImageDetail::Original),
},
UserInput::LocalAudio {
path: audio_path.clone(),
},
);
let expected_queued_input = user_input_with_media(
"queued attachments",
UserInput::Image {
image_url: TINY_PNG_DATA_URL.to_string(),
detail: Some(ImageDetail::Original),
},
UserInput::Audio {
audio_url: "data:audio/mpeg;base64,YXVkaW8=".to_string(),
},
);
let queued = service.enqueue(thread_id, queued_input).await?;
std::fs::remove_file(&image_path)?;
std::fs::remove_file(&audio_path)?;
assert_eq!(expected_queued_input, queued.input);
assert_eq!(vec![queued.clone()], service.list(thread_id).await?);
let queued_record = queue
.list_page(thread_id, /*offset*/ 0, /*limit*/ 1)
.await?
.into_iter()
.next()
.context("snapshotted queued attachments were not persisted")?;
let persisted_queued_input: TurnInput = serde_json::from_str(&queued_record.payload)?;
assert_eq!(expected_queued_input, persisted_queued_input);
let edited_image_path = home.path().join("edited.png");
let edited_audio_path = home.path().join("edited.m4a");
std::fs::write(&edited_image_path, TINY_PNG_BYTES)?;
std::fs::write(&edited_audio_path, b"edited audio")?;
let edited_input = user_input_with_media(
"edited attachments",
UserInput::LocalImage {
path: edited_image_path.clone(),
detail: Some(ImageDetail::High),
},
UserInput::LocalAudio {
path: edited_audio_path.clone(),
},
);
let expected_edited_input = user_input_with_media(
"edited attachments",
UserInput::Image {
image_url: TINY_PNG_DATA_URL.to_string(),
detail: Some(ImageDetail::High),
},
UserInput::Audio {
audio_url: "data:audio/mp4;base64,ZWRpdGVkIGF1ZGlv".to_string(),
},
);
let edited = service
.update(thread_id, queued.id.clone(), edited_input)
.await?
.context("snapshotted queued attachments were not updated")?;
std::fs::remove_file(&edited_image_path)?;
std::fs::remove_file(&edited_audio_path)?;
assert_eq!(expected_edited_input, edited.input);
assert_eq!(vec![edited.clone()], service.list(thread_id).await?);
let edited_record = queue
.list_page(thread_id, /*offset*/ 0, /*limit*/ 1)
.await?
.into_iter()
.next()
.context("snapshotted edited attachments were not persisted")?;
let persisted_edited_input: TurnInput = serde_json::from_str(&edited_record.payload)?;
assert_eq!(expected_edited_input, persisted_edited_input);
Ok(())
}
#[tokio::test]
async fn invalid_local_attachments_do_not_mutate_queue() -> anyhow::Result<()> {
let (queue, home) = test_queue().await?;
let service = QueuedItemService::new(queue, Weak::new(), Arc::new(NoopExtensionEventSink));
let thread_id = ThreadId::new();
let existing = service.enqueue(thread_id, user_input("existing")).await?;
let missing_path = home.path().join("missing.png");
let invalid_input = user_input_with_media(
"invalid attachments",
UserInput::LocalImage {
path: missing_path,
detail: Some(ImageDetail::Original),
},
UserInput::Audio {
audio_url: "data:audio/mpeg;base64,YXVkaW8=".to_string(),
},
);
assert!(matches!(
service
.enqueue(thread_id, invalid_input.clone())
.await,
Err(QueueServiceError::InvalidAttachment(error))
if error.kind() == std::io::ErrorKind::NotFound
));
assert!(matches!(
service
.update(
thread_id,
existing.id.clone(),
invalid_input,
)
.await,
Err(QueueServiceError::InvalidAttachment(error))
if error.kind() == std::io::ErrorKind::NotFound
));
assert_eq!(vec![existing], service.list(thread_id).await?);
Ok(())
}
#[tokio::test]
async fn non_user_input_cannot_enter_the_user_message_queue() -> anyhow::Result<()> {
let (queue, _home) = test_queue().await?;
let service = QueuedItemService::new(queue, Weak::new(), Arc::new(NoopExtensionEventSink));
let error = service
.enqueue(
ThreadId::new(),
TurnInput::ResponseItem(ResponseItem::Other),
)
.await
.expect_err("response item should not enter the user queue");
assert!(matches!(error, QueueServiceError::InvalidInput));
Ok(())
}
#[tokio::test]
async fn queued_text_limit_is_enforced_across_all_input_items() -> anyhow::Result<()> {
let (queue, _home) = test_queue().await?;
let service = QueuedItemService::new(queue, Weak::new(), Arc::new(NoopExtensionEventSink));
let thread_id = ThreadId::new();
let existing = service.enqueue(thread_id, user_input("existing")).await?;
let mut oversized = user_input(&"x".repeat(MAX_USER_INPUT_TEXT_CHARS / 2));
if let TurnInput::UserInput { content, .. } = &mut oversized {
content.push(UserInput::Text {
text: "y".repeat(MAX_USER_INPUT_TEXT_CHARS / 2 + 1),
text_elements: Vec::new(),
});
}
assert!(matches!(
service
.enqueue(thread_id, oversized.clone())
.await,
Err(QueueServiceError::InputTooLarge { actual_chars })
if actual_chars == MAX_USER_INPUT_TEXT_CHARS + 1
));
assert!(matches!(
service
.update(
thread_id,
existing.id.clone(),
oversized,
)
.await,
Err(QueueServiceError::InputTooLarge { actual_chars })
if actual_chars == MAX_USER_INPUT_TEXT_CHARS + 1
));
assert_eq!(vec![existing], service.list(thread_id).await?);
Ok(())
}
#[tokio::test]
async fn queued_text_limit_counts_characters_and_ignores_non_text_items() -> anyhow::Result<()> {
let (queue, _home) = test_queue().await?;
let service = QueuedItemService::new(queue, Weak::new(), Arc::new(NoopExtensionEventSink));
let mut input = structured_user_input(&"é".repeat(MAX_USER_INPUT_TEXT_CHARS));
if let TurnInput::UserInput { content, .. } = &mut input {
content.push(UserInput::Mention {
name: "Demo App".to_string(),
path: "app://demo-app".to_string(),
});
}
let queued = service.enqueue(ThreadId::new(), input.clone()).await?;
assert_eq!(input, queued.input);
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn invalid_head_is_skipped_and_a_live_user_turn_is_accepted() -> anyhow::Result<()> {
let server = start_mock_server().await;
let response =
responses::mount_sse_once(&server, responses::sse_completed("queued-turn")).await;
let test = test_codex()
.with_config(|config| config.include_environment_context = false)
.build_with_auto_env(&server)
.await?;
let thread_id = test.session_configured.thread_id;
let queue = loaded_thread_queue(&test)?;
queue
.enqueue(thread_id, r#"{"unsupported":true}"#.to_string())
.await?;
let service = QueuedItemService::new(
queue,
Arc::downgrade(&test.thread_manager),
Arc::new(NoopExtensionEventSink),
);
service
.enqueue(thread_id, structured_user_input("durable follow-up"))
.await?;
emit_idle(&service, thread_id).await;
let client_id = wait_for_event_match(test.codex.as_ref(), |event| match event {
EventMsg::ItemCompleted(event) => match &event.item {
TurnItem::UserMessage(item) => Some(item.client_id.clone()),
_ => None,
},
_ => None,
})
.await;
assert_eq!(Some("stable-client-message".to_string()), client_id);
wait_for_event_match(test.codex.as_ref(), |event| match event {
EventMsg::TurnComplete(_) => Some(()),
_ => None,
})
.await;
assert!(service.list(thread_id).await?.is_empty());
let request = response.single_request();
assert_eq!(
vec!["durable follow-up"],
request.message_input_texts("user")
);
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn resumed_idle_dispatches_input_persisted_without_a_loaded_manager() -> anyhow::Result<()> {
let server = start_mock_server().await;
responses::mount_sse_once(&server, responses::sse_completed("resumed-turn")).await;
let test = test_codex().build_with_auto_env(&server).await?;
let thread_id = test.session_configured.thread_id;
let queue = loaded_thread_queue(&test)?;
QueuedItemService::new(
Arc::clone(&queue),
Weak::new(),
Arc::new(NoopExtensionEventSink),
)
.enqueue(thread_id, user_input("queued while unloaded"))
.await?;
let service = QueuedItemService::new(
queue,
Arc::downgrade(&test.thread_manager),
Arc::new(NoopExtensionEventSink),
);
emit_idle(&service, thread_id).await;
assert!(service.list(thread_id).await?.is_empty());
Ok(())
}