Add persisted thread pinning to the app server (#34840)

## What changed

- Add `isPinned` to thread responses and allow `thread/metadata/update` to pin or unpin stored threads.
- Add an `isPinned` filter to `thread/list`, including cursor-based pagination and combinations with relationship filters.
- Persist pin state in SQLite without modifying rollout files, default existing threads to unpinned, and preserve pins through reconciliation and archive transitions.

## Testing

- Cover protocol serialization, database migration and indexing, pin updates, filtered pagination, rollout reconciliation, and archive/unarchive behavior.

GitOrigin-RevId: c2eacabd6dae465e2ae6ce8a169e00740960cdb7
This commit is contained in:
joeytrasatti-openai authored and copyberry committed 2026-07-22 22:54:28 +00:00
1 parent d7e8f4c3dc
commit 400ee190c3
71 files changed
+1058 -60

No files matched your search

@@ -108,6 +108,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: true,
search_term: None,
relation_filter: None,
@@ -144,6 +144,7 @@ pub(super) fn stored_thread_from_rollout_item(
updated_at,
recency_at,
archived_at,
is_pinned: item.is_pinned,
cwd: item.cwd.unwrap_or_default(),
cli_version: item.cli_version.unwrap_or_default(),
source,
+21 -11
View File
@@ -97,15 +97,17 @@ pub(super) async fn list_rollout_threads(
sort_key: codex_rollout::ThreadSortKey,
sort_direction: codex_rollout::SortDirection,
) -> ThreadStoreResult<codex_rollout::ThreadsPage> {
if let Some(relation_filter) = params.relation_filter {
let relation_filter = match relation_filter {
ThreadRelationFilter::DirectChildrenOf(parent_thread_id) => {
codex_state::ThreadRelationFilter::DirectChildrenOf(parent_thread_id)
}
ThreadRelationFilter::DescendantsOf(ancestor_thread_id) => {
codex_state::ThreadRelationFilter::DescendantsOf(ancestor_thread_id)
}
};
if params.relation_filter.is_some() || params.is_pinned.is_some() {
let relation_filter = params
.relation_filter
.map(|relation_filter| match relation_filter {
ThreadRelationFilter::DirectChildrenOf(parent_thread_id) => {
codex_state::ThreadRelationFilter::DirectChildrenOf(parent_thread_id)
}
ThreadRelationFilter::DescendantsOf(ancestor_thread_id) => {
codex_state::ThreadRelationFilter::DescendantsOf(ancestor_thread_id)
}
});
let page = codex_rollout::state_db::list_threads_db(
state_db.as_deref(),
config.codex_home.as_path(),
@@ -116,13 +118,14 @@ pub(super) async fn list_rollout_threads(
params.allowed_sources.as_slice(),
params.model_providers.as_deref(),
params.cwd_filters.as_deref(),
Some(relation_filter),
relation_filter,
params.archived,
params.is_pinned,
params.search_term.as_deref(),
)
.await
.ok_or_else(|| ThreadStoreError::Internal {
message: "state DB unavailable for relationship-filtered thread listing".to_string(),
message: "state DB unavailable for filtered thread listing".to_string(),
})?;
return Ok(page.into());
}
@@ -236,6 +239,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: false,
search_term: None,
relation_filter: None,
@@ -296,6 +300,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: false,
search_term: Some("needle".to_string()),
relation_filter: None,
@@ -368,6 +373,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: false,
search_term: Some("canonical".to_string()),
relation_filter: None,
@@ -404,6 +410,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: false,
search_term: None,
relation_filter: None,
@@ -420,6 +427,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: true,
search_term: None,
relation_filter: None,
@@ -472,6 +480,7 @@ mod tests {
allowed_sources: vec![SessionSource::Cli],
model_providers: Some(vec!["test-provider".to_string()]),
cwd_filters: None,
is_pinned: None,
archived: false,
search_term: None,
relation_filter: None,
@@ -509,6 +518,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: false,
search_term: None,
relation_filter: None,
@@ -59,6 +59,7 @@ pub(super) async fn read_thread(
&& !rollout_thread.preview.is_empty()
{
rollout_thread.recency_at = thread.recency_at;
rollout_thread.is_pinned = thread.is_pinned;
if thread.name.is_some() {
rollout_thread.name = thread.name;
}
@@ -125,6 +126,7 @@ pub(super) async fn read_thread_by_rollout_path(
thread.name = sqlite_thread_name(&metadata);
}
thread.recency_at = metadata.recency_at;
thread.is_pinned = metadata.is_pinned;
thread.git_info = if thread.history_mode == ThreadHistoryMode::Paginated {
// A paginated rollout only has the initial Git tuple. Do not turn an explicit SQLite
// clear back into the stale rollout value while reading by path.
@@ -384,6 +386,7 @@ async fn stored_thread_from_sqlite_metadata(
updated_at: metadata.updated_at,
recency_at: metadata.recency_at,
archived_at: metadata.archived_at,
is_pinned: metadata.is_pinned,
cwd: metadata.cwd,
cli_version: metadata.cli_version,
source: parse_session_source(&metadata.source),
@@ -479,6 +482,7 @@ fn stored_thread_from_meta_line(
updated_at,
recency_at: updated_at,
archived_at: archived.then_some(updated_at),
is_pinned: false,
cwd: meta_line.meta.cwd,
cli_version: meta_line.meta.cli_version,
source: meta_line.meta.source,
@@ -93,6 +93,7 @@ pub(super) async fn search_threads(
allowed_sources: params.allowed_sources.clone(),
model_providers: None,
cwd_filters: None,
is_pinned: None,
archived: params.archived,
search_term: None,
relation_filter: None,
@@ -1,13 +1,12 @@
use codex_rollout::find_archived_thread_path_by_id_str;
use codex_rollout::read_thread_item_from_rollout;
use codex_rollout::rollout_date_parts;
use super::LocalThreadStore;
use super::helpers::matching_rollout_file_name;
use super::helpers::scoped_rollout_path;
use super::helpers::stored_thread_from_rollout_item;
use super::helpers::touch_modified_time;
use crate::ArchiveThreadParams;
use crate::ReadThreadParams;
use crate::StoredThread;
use crate::ThreadStoreError;
use crate::ThreadStoreResult;
@@ -79,25 +78,15 @@ pub(super) async fn unarchive_thread(
.await;
}
let item = read_thread_item_from_rollout(restored_path.clone())
.await
.ok_or_else(|| ThreadStoreError::Internal {
message: format!(
"failed to read unarchived thread {}",
restored_path.display()
),
})?;
stored_thread_from_rollout_item(
item,
/*archived*/ false,
store.config.default_model_provider_id.as_str(),
super::read_thread::read_thread(
store,
ReadThreadParams {
thread_id,
include_archived: false,
include_history: false,
},
)
.ok_or_else(|| ThreadStoreError::Internal {
message: format!(
"failed to read unarchived thread id from {}",
restored_path.display()
),
})
.await
}
#[cfg(test)]
@@ -175,15 +164,17 @@ mod tests {
builder.cli_version = Some("test_version".to_string());
let mut metadata = builder.build(config.default_model_provider_id.as_str());
metadata.archived_at = Some(metadata.updated_at);
metadata.is_pinned = true;
runtime
.upsert_thread(&metadata)
.await
.expect("state db upsert should succeed");
store
let unarchived = store
.unarchive_thread(ArchiveThreadParams { thread_id })
.await
.expect("unarchive thread");
assert!(unarchived.is_pinned);
let restored_path = home
.path()
@@ -197,5 +188,6 @@ mod tests {
assert_eq!(updated.rollout_path, restored_path);
assert_eq!(updated.archived_at, None);
assert_eq!(updated.recency_at, metadata.recency_at);
assert!(updated.is_pinned);
}
}
@@ -264,7 +264,7 @@ async fn apply_metadata_update(
let sqlite_write_result: ThreadStoreResult<()> = if let Some(state_db) = state_db.as_ref() {
let patch = patch.clone();
async {
let existing =
let mut existing =
state_db
.get_thread(thread_id)
.await
@@ -277,6 +277,30 @@ async fn apply_metadata_update(
rollout_path_archived = resolved.archived;
rollout_path = Some(resolved.path);
}
if existing.is_none()
&& patch.is_pinned.is_some()
&& let Some(path) = rollout_path.as_deref()
&& let Some(existing_rollout_path) =
codex_rollout::existing_rollout_path(path).await
{
codex_rollout::state_db::reconcile_rollout(
Some(state_db.as_ref()),
existing_rollout_path.as_path(),
store.config.default_model_provider_id.as_str(),
/*builder*/ None,
&[],
/*archived_only*/ Some(rollout_path_archived),
/*new_thread_memory_mode*/ None,
)
.await;
existing = state_db.get_thread(thread_id).await.map_err(|err| {
ThreadStoreError::Internal {
message: format!(
"failed to read reconciled thread metadata for {thread_id}: {err}"
),
}
})?;
}
let mut metadata = match existing.clone() {
Some(metadata) => metadata,
None => {
@@ -365,6 +389,9 @@ async fn apply_metadata_update(
if let Some(first_user_message) = patch.first_user_message {
metadata.first_user_message = Some(first_user_message);
}
if let Some(is_pinned) = patch.is_pinned {
metadata.is_pinned = is_pinned;
}
if let Some(git_info) = patch.git_info {
let existing_git_info = git_info_from_parts(
metadata.git_sha.clone(),
@@ -382,6 +409,23 @@ async fn apply_metadata_update(
.map_err(|err| ThreadStoreError::Internal {
message: format!("failed to update thread metadata for {thread_id}: {err}"),
})?;
if let Some(is_pinned) = patch.is_pinned {
let updated = state_db
.update_thread_pin(thread_id, is_pinned)
.await
.map_err(|err| ThreadStoreError::Internal {
message: format!(
"failed to update pin state for thread {thread_id}: {err}"
),
})?;
if !updated {
return Err(ThreadStoreError::Internal {
message: format!(
"thread metadata unavailable before pin update: {thread_id}"
),
});
}
}
if let Some(name) = patch.name.as_ref() {
let history_mode = history_mode.ok_or_else(|| ThreadStoreError::Internal {
message: format!(
@@ -546,8 +590,9 @@ fn sqlite_write_failure_should_block(patch: &ThreadMetadataPatch) -> bool {
// transcript-derived metadata, thread names, and memory-mode indexing were log-only. Keep that
// failure isolation so a corrupted optional state DB does not make JSONL transcript durability
// look broken. Explicit git-only updates still require SQLite because partial git patches need
// the existing SQLite value to preserve unspecified fields.
patch.git_info.is_some() && !has_observed_metadata_facts(patch)
// the existing SQLite value to preserve unspecified fields. User-selected pin state is
// SQLite-only, so losing its write must also fail the explicit metadata update.
patch.is_pinned.is_some() || (patch.git_info.is_some() && !has_observed_metadata_facts(patch))
}
fn sqlite_write_error_is_best_effort(err: &ThreadStoreError) -> bool {
@@ -845,6 +890,110 @@ mod tests {
assert_eq!(latest_name.as_deref(), Some("A sharper name"));
}
#[tokio::test]
async fn pin_only_metadata_updates_persist_in_sqlite_without_changing_the_rollout() {
let home = TempDir::new().expect("temp dir");
let config = test_config(home.path());
let uuid = Uuid::from_u128(320);
let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
let rollout_path =
write_session_file(home.path(), "2025-01-03T14-20-00", uuid).expect("session file");
let original_rollout = std::fs::read_to_string(&rollout_path).expect("read rollout");
let runtime = codex_state::StateRuntime::init(
home.path().to_path_buf(),
config.default_model_provider_id.clone(),
)
.await
.expect("state db should initialize");
let store = LocalThreadStore::new(config, Some(runtime.clone()));
let pinned = store
.update_thread_metadata(UpdateThreadMetadataParams {
thread_id,
patch: ThreadMetadataPatch {
is_pinned: Some(true),
..Default::default()
},
include_archived: false,
})
.await
.expect("pin thread");
assert!(pinned.is_pinned);
let pinned_metadata = runtime
.get_thread(thread_id)
.await
.expect("read pinned metadata")
.expect("pinned metadata");
assert!(pinned_metadata.is_pinned);
assert_eq!(pinned_metadata.preview.as_deref(), Some("Hello from user"));
assert_eq!(pinned_metadata.source, "cli");
let pinned_page = store
.list_threads(ListThreadsParams {
page_size: 10,
cursor: None,
sort_key: ThreadSortKey::RecencyAt,
sort_direction: SortDirection::Desc,
allowed_sources: Vec::new(),
model_providers: None,
cwd_filters: None,
is_pinned: Some(true),
archived: false,
search_term: None,
relation_filter: None,
use_state_db_only: true,
})
.await
.expect("list pinned thread");
assert_eq!(
pinned_page
.items
.iter()
.map(|thread| thread.thread_id)
.collect::<Vec<_>>(),
vec![thread_id]
);
let read_by_path = store
.read_thread_by_rollout_path(
rollout_path.clone(),
/*include_archived*/ false,
/*include_history*/ false,
)
.await
.expect("read pinned thread by rollout path");
assert!(read_by_path.is_pinned);
assert_eq!(
std::fs::read_to_string(&rollout_path).expect("read rollout"),
original_rollout
);
let unpinned = store
.update_thread_metadata(UpdateThreadMetadataParams {
thread_id,
patch: ThreadMetadataPatch {
is_pinned: Some(false),
..Default::default()
},
include_archived: false,
})
.await
.expect("unpin thread");
assert!(!unpinned.is_pinned);
assert!(
!runtime
.get_thread(thread_id)
.await
.expect("read unpinned metadata")
.expect("unpinned metadata")
.is_pinned
);
assert_eq!(
std::fs::read_to_string(&rollout_path).expect("read rollout"),
original_rollout
);
}
#[tokio::test]
async fn paginated_name_updates_use_sqlite_without_rollout_writes() {
let home = TempDir::new().expect("temp dir");
@@ -1647,6 +1796,14 @@ mod tests {
}));
}
#[test]
fn sqlite_failures_block_for_explicit_pin_updates() {
assert!(sqlite_write_failure_should_block(&ThreadMetadataPatch {
is_pinned: Some(false),
..Default::default()
}));
}
#[tokio::test]
async fn metadata_patch_applies_title_over_existing_name() {
let home = TempDir::new().expect("temp dir");
@@ -1920,6 +2077,7 @@ mod tests {
allowed_sources: Vec::new(),
model_providers: Some(Vec::new()),
cwd_filters: Some(vec![workspace]),
is_pinned: None,
archived: false,
search_term: None,
relation_filter: None,