changeset: add required changeKind field to Changeset

CHANGELOG.md

@@ -27,6 +27,9 @@ changes accumulate. Track in-flight protocol changes via PRs touching
 
 Spec version: `0.3.0`
 
+- Added `changeKind` to `Changeset` (well-known values: `'session'`,
+  `'branch'`, `'uncommitted'`, `'turn'`, `'compare-turns'`) so clients can
+  group, sort, or pick an icon without parsing `uriTemplate`.
 - Added `status` and `error` to `ChangesetOperation` and a new
   `changeset/operationStatusChanged` action so servers can reflect an
   operation's execution lifecycle (`idle → running → error`) back into

clients/go/CHANGELOG.md

@@ -16,6 +16,8 @@ tag whose matching `## [X.Y.Z]` heading is missing from this file.
 
 ### Added
 
+- `changeKind` field on `Changeset` (well-known values: `'session'`,
+  `'branch'`, `'uncommitted'`, `'turn'`, `'compare-turns'`).
 - `status` and `error` fields on `ChangesetOperation` and the
   `changeset/operationStatusChanged` action, tracking the
   `idle → running → error` lifecycle of a changeset operation.

clients/go/ahptypes/state.generated.go

@@ -2056,6 +2056,24 @@ type Changeset struct {
 	UriTemplate string `json:"uriTemplate"`
 	// Optional longer description.
 	Description *string `json:"description,omitempty"`
+	// Advisory hint describing what kind of changeset this is, so clients can
+	// group, sort, or render an appropriate icon without parsing
+	// {@link uriTemplate}. Recognized values include:
+	//
+	// - `'session'`: a static, session-wide changeset covering all changes the
+	//   agent has produced in this session.
+	// - `'branch'`: changes relative to a base branch (e.g. a feature branch
+	//   diffed against `main`).
+	// - `'uncommitted'`: the workspace's current uncommitted changes.
+	// - `'turn'`: changes produced by a single turn. Typically paired with a
+	//   `{turnId}` variable in {@link uriTemplate}.
+	// - `'compare-turns'`: a diff between two turns. Typically paired with
+	//   `{originalTurnId}` and `{modifiedTurnId}` variables in
+	//   {@link uriTemplate}.
+	//
+	// Implementations MAY provide additional values; clients SHOULD fall back
+	// to a reasonable default when an unknown value is encountered.
+	ChangeKind string `json:"changeKind"`
 }
 
 // Full state for a single changeset, returned when a client subscribes to

clients/kotlin/CHANGELOG.md

@@ -17,6 +17,8 @@ versions (`*-SNAPSHOT`) are explicitly rejected by the publish pipeline; bump
 
 ### Added
 
+- `changeKind` field on `Changeset` (well-known values: `'session'`,
+  `'branch'`, `'uncommitted'`, `'turn'`, `'compare-turns'`).
 - `status` and `error` fields on `ChangesetOperation` and the
   `changeset/operationStatusChanged` action, tracking the
   `idle → running → error` lifecycle of a changeset operation.

clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt

@@ -2967,7 +2967,27 @@ data class Changeset(
     /**
      * Optional longer description.
      */
-    val description: String? = null
+    val description: String? = null,
+    /**
+     * Advisory hint describing what kind of changeset this is, so clients can
+     * group, sort, or render an appropriate icon without parsing
+     * {@link uriTemplate}. Recognized values include:
+     * 
+     * - `'session'`: a static, session-wide changeset covering all changes the
+     * agent has produced in this session.
+     * - `'branch'`: changes relative to a base branch (e.g. a feature branch
+     * diffed against `main`).
+     * - `'uncommitted'`: the workspace's current uncommitted changes.
+     * - `'turn'`: changes produced by a single turn. Typically paired with a
+     * `{turnId}` variable in {@link uriTemplate}.
+     * - `'compare-turns'`: a diff between two turns. Typically paired with
+     * `{originalTurnId}` and `{modifiedTurnId}` variables in
+     * {@link uriTemplate}.
+     * 
+     * Implementations MAY provide additional values; clients SHOULD fall back
+     * to a reasonable default when an unknown value is encountered.
+     */
+    val changeKind: String
 )
 
 @Serializable

