app-server: Move watch_id to request of fs/watch (#17026)

It's easier for clients to maintain watchers if they define the watch id, so move it into the request. It's not used yet, so should be a safe change.
2026-04-30 19:32:04 +03:00 · 2026-04-07 11:22:28 -07:00
parent 252d79f5eb
commit 8a13f82204
17 changed files with 171 additions and 113 deletions
--- a/codex-rs/app-server-protocol/schema/json/ClientRequest.json
+++ b/codex-rs/app-server-protocol/schema/json/ClientRequest.json
@@ -800,7 +800,7 @@
      "description": "Stop filesystem watch notifications for a prior `fs/watch`.",
      "properties": {
        "watchId": {
-          "description": "Watch identifier returned by `fs/watch`.",
+          "description": "Watch identifier previously provided to `fs/watch`.",
          "type": "string"
        }
      },
@@ -819,10 +819,15 @@
            }
          ],
          "description": "Absolute file or directory path to watch."
+        },
+        "watchId": {
+          "description": "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
+          "type": "string"
        }
      },
      "required": [
-        "path"
+        "path",
+        "watchId"
      ],
      "type": "object"
    },
--- a/codex-rs/app-server-protocol/schema/json/ServerNotification.json
+++ b/codex-rs/app-server-protocol/schema/json/ServerNotification.json
@@ -1013,7 +1013,7 @@
          "type": "array"
        },
        "watchId": {
-          "description": "Watch identifier returned by `fs/watch`.",
+          "description": "Watch identifier previously provided to `fs/watch`.",
          "type": "string"
        }
      },
--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
@@ -7511,7 +7511,7 @@
            "type": "array"
          },
          "watchId": {
-            "description": "Watch identifier returned by `fs/watch`.",
+            "description": "Watch identifier previously provided to `fs/watch`.",
            "type": "string"
          }
        },
@@ -7781,7 +7781,7 @@
        "description": "Stop filesystem watch notifications for a prior `fs/watch`.",
        "properties": {
          "watchId": {
-            "description": "Watch identifier returned by `fs/watch`.",
+            "description": "Watch identifier previously provided to `fs/watch`.",
            "type": "string"
          }
        },
@@ -7808,25 +7808,6 @@
              }
            ],
            "description": "Absolute file or directory path to watch."
-          }
-        },
-        "required": [
-          "path"
-        ],
-        "title": "FsWatchParams",
-        "type": "object"
-      },
-      "FsWatchResponse": {
-        "$schema": "http://json-schema.org/draft-07/schema#",
-        "description": "Created watch handle returned by `fs/watch`.",
-        "properties": {
-          "path": {
-            "allOf": [
-              {
-                "$ref": "#/definitions/v2/AbsolutePathBuf"
-              }
-            ],
-            "description": "Canonicalized path associated with the watch."
          },
          "watchId": {
            "description": "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
@@ -7837,6 +7818,25 @@
          "path",
          "watchId"
        ],
+        "title": "FsWatchParams",
+        "type": "object"
+      },
+      "FsWatchResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Successful response for `fs/watch`.",
+        "properties": {
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Canonicalized path associated with the watch."
+          }
+        },
+        "required": [
+          "path"
+        ],
        "title": "FsWatchResponse",
        "type": "object"
      },
--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
@@ -4179,7 +4179,7 @@
          "type": "array"
        },
        "watchId": {
-          "description": "Watch identifier returned by `fs/watch`.",
+          "description": "Watch identifier previously provided to `fs/watch`.",
          "type": "string"
        }
      },
@@ -4449,7 +4449,7 @@
      "description": "Stop filesystem watch notifications for a prior `fs/watch`.",
      "properties": {
        "watchId": {
-          "description": "Watch identifier returned by `fs/watch`.",
+          "description": "Watch identifier previously provided to `fs/watch`.",
          "type": "string"
        }
      },
@@ -4476,25 +4476,6 @@
            }
          ],
          "description": "Absolute file or directory path to watch."
-        }
-      },
-      "required": [
-        "path"
-      ],
-      "title": "FsWatchParams",
-      "type": "object"
-    },
-    "FsWatchResponse": {
-      "$schema": "http://json-schema.org/draft-07/schema#",
-      "description": "Created watch handle returned by `fs/watch`.",
-      "properties": {
-        "path": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/AbsolutePathBuf"
-            }
-          ],
-          "description": "Canonicalized path associated with the watch."
        },
        "watchId": {
          "description": "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
@@ -4505,6 +4486,25 @@
        "path",
        "watchId"
      ],
