feat(app-server): list descendant threads by ancestor (#29591)

## Why

`thread/list` can filter direct children with `parentThreadId`, but
clients cannot request an entire spawned subtree. Discovering every
descendant requires repeated client-side requests and gives up the
database's existing filtering and pagination path.

## What changed

Experimental clients can use `ancestorThreadId` to return strict
descendants at any depth while `parentThreadId` retains its direct-child
meaning. The filters are mutually exclusive, the ancestor is excluded,
and every result preserves its immediate `parentThreadId` so callers can
reconstruct the tree.

## How it works

- **Explicit relationship:** Internal list parameters distinguish direct
children from transitive descendants without changing the meaning of
`parentThreadId`.
- **Existing graph:** Persisted parent-child spawn edges remain the
source of truth, so descendant lookup needs no schema migration or
ancestry cache.
- **Indexed traversal:** A recursive SQLite query starts from the
parent-edge index, walks each generation, and applies thread filters,
sorting, and cursor pagination in the same database request.
- **Reconstructable results:** The response stays flat and normally
ordered while carrying each descendant's immediate parent.

## Verification

Ran 550 tests across the protocol, state, rollout, and thread-store
crates, then reran the four focused state, store, and app-server
descendant-listing tests after the final diff reduction. Scoped Clippy
and formatting checks passed. Stable and experimental schema generation
was checked; the stable fixtures remain unchanged while the experimental
schema includes the new field.
This commit is contained in:
Brent Traut authored and GitHub committed 2026-06-24 13:08:14 -07:00
1 parent 3ccef20ef4
commit 8057603d0c
30 files changed
+494 -106

No files matched your search

@@ -110,7 +110,7 @@ mod tests {
cwd_filters: None,
archived: true,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: false,
})
.await
+19 -14
View File
@@ -14,6 +14,7 @@ use super::helpers::stored_thread_from_rollout_item;
use crate::ListThreadsParams;
use crate::SortDirection;
use crate::ThreadPage;
use crate::ThreadRelationFilter;
use crate::ThreadSortKey;
use crate::ThreadStoreError;
use crate::ThreadStoreResult;
@@ -117,7 +118,15 @@ pub(super) async fn list_rollout_threads(
sort_key: codex_rollout::ThreadSortKey,
sort_direction: codex_rollout::SortDirection,
) -> ThreadStoreResult<codex_rollout::ThreadsPage> {
if let Some(parent_thread_id) = params.parent_thread_id {
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)
}
};
let page = codex_rollout::state_db::list_threads_db(
state_db.as_deref(),
config.codex_home.as_path(),
@@ -128,19 +137,15 @@ pub(super) async fn list_rollout_threads(
params.allowed_sources.as_slice(),
params.model_providers.as_deref(),
params.cwd_filters.as_deref(),
Some(parent_thread_id),
Some(relation_filter),
params.archived,
params.search_term.as_deref(),
)
.await
.ok_or_else(|| ThreadStoreError::Internal {
message: "state DB unavailable for parent-filtered thread listing".to_string(),
message: "state DB unavailable for relationship-filtered thread listing".to_string(),
})?;
let mut page: codex_rollout::ThreadsPage = page.into();
for item in &mut page.items {
item.parent_thread_id = Some(parent_thread_id);
}
return Ok(page);
return Ok(page.into());
}
let page = if params.use_state_db_only && params.archived {
@@ -252,7 +257,7 @@ mod tests {
cwd_filters: None,
archived: false,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: false,
})
.await
@@ -312,7 +317,7 @@ mod tests {
cwd_filters: None,
archived: false,
search_term: Some("needle".to_string()),
parent_thread_id: None,
relation_filter: None,
use_state_db_only: true,
})
.await
@@ -352,7 +357,7 @@ mod tests {
cwd_filters: None,
archived: false,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: false,
})
.await
@@ -368,7 +373,7 @@ mod tests {
cwd_filters: None,
archived: true,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: false,
})
.await
@@ -420,7 +425,7 @@ mod tests {
cwd_filters: None,
archived: false,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: false,
})
.await
@@ -457,7 +462,7 @@ mod tests {
cwd_filters: None,
archived: false,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: false,
})
.await
@@ -98,7 +98,7 @@ pub(super) async fn search_threads(
cwd_filters: None,
archived: params.archived,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: state_db.is_some(),
};
let mut remaining_rollouts = matching_rollouts;
@@ -1495,7 +1495,7 @@ mod tests {
cwd_filters: Some(vec![workspace]),
archived: false,
search_term: None,
parent_thread_id: None,
relation_filter: None,
use_state_db_only: true,
})
.await