clients/rust/CHANGELOG.md

@@ -17,6 +17,8 @@ matching `## [X.Y.Z]` heading is missing from this file.
 
 ### Added
 
+- `changeKind` field on `Changeset` (well-known values: `'session'`,
+  `'branch'`, `'uncommitted'`, `'turn'`, `'compare-turns'`).
 - `status` and `error` fields on `ChangesetOperation` and the
   `changeset/operationStatusChanged` action, tracking the
   `idle → running → error` lifecycle of a changeset operation.

clients/rust/crates/ahp-types/src/state.rs

@@ -2499,6 +2499,24 @@ pub struct Changeset {
     /// Optional longer description.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
+    /// Advisory hint describing what kind of changeset this is, so clients can
+    /// group, sort, or render an appropriate icon without parsing
+    /// {@link uriTemplate}. Recognized values include:
+    ///
+    /// - `'session'`: a static, session-wide changeset covering all changes the
+    ///   agent has produced in this session.
+    /// - `'branch'`: changes relative to a base branch (e.g. a feature branch
+    ///   diffed against `main`).
+    /// - `'uncommitted'`: the workspace's current uncommitted changes.
+    /// - `'turn'`: changes produced by a single turn. Typically paired with a
+    ///   `{turnId}` variable in {@link uriTemplate}.
+    /// - `'compare-turns'`: a diff between two turns. Typically paired with
+    ///   `{originalTurnId}` and `{modifiedTurnId}` variables in
+    ///   {@link uriTemplate}.
+    ///
+    /// Implementations MAY provide additional values; clients SHOULD fall back
+    /// to a reasonable default when an unknown value is encountered.
+    pub change_kind: String,
 }
 
 /// Full state for a single changeset, returned when a client subscribes to

clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift

@@ -3242,15 +3242,35 @@ public struct Changeset: Codable, Sendable {
     public var uriTemplate: String
     /// Optional longer description.
     public var description: String?
+    /// Advisory hint describing what kind of changeset this is, so clients can
+    /// group, sort, or render an appropriate icon without parsing
+    /// {@link uriTemplate}. Recognized values include:
+    /// 
+    /// - `'session'`: a static, session-wide changeset covering all changes the
+    /// agent has produced in this session.
+    /// - `'branch'`: changes relative to a base branch (e.g. a feature branch
+    /// diffed against `main`).
+    /// - `'uncommitted'`: the workspace's current uncommitted changes.
+    /// - `'turn'`: changes produced by a single turn. Typically paired with a
+    /// `{turnId}` variable in {@link uriTemplate}.
+    /// - `'compare-turns'`: a diff between two turns. Typically paired with
+    /// `{originalTurnId}` and `{modifiedTurnId}` variables in
+    /// {@link uriTemplate}.
+    /// 
+    /// Implementations MAY provide additional values; clients SHOULD fall back
+    /// to a reasonable default when an unknown value is encountered.
+    public var changeKind: String
 
     public init(
         label: String,
         uriTemplate: String,
-        description: String? = nil
+        description: String? = nil,
+        changeKind: String
     ) {
         self.label = label
         self.uriTemplate = uriTemplate
         self.description = description
+        self.changeKind = changeKind
     }
 }
 

clients/swift/CHANGELOG.md

@@ -19,6 +19,8 @@ the tag matches the version pinned in [`VERSION`](VERSION).
 
 ### Added
 
+- `changeKind` field on `Changeset` (well-known values: `'session'`,
+  `'branch'`, `'uncommitted'`, `'turn'`, `'compare-turns'`).
 - `status` and `error` fields on `ChangesetOperation` and the
   `changeset/operationStatusChanged` action, tracking the
   `idle → running → error` lifecycle of a changeset operation.

clients/typescript/CHANGELOG.md

@@ -22,6 +22,8 @@ hotfix escape hatch.
 
 ### Added
 
+- `changeKind` field on `Changeset` (well-known values: `'session'`,
+  `'branch'`, `'uncommitted'`, `'turn'`, `'compare-turns'`).
 - `status` and `error` fields on `ChangesetOperation` and the
   `changeset/operationStatusChanged` action, tracking the
   `idle → running → error` lifecycle of a changeset operation.

