app-server: document thread and turn IDs are UUID7 (#27714)

It's actually a very nice property that these are UUID7s, so documenting
them so we think twice before changing it away from UUID7s in the
future.

codex-rs/app-server-protocol/schema/json/ServerNotification.json

@@ -3626,6 +3626,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -5111,6 +5112,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json

@@ -16831,6 +16831,7 @@
             "description": "Optional Git metadata captured when the thread was created."
           },
           "id": {
+            "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
             "type": "string"
           },
           "modelProvider": {
@@ -19699,6 +19700,7 @@
             "description": "Only populated when the Turn's status is failed."
           },
           "id": {
+            "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
             "type": "string"
           },
           "items": {

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json

@@ -14610,6 +14610,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -17478,6 +17479,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ReviewStartResponse.json

@@ -1438,6 +1438,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadForkResponse.json

@@ -1059,6 +1059,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -2017,6 +2018,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.json

@@ -865,6 +865,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -1823,6 +1824,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadMetadataUpdateResponse.json

@@ -865,6 +865,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -1823,6 +1824,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadReadResponse.json

@@ -865,6 +865,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -1823,6 +1824,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadResumeResponse.json

@@ -1059,6 +1059,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -2017,6 +2018,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadRollbackResponse.json

@@ -865,6 +865,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -1823,6 +1824,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadStartResponse.json

@@ -1059,6 +1059,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -2017,6 +2018,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadStartedNotification.json

@@ -865,6 +865,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -1823,6 +1824,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/ThreadUnarchiveResponse.json

@@ -865,6 +865,7 @@
           "description": "Optional Git metadata captured when the thread was created."
         },
         "id": {
+          "description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
           "type": "string"
         },
         "modelProvider": {
@@ -1823,6 +1824,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/TurnCompletedNotification.json

@@ -1438,6 +1438,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/TurnStartResponse.json

@@ -1438,6 +1438,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/json/v2/TurnStartedNotification.json

@@ -1438,6 +1438,7 @@
           "description": "Only populated when the Turn's status is failed."
         },
         "id": {
+          "description": "Identifier for this turn. Codex-generated turn IDs are UUIDv7.",
           "type": "string"
         },
         "items": {

codex-rs/app-server-protocol/schema/typescript/ThreadId.ts

@@ -2,4 +2,9 @@
 
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
+/**
+ * Identifier for a Codex thread.
+ *
+ * Codex-generated thread IDs are UUIDv7, and some use cases rely on that.
+ */
 export type ThreadId = string;

codex-rs/app-server-protocol/schema/typescript/v2/Thread.ts

@@ -8,7 +8,11 @@ import type { ThreadSource } from "./ThreadSource";
 import type { ThreadStatus } from "./ThreadStatus";
 import type { Turn } from "./Turn";
 
-export type Thread = { id: string,
+export type Thread = {
+/**
+ * Identifier for this thread. Codex-generated thread IDs are UUIDv7.
+ */
+id: string,
 /**
  * Session id shared by threads that belong to the same session tree.
  */

codex-rs/app-server-protocol/schema/typescript/v2/Turn.ts

@@ -6,7 +6,11 @@ import type { TurnError } from "./TurnError";
 import type { TurnItemsView } from "./TurnItemsView";
 import type { TurnStatus } from "./TurnStatus";
 
-export type Turn = { id: string,
+export type Turn = {
+/**
+ * Identifier for this turn. Codex-generated turn IDs are UUIDv7.
+ */
+id: string,
 /**
  * Thread items currently included in this turn payload.
  */

codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs

@@ -133,6 +133,7 @@ pub struct GitInfo {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct Thread {
+    /// Identifier for this thread. Codex-generated thread IDs are UUIDv7.
     pub id: String,
     /// Session id shared by threads that belong to the same session tree.
     pub session_id: String,
@@ -186,6 +187,7 @@ pub struct Thread {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct Turn {
+    /// Identifier for this turn. Codex-generated turn IDs are UUIDv7.
     pub id: String,
     /// Thread items currently included in this turn payload.
     pub items: Vec<ThreadItem>,

codex-rs/core/src/session/mod.rs

@@ -724,7 +724,7 @@ impl Codex {
         op: Op,
         trace: Option<W3cTraceContext>,
     ) -> CodexResult<String> {
-        let id = Uuid::now_v7().to_string();
+        let id = new_submission_id();
         let sub = Submission {
             id: id.clone(),
             op,
@@ -742,7 +742,7 @@ impl Codex {
         client_user_message_id: Option<String>,
     ) -> CodexResult<String> {
         debug_assert!(matches!(op, Op::UserInput { .. }));
-        let id = Uuid::now_v7().to_string();
+        let id = new_submission_id();
         let sub = Submission {
             id: id.clone(),
             op,
@@ -869,6 +869,15 @@ impl Codex {
     }
 }
 
+/// Generate a core submission ID. App-server exposes submission IDs that
+/// create turns as a public-facing turn ID.
+///
+/// Some use cases take advantage of the fact that these are UUID7 which
+/// encodes a timestamp, so think carefully before changing this.
+fn new_submission_id() -> String {
+    Uuid::now_v7().to_string()
+}
+
 fn get_service_tier(
     configured_service_tier: Option<String>,
     fast_mode_enabled: bool,

codex-rs/protocol/src/thread_id.rs

@@ -10,6 +10,9 @@ use uuid::Uuid;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, TS, Hash)]
 #[ts(type = "string")]
+/// Identifier for a Codex thread.
+///
+/// Codex-generated thread IDs are UUIDv7, and some use cases rely on that.
 pub struct ThreadId {
     pub(crate) uuid: Uuid,
 }