+      "title": "FsWatchParams",
+      "type": "object"
+    },
+    "FsWatchResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Successful response for `fs/watch`.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Canonicalized path associated with the watch."
+        }
+      },
+      "required": [
+        "path"
+      ],
      "title": "FsWatchResponse",
      "type": "object"
    },
--- a/codex-rs/app-server-protocol/schema/json/v2/FsChangedNotification.json
+++ b/codex-rs/app-server-protocol/schema/json/v2/FsChangedNotification.json
@@ -16,7 +16,7 @@
      "type": "array"
    },
    "watchId": {
-      "description": "Watch identifier returned by `fs/watch`.",
+      "description": "Watch identifier previously provided to `fs/watch`.",
      "type": "string"
    }
  },
--- a/codex-rs/app-server-protocol/schema/json/v2/FsUnwatchParams.json
+++ b/codex-rs/app-server-protocol/schema/json/v2/FsUnwatchParams.json
@@ -3,7 +3,7 @@
  "description": "Stop filesystem watch notifications for a prior `fs/watch`.",
  "properties": {
    "watchId": {
-      "description": "Watch identifier returned by `fs/watch`.",
+      "description": "Watch identifier previously provided to `fs/watch`.",
      "type": "string"
    }
  },
--- a/codex-rs/app-server-protocol/schema/json/v2/FsWatchParams.json
+++ b/codex-rs/app-server-protocol/schema/json/v2/FsWatchParams.json
@@ -15,10 +15,15 @@
        }
      ],
      "description": "Absolute file or directory path to watch."
+    },
+    "watchId": {
+      "description": "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
+      "type": "string"
    }
  },
  "required": [
-    "path"
+    "path",
+    "watchId"
  ],
  "title": "FsWatchParams",
  "type": "object"
--- a/codex-rs/app-server-protocol/schema/json/v2/FsWatchResponse.json
+++ b/codex-rs/app-server-protocol/schema/json/v2/FsWatchResponse.json
@@ -6,7 +6,7 @@
      "type": "string"
    }
  },
-  "description": "Created watch handle returned by `fs/watch`.",
+  "description": "Successful response for `fs/watch`.",
  "properties": {
    "path": {
      "allOf": [
@@ -15,15 +15,10 @@
        }
      ],
      "description": "Canonicalized path associated with the watch."
-    },
-    "watchId": {
-      "description": "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
-      "type": "string"
    }
  },
  "required": [
-    "path",
-    "watchId"
+    "path"
  ],
  "title": "FsWatchResponse",
  "type": "object"
--- a/codex-rs/app-server-protocol/schema/typescript/v2/FsChangedNotification.ts
+++ b/codex-rs/app-server-protocol/schema/typescript/v2/FsChangedNotification.ts
@@ -8,7 +8,7 @@ import type { AbsolutePathBuf } from "../AbsolutePathBuf";
 */
 export type FsChangedNotification = { 
 /**
- * Watch identifier returned by `fs/watch`.
+ * Watch identifier previously provided to `fs/watch`.
 */
 watchId: string, 
 /**
--- a/codex-rs/app-server-protocol/schema/typescript/v2/FsUnwatchParams.ts
+++ b/codex-rs/app-server-protocol/schema/typescript/v2/FsUnwatchParams.ts
@@ -7,6 +7,6 @@
 */
 export type FsUnwatchParams = { 
 /**
- * Watch identifier returned by `fs/watch`.
+ * Watch identifier previously provided to `fs/watch`.
 */
 watchId: string, };
--- a/codex-rs/app-server-protocol/schema/typescript/v2/FsWatchParams.ts
+++ b/codex-rs/app-server-protocol/schema/typescript/v2/FsWatchParams.ts
@@ -7,6 +7,10 @@ import type { AbsolutePathBuf } from "../AbsolutePathBuf";
 * Start filesystem watch notifications for an absolute path.
 */
 export type FsWatchParams = { 
+/**
+ * Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.
+ */
+watchId: string, 
 /**
 * Absolute file or directory path to watch.
 */
--- a/codex-rs/app-server-protocol/schema/typescript/v2/FsWatchResponse.ts
+++ b/codex-rs/app-server-protocol/schema/typescript/v2/FsWatchResponse.ts
@@ -4,13 +4,9 @@
 import type { AbsolutePathBuf } from "../AbsolutePathBuf";

 /**
- * Created watch handle returned by `fs/watch`.
+ * Successful response for `fs/watch`.
 */
 export type FsWatchResponse = { 
-/**
- * Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.
- */
-watchId: string, 
 /**
 * Canonicalized path associated with the watch.
 */