docs/guide/changesets.md

@@ -28,6 +28,11 @@ Changeset {
   /** RFC 6570 URI template; expand to obtain a subscribable URI. */
   uriTemplate: string
   description?: string
+  /**
+   * Advisory hint: one of `'session'`, `'branch'`, `'uncommitted'`,
+   * `'turn'`, or `'compare-turns'`. Other values allowed.
+   */
+  changeKind: string
   additions?: number
   deletions?: number
   files?: number

schema/actions.schema.json

@@ -4884,11 +4884,16 @@
         "description": {
           "type": "string",
           "description": "Optional longer description."
+        },
+        "changeKind": {
+          "type": "string",
+          "description": "Advisory hint describing what kind of changeset this is, so clients can\ngroup, sort, or render an appropriate icon without parsing\n{@link uriTemplate}. Recognized values include:\n\n- `'session'`: a static, session-wide changeset covering all changes the\n  agent has produced in this session.\n- `'branch'`: changes relative to a base branch (e.g. a feature branch\n  diffed against `main`).\n- `'uncommitted'`: the workspace's current uncommitted changes.\n- `'turn'`: changes produced by a single turn. Typically paired with a\n  `{turnId}` variable in {@link uriTemplate}.\n- `'compare-turns'`: a diff between two turns. Typically paired with\n  `{originalTurnId}` and `{modifiedTurnId}` variables in\n  {@link uriTemplate}.\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered."
         }
       },
       "required": [
         "label",
-        "uriTemplate"
+        "uriTemplate",
+        "changeKind"
       ]
     },
     "ChangesetState": {

schema/commands.schema.json

@@ -4535,11 +4535,16 @@
         "description": {
           "type": "string",
           "description": "Optional longer description."
+        },
+        "changeKind": {
+          "type": "string",
+          "description": "Advisory hint describing what kind of changeset this is, so clients can\ngroup, sort, or render an appropriate icon without parsing\n{@link uriTemplate}. Recognized values include:\n\n- `'session'`: a static, session-wide changeset covering all changes the\n  agent has produced in this session.\n- `'branch'`: changes relative to a base branch (e.g. a feature branch\n  diffed against `main`).\n- `'uncommitted'`: the workspace's current uncommitted changes.\n- `'turn'`: changes produced by a single turn. Typically paired with a\n  `{turnId}` variable in {@link uriTemplate}.\n- `'compare-turns'`: a diff between two turns. Typically paired with\n  `{originalTurnId}` and `{modifiedTurnId}` variables in\n  {@link uriTemplate}.\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered."
         }
       },
       "required": [
         "label",
-        "uriTemplate"
+        "uriTemplate",
+        "changeKind"
       ]
     },
     "ChangesetState": {

schema/errors.schema.json

@@ -3467,11 +3467,16 @@
         "description": {
           "type": "string",
           "description": "Optional longer description."
+        },
+        "changeKind": {
+          "type": "string",
+          "description": "Advisory hint describing what kind of changeset this is, so clients can\ngroup, sort, or render an appropriate icon without parsing\n{@link uriTemplate}. Recognized values include:\n\n- `'session'`: a static, session-wide changeset covering all changes the\n  agent has produced in this session.\n- `'branch'`: changes relative to a base branch (e.g. a feature branch\n  diffed against `main`).\n- `'uncommitted'`: the workspace's current uncommitted changes.\n- `'turn'`: changes produced by a single turn. Typically paired with a\n  `{turnId}` variable in {@link uriTemplate}.\n- `'compare-turns'`: a diff between two turns. Typically paired with\n  `{originalTurnId}` and `{modifiedTurnId}` variables in\n  {@link uriTemplate}.\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered."
         }
       },
       "required": [
         "label",
-        "uriTemplate"
+        "uriTemplate",
+        "changeKind"
       ]
     },
     "ChangesetState": {

schema/notifications.schema.json

@@ -3592,11 +3592,16 @@
         "description": {
           "type": "string",
           "description": "Optional longer description."
+        },
+        "changeKind": {
+          "type": "string",
+          "description": "Advisory hint describing what kind of changeset this is, so clients can\ngroup, sort, or render an appropriate icon without parsing\n{@link uriTemplate}. Recognized values include:\n\n- `'session'`: a static, session-wide changeset covering all changes the\n  agent has produced in this session.\n- `'branch'`: changes relative to a base branch (e.g. a feature branch\n  diffed against `main`).\n- `'uncommitted'`: the workspace's current uncommitted changes.\n- `'turn'`: changes produced by a single turn. Typically paired with a\n  `{turnId}` variable in {@link uriTemplate}.\n- `'compare-turns'`: a diff between two turns. Typically paired with\n  `{originalTurnId}` and `{modifiedTurnId}` variables in\n  {@link uriTemplate}.\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered."
         }
       },
       "required": [
         "label",
-        "uriTemplate"
+        "uriTemplate",
+        "changeKind"
       ]
     },
     "ChangesetState": {

schema/state.schema.json

@@ -3378,11 +3378,16 @@
         "description": {
           "type": "string",
           "description": "Optional longer description."
+        },
+        "changeKind": {
+          "type": "string",
+          "description": "Advisory hint describing what kind of changeset this is, so clients can\ngroup, sort, or render an appropriate icon without parsing\n{@link uriTemplate}. Recognized values include:\n\n- `'session'`: a static, session-wide changeset covering all changes the\n  agent has produced in this session.\n- `'branch'`: changes relative to a base branch (e.g. a feature branch\n  diffed against `main`).\n- `'uncommitted'`: the workspace's current uncommitted changes.\n- `'turn'`: changes produced by a single turn. Typically paired with a\n  `{turnId}` variable in {@link uriTemplate}.\n- `'compare-turns'`: a diff between two turns. Typically paired with\n  `{originalTurnId}` and `{modifiedTurnId}` variables in\n  {@link uriTemplate}.\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered."
         }
       },
       "required": [
         "label",
-        "uriTemplate"
+        "uriTemplate",
+        "changeKind"
       ]
     },
     "ChangesetState": {

types/channels-changeset/state.ts

@@ -43,6 +43,26 @@ export interface Changeset {
   uriTemplate: string;
   /** Optional longer description. */
   description?: string;
+  /**
+   * Advisory hint describing what kind of changeset this is, so clients can
+   * group, sort, or render an appropriate icon without parsing
+   * {@link uriTemplate}. Recognized values include:
+   *
+   * - `'session'`: a static, session-wide changeset covering all changes the
+   *   agent has produced in this session.
+   * - `'branch'`: changes relative to a base branch (e.g. a feature branch
+   *   diffed against `main`).
+   * - `'uncommitted'`: the workspace's current uncommitted changes.
+   * - `'turn'`: changes produced by a single turn. Typically paired with a
+   *   `{turnId}` variable in {@link uriTemplate}.
+   * - `'compare-turns'`: a diff between two turns. Typically paired with
+   *   `{originalTurnId}` and `{modifiedTurnId}` variables in
+   *   {@link uriTemplate}.
+   *
+   * Implementations MAY provide additional values; clients SHOULD fall back
+   * to a reasonable default when an unknown value is encountered.
+   */
+  changeKind: string;
 }
 
 /**

types/test-cases/reducers/145-session-changesetschanged-sets-catalogue.json

@@ -19,7 +19,8 @@
       "changesets": [
         {
           "label": "Session Changes",
-          "uriTemplate": "copilot:/test-session/changeset/session"
+          "uriTemplate": "copilot:/test-session/changeset/session",
+          "changeKind": "session"
         }
       ]
     }
@@ -38,7 +39,8 @@
     "changesets": [
       {
         "label": "Session Changes",
-        "uriTemplate": "copilot:/test-session/changeset/session"
+        "uriTemplate": "copilot:/test-session/changeset/session",
+        "changeKind": "session"
       }
     ]
   }

types/test-cases/reducers/146-session-changesetschanged-clears-catalogue.json

@@ -15,7 +15,8 @@
     "changesets": [
       {
         "label": "Session Changes",
-        "uriTemplate": "copilot:/test-session/changeset/session"
+        "uriTemplate": "copilot:/test-session/changeset/session",
+        "changeKind": "session"
       }
     ]
   },