Add experimental app-server project APIs (#38940)

## What changed

- Add SQLite-backed `project/list`, `project/read`, `project/create`,
  `project/import`, `project/update`, `project/move`, and `project/delete`
  endpoints with ordered roots, metadata, manual positioning, pagination, and
  idempotent creation.
- Add project assignment to thread start, metadata updates, list filtering,
  and fork inheritance. Project deletion clears assignments without deleting
  threads.
- Emit `project/changed` and `thread/project/updated` notifications after
  committed changes, and export the new protocol schemas and TypeScript types.

## Testing

- Cover project lifecycle and ordering, idempotency, atomic imports, cursor and
  filter validation, thread assignment, deletion, and fork inheritance.

GitOrigin-RevId: 47ae621be01ab8ef70a74a629fb29a5c5709ea33
This commit is contained in:
Anton Panasenko authored and copyberry committed 2026-08-17 04:01:37 +00:00
1 parent 1f41cc5d92
commit 3b4569a920
107 files changed
+4210 -52

No files matched your search

@@ -612,6 +612,7 @@ client_request_definitions! {
},
ThreadMetadataUpdate => "thread/metadata/update" {
params: v2::ThreadMetadataUpdateParams,
inspect_params: true,
serialization: thread_id(params.thread_id),
response: v2::ThreadMetadataUpdateResponse,
},
@@ -694,6 +695,48 @@ client_request_definitions! {
serialization: None,
response: v2::ThreadListResponse,
},
#[experimental("project/list")]
ProjectList => "project/list" {
params: v2::ProjectListParams,
serialization: global_shared_read("projects"),
response: v2::ProjectListResponse,
},
#[experimental("project/read")]
ProjectRead => "project/read" {
params: v2::ProjectReadParams,
serialization: global_shared_read("projects"),
response: v2::ProjectReadResponse,
},
#[experimental("project/create")]
ProjectCreate => "project/create" {
params: v2::ProjectCreateParams,
serialization: global("projects"),
response: v2::ProjectCreateResponse,
},
#[experimental("project/import")]
ProjectImport => "project/import" {
params: v2::ProjectImportParams,
serialization: global("projects"),
response: v2::ProjectImportResponse,
},
#[experimental("project/update")]
ProjectUpdate => "project/update" {
params: v2::ProjectUpdateParams,
serialization: global("projects"),
response: v2::ProjectUpdateResponse,
},
#[experimental("project/move")]
ProjectMove => "project/move" {
params: v2::ProjectMoveParams,
serialization: global("projects"),
response: v2::ProjectMoveResponse,
},
#[experimental("project/delete")]
ProjectDelete => "project/delete" {
params: v2::ProjectDeleteParams,
serialization: global("projects"),
response: v2::ProjectDeleteResponse,
},
ThreadSectionList => "threadSection/list" {
params: v2::ThreadSectionListParams,
serialization: global_shared_read("thread-sections"),
@@ -1761,6 +1804,10 @@ server_notification_definitions! {
ThreadGoalCleared => "thread/goal/cleared" (v2::ThreadGoalClearedNotification),
#[experimental("thread/queue/changed")]
ThreadQueueChanged => "thread/queue/changed" (v2::ThreadQueueChangedNotification),
#[experimental("project/changed")]
ProjectChanged => "project/changed" (v2::ProjectChangedNotification),
#[experimental("thread/project/updated")]
ThreadProjectUpdated => "thread/project/updated" (v2::ThreadProjectUpdatedNotification),
#[experimental("thread/environment/connected")]
EnvironmentConnected => "thread/environment/connected" (v2::EnvironmentConnectionNotification),
#[experimental("thread/environment/disconnected")]
@@ -2992,6 +3039,7 @@ mod tests {
ephemeral: true,
section: None,
section_entered_at: None,
project_id: None,
history_mode: Default::default(),
model_provider: "openai".to_string(),
created_at: 1,
@@ -3046,6 +3094,7 @@ mod tests {
"ephemeral": true,
"section": null,
"sectionEnteredAt": null,
"projectId": null,
"historyMode": "legacy",
"modelProvider": "openai",
"createdAt": 1,
@@ -21,6 +21,7 @@ mod permissions;
mod plugin;
mod plugin_search;
mod process;
mod project;
mod realtime;
mod remote_control;
mod review;
@@ -51,6 +52,7 @@ pub use permissions::*;
pub use plugin::*;
pub use plugin_search::*;
pub use process::*;
pub use project::*;
pub use realtime::*;
pub use remote_control::*;
pub use review::*;
@@ -0,0 +1,176 @@
use std::collections::BTreeMap;
use crate::JsonSchema;
use crate::TS;
use codex_experimental_api_macros::ExperimentalApi;
use codex_utils_absolute_path::AbsolutePathBuf;
use serde::Deserialize;
use serde::Serialize;
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectRoot {
pub path: AbsolutePathBuf,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct Project {
pub id: String,
pub name: String,
pub roots: Vec<ProjectRoot>,
pub metadata: BTreeMap<String, String>,
#[ts(type = "number")]
pub position: i64,
#[ts(type = "number")]
pub created_at: i64,
#[ts(type = "number")]
pub updated_at: i64,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectListParams {
#[ts(optional = nullable)]
pub cursor: Option<String>,
#[ts(optional = nullable)]
pub limit: Option<u32>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectListResponse {
pub data: Vec<Project>,
pub next_cursor: Option<String>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectReadParams {
pub project_id: String,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectReadResponse {
pub project: Project,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectCreateParams {
pub name: String,
pub roots: Vec<ProjectRoot>,
#[ts(optional = nullable)]
pub metadata: Option<BTreeMap<String, String>>,
pub idempotency_key: String,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectCreateResponse {
pub project: Project,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectImportParams {
pub name: String,
pub roots: Vec<ProjectRoot>,
#[ts(optional = nullable)]
pub metadata: Option<BTreeMap<String, String>>,
#[ts(optional = nullable)]
pub threads: Option<Vec<String>>,
pub idempotency_key: String,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectImportResponse {
pub project: Project,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectUpdateParams {
pub project_id: String,
#[ts(optional = nullable)]
pub name: Option<String>,
#[ts(optional = nullable)]
pub roots: Option<Vec<ProjectRoot>>,
#[ts(optional = nullable)]
pub metadata: Option<BTreeMap<String, String>>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectUpdateResponse {
pub project: Project,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectMoveParams {
pub project_id: String,
#[ts(optional = nullable)]
pub before_project_id: Option<String>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectMoveResponse {}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectDeleteParams {
pub project_id: String,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectDeleteResponse {}
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub enum ProjectChangeType {
Created,
Updated,
Deleted,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ProjectChangedNotification {
pub project_id: String,
pub change_type: ProjectChangeType,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ThreadProjectUpdatedNotification {
pub thread_id: String,
#[schemars(
required,
schema_with = "crate::protocol::serde_helpers::nullable_string_schema"
)]
pub project_id: Option<String>,
}
@@ -258,6 +258,7 @@ fn thread_resume_response_round_trips_initial_turns_page() {
appearance: None,
}),
section_entered_at: Some(1),
project_id: None,
history_mode: Default::default(),
model_provider: "openai".to_string(),
created_at: 1,
@@ -314,10 +315,12 @@ fn thread_resume_response_round_trips_initial_turns_page() {
.expect("serialized thread should be an object");
legacy_thread_fields.remove("section");
legacy_thread_fields.remove("sectionEnteredAt");
legacy_thread_fields.remove("projectId");
let legacy_thread =
serde_json::from_value::<Thread>(legacy_thread).expect("deserialize legacy thread");
assert_eq!(legacy_thread.section, None);
assert_eq!(legacy_thread.section_entered_at, None);
assert_eq!(legacy_thread.project_id, None);
assert_eq!(
value.get("initialTurnsPage"),
@@ -118,6 +118,11 @@ pub struct ThreadStartParams {
/// Optional client-supplied analytics source classification for this thread.
#[ts(optional = nullable)]
pub thread_source: Option<ThreadSource>,
/// Optional project identity for this new thread. Durable threads persist
/// the assignment; ephemeral threads expose it only in live responses.
#[experimental("thread/start.projectId")]
#[ts(optional = nullable)]
pub project_id: Option<String>,
/// Optional sticky environments for this thread.
///
/// Omitted selects the default environment when environment access is
@@ -858,7 +863,7 @@ pub struct ThreadGoalClearResponse {
pub cleared: bool,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct QueuedSubmission {
@@ -965,11 +970,16 @@ pub struct ThreadQueueStartResponse {
pub turn: Turn,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ThreadMetadataUpdateParams {
pub thread_id: String,
/// Omit to leave the project unchanged, use an empty string to clear it,
/// or provide an existing project ID to assign it.
#[experimental("thread/metadata/update.projectId")]
#[ts(optional = nullable)]
pub project_id: Option<String>,
/// Patch the stored Git metadata for this thread.
/// Omit a field to leave it unchanged, set it to `null` to clear it, or
/// provide a string to replace the stored value.
@@ -1381,6 +1391,17 @@ pub struct ThreadListParams {
)]
#[ts(optional = nullable, type = "string | null")]
pub section_id: Option<Option<String>>,
/// Omit to include every project, set to null for unassigned threads,
/// or provide a project ID to return only threads in that project.
#[experimental("thread/list.projectId")]
#[serde(
default,
skip_serializing_if = "Option::is_none",
serialize_with = "crate::protocol::serde_helpers::serialize_double_option",
deserialize_with = "crate::protocol::serde_helpers::deserialize_double_option"
)]
#[ts(optional = nullable, type = "string | null")]
pub project_id: Option<Option<String>>,
/// Optional cwd filter or filters; when set, only threads whose session cwd
/// exactly matches one of these paths are returned.
#[ts(optional = nullable, type = "string | Array<string> | null")]
@@ -190,7 +190,7 @@ pub struct ThreadSectionAppearance {
pub color: Option<String>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]
#[derive(Serialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct Thread {
@@ -216,6 +216,12 @@ pub struct Thread {
#[serde(default)]
#[ts(type = "number | null")]
pub section_entered_at: Option<i64>,
/// Canonical project assignment owned by app-server, if any.
#[schemars(
required,
schema_with = "crate::protocol::serde_helpers::nullable_string_schema"
)]
pub project_id: Option<String>,
/// Persisted thread history contract selected when this thread was created.
#[experimental("thread.historyMode")]
#[serde(default)]
@@ -262,6 +268,82 @@ pub struct Thread {
pub turns: Vec<Turn>,
}
// TODO: Remove this compatibility decoder after app-server versions that omitted
// `projectId` have aged out of the supported TUI -> remote app-server version-skew window.
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct ThreadCompatibility {
id: String,
extra: Option<ThreadExtra>,
session_id: String,
forked_from_id: Option<String>,
parent_thread_id: Option<String>,
preview: String,
ephemeral: bool,
#[serde(default)]
section: Option<ThreadSection>,
#[serde(default)]
section_entered_at: Option<i64>,
#[serde(default)]
project_id: Option<String>,
#[serde(default)]
history_mode: ThreadHistoryMode,
model_provider: String,
created_at: i64,
updated_at: i64,
recency_at: Option<i64>,
status: ThreadStatus,
path: Option<PathBuf>,
cwd: AbsolutePathBuf,
cli_version: String,
source: SessionSource,
can_accept_direct_input: Option<bool>,
thread_source: Option<ThreadSource>,
agent_nickname: Option<String>,
agent_role: Option<String>,
git_info: Option<GitInfo>,
name: Option<String>,
turns: Vec<Turn>,
}
impl<'de> Deserialize<'de> for Thread {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let thread = ThreadCompatibility::deserialize(deserializer)?;
Ok(Self {
id: thread.id,
extra: thread.extra,
session_id: thread.session_id,
forked_from_id: thread.forked_from_id,
parent_thread_id: thread.parent_thread_id,
preview: thread.preview,
ephemeral: thread.ephemeral,
section: thread.section,
section_entered_at: thread.section_entered_at,
project_id: thread.project_id,
history_mode: thread.history_mode,
model_provider: thread.model_provider,
created_at: thread.created_at,
updated_at: thread.updated_at,
recency_at: thread.recency_at,
status: thread.status,
path: thread.path,
cwd: thread.cwd,
cli_version: thread.cli_version,
source: thread.source,
can_accept_direct_input: thread.can_accept_direct_input,
thread_source: thread.thread_source,
agent_nickname: thread.agent_nickname,
agent_role: thread.agent_role,
git_info: thread.git_info,
name: thread.name,
turns: thread.turns,
})
}
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]