From a6f459c6a757fdb8731548c71f37dfd8fa3618d4 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Wed, 24 Jun 2026 15:30:56 -0700 Subject: [PATCH] Move annotations channel changelog entries to 0.4.0 The annotations channel (state types, `annotations/set|removed|entrySet| entryRemoved` actions, `MessageAnnotationsAttachment`, `SessionSummary.annotations`) was documented under `## [0.3.0]` in every CHANGELOG and mapped to `'0.3.0'` in `ACTION_INTRODUCED_IN`, but it never shipped in `spec/v0.3.0`. Its sources first appear at the `spec/v0.4.0` tag, so the channel actually shipped in 0.4.0. Move the annotations bullets from `[0.3.0]` to `[0.4.0]` across all six changelogs and correct the registry's introduced-in versions to `0.4.0`, so `isActionKnownToVersion` no longer advertises annotations to peers negotiating `0.3.0`. Fixes #222 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 38 ++++++++++++++++++++------------- clients/go/CHANGELOG.md | 24 ++++++++++----------- clients/kotlin/CHANGELOG.md | 24 ++++++++++----------- clients/rust/CHANGELOG.md | 24 ++++++++++----------- clients/swift/CHANGELOG.md | 23 ++++++++++---------- clients/typescript/CHANGELOG.md | 27 +++++++++++++---------- types/version/registry.ts | 8 +++---- 7 files changed, 90 insertions(+), 78 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 634e9cb3..5f55ce7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,6 +49,14 @@ changes accumulate. Track in-flight protocol changes via PRs touching - `session/activeClientToolsChanged`. An active client now updates its published tools by re-dispatching `session/activeClientSet` with its full, updated entry. +### Fixed + +- Corrected the `ACTION_INTRODUCED_IN` entries for `annotations/set`, + `annotations/removed`, `annotations/entrySet`, and `annotations/entryRemoved` + from `0.3.0` to `0.4.0`. The annotations channel first shipped in the + `0.4.0` spec release (it is absent from `spec/v0.3.0`), so version + negotiation must not advertise it to peers speaking `0.3.0`. + ## [0.5.0] — Unreleased Spec version: `0.5.0` @@ -82,6 +90,21 @@ Spec version: `0.4.0` event to a specific agent (e.g. a sub-agent acting within the turn). The tool-call actions already exposed `_meta`; this extends the same convention to the remaining turn-scoped actions. +- Added a new annotations channel exposed on `ahp-session://annotations`. + Annotations anchor to a `(turnId, resource)` pair with an optional `range` + (omitted to anchor to the entire file), carry a `resolved` flag (newly + created annotations start unresolved), and always carry at least one entry. + Clients drive every mutation by dispatching the client-dispatchable + `annotations/set`, `annotations/removed`, `annotations/entrySet`, and + `annotations/entryRemoved` state actions directly — assigning the + `Annotation.id` / `AnnotationEntry.id` themselves — rather than through RPC + commands, so annotations inherit write-ahead replay and conflict resolution. + `SessionSummary.annotations` advertises the per-session `AnnotationsSummary` + (`{ resource, annotationCount, entryCount }`) for badge UI. +- Added an `annotations` `MessageAttachment` variant + (`MessageAnnotationsAttachment`) that references annotations on a + session's annotations channel by its `resource` URI, optionally narrowed to + an `annotationIds` array (omitted to reference every annotation). - `annotations/updated` (`AnnotationsUpdatedAction`) — a client-dispatchable action that partially updates an existing annotation's own properties (`turnId`, `resource`, `range`, `resolved`) without resending its entries. @@ -177,21 +200,6 @@ Spec version: `0.3.0` - Added optional `changes` field of type `ChangesSummary` to `SessionSummary`, carrying optional `additions`, `deletions`, and `files` counts so servers can advertise an at-a-glance view of a session's file-change footprint. -- Added a new annotations channel exposed on `ahp-session://annotations`. - Annotations anchor to a `(turnId, resource)` pair with an optional `range` - (omitted to anchor to the entire file), carry a `resolved` flag (newly - created annotations start unresolved), and always carry at least one entry. - Clients drive every mutation by dispatching the client-dispatchable - `annotations/set`, `annotations/removed`, `annotations/entrySet`, and - `annotations/entryRemoved` state actions directly — assigning the - `Annotation.id` / `AnnotationEntry.id` themselves — rather than through RPC - commands, so annotations inherit write-ahead replay and conflict resolution. - `SessionSummary.annotations` advertises the per-session `AnnotationsSummary` - (`{ resource, annotationCount, entryCount }`) for badge UI. -- Added an `annotations` `MessageAttachment` variant - (`MessageAnnotationsAttachment`) that references annotations on a - session's annotations channel by its `resource` URI, optionally narrowed to - an `annotationIds` array (omitted to reference every annotation). - Removed the `additions`, `deletions`, and `files` fields from `ChangesetSummary`. Aggregate counts now live on `SessionSummary.changes`; per-changeset views derive their own totals from `ChangesetState.files`. diff --git a/clients/go/CHANGELOG.md b/clients/go/CHANGELOG.md index 8c608bac..e8ff02d6 100644 --- a/clients/go/CHANGELOG.md +++ b/clients/go/CHANGELOG.md @@ -99,6 +99,18 @@ Implements AHP 0.4.0. ### Added +- New annotations channel wire types (`ahp-session://annotations`): + `AnnotationsState`, `Annotation`, `AnnotationEntry`, + `AnnotationsSummary`; the client-dispatchable `AnnotationsSetAction`, + `AnnotationsRemovedAction`, `AnnotationsEntrySetAction`, + `AnnotationsEntryRemovedAction` variants — clients drive every annotation + mutation by dispatching these directly, assigning the `Annotation.Id` / + `AnnotationEntry.Id` themselves; + `ApplyActionToAnnotations` (stub mirroring `ApplyActionToChangeset`); and + `SnapshotState.Annotations`. +- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) + referencing annotations on a session's annotations channel by `Resource` + URI, optionally narrowed to an `AnnotationIds` array. - `AnnotationsUpdatedAction` (`annotations/updated`) — partially updates an existing annotation's `TurnID` / `Resource` / `Range` / `Resolved` without resending its entries. Handled by the annotations reducer (no-op on unknown @@ -153,18 +165,6 @@ Implements AHP 0.3.0. `idle → running → error` lifecycle of a changeset operation. - `AgentCustomization._meta` provider metadata field. - Optional `changes` field on `SessionSummary` (`ChangesSummary` with optional `additions`, `deletions`, and `files` counts) summarising a session's file-change footprint. -- New annotations channel wire types (`ahp-session://annotations`): - `AnnotationsState`, `Annotation`, `AnnotationEntry`, - `AnnotationsSummary`; the client-dispatchable `AnnotationsSetAction`, - `AnnotationsRemovedAction`, `AnnotationsEntrySetAction`, - `AnnotationsEntryRemovedAction` variants — clients drive every annotation - mutation by dispatching these directly, assigning the `Annotation.Id` / - `AnnotationEntry.Id` themselves; - `ApplyActionToAnnotations` (stub mirroring `ApplyActionToChangeset`); and - `SnapshotState.Annotations`. -- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) - referencing annotations on a session's annotations channel by `Resource` - URI, optionally narrowed to an `AnnotationIds` array. ### Changed diff --git a/clients/kotlin/CHANGELOG.md b/clients/kotlin/CHANGELOG.md index 05a1a65f..9a564c32 100644 --- a/clients/kotlin/CHANGELOG.md +++ b/clients/kotlin/CHANGELOG.md @@ -95,6 +95,18 @@ Implements AHP 0.4.0. ### Added +- New annotations channel (`ahp-session://annotations`): `AnnotationsState`, + `Annotation`, `AnnotationEntry`, + `AnnotationsSummary`; the `annotationsReducer` top-level function and + `AnnotationsReducer` object; and the client-dispatchable `annotations/set`, + `annotations/removed`, `annotations/entrySet`, and `annotations/entryRemoved` + action variants — clients drive every annotation mutation by dispatching + these directly (assigning the `Annotation.id` / `AnnotationEntry.id` + themselves); and `SnapshotState.Annotations`. + `SessionSummary.annotations` surfaces the per-session `AnnotationsSummary`. +- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) + referencing annotations on a session's annotations channel by `resource` + URI, optionally narrowed to an `annotationIds` array. - `AnnotationsUpdatedAction` (`annotations/updated`) — partially updates an existing annotation's `turnId` / `resource` / `range` / `resolved` without resending its entries. Handled by the annotations reducer (no-op on unknown @@ -147,18 +159,6 @@ Implements AHP 0.3.0. `idle → running → error` lifecycle of a changeset operation. - `AgentCustomization._meta` provider metadata field. - Optional `changes` field on `SessionSummary` (`ChangesSummary` with optional `additions`, `deletions`, and `files` counts) summarising a session's file-change footprint. -- New annotations channel (`ahp-session://annotations`): `AnnotationsState`, - `Annotation`, `AnnotationEntry`, - `AnnotationsSummary`; the `annotationsReducer` top-level function and - `AnnotationsReducer` object; and the client-dispatchable `annotations/set`, - `annotations/removed`, `annotations/entrySet`, and `annotations/entryRemoved` - action variants — clients drive every annotation mutation by dispatching - these directly (assigning the `Annotation.id` / `AnnotationEntry.id` - themselves); and `SnapshotState.Annotations`. - `SessionSummary.annotations` surfaces the per-session `AnnotationsSummary`. -- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) - referencing annotations on a session's annotations channel by `resource` - URI, optionally narrowed to an `annotationIds` array. ### Changed diff --git a/clients/rust/CHANGELOG.md b/clients/rust/CHANGELOG.md index c21e9422..ed90eda0 100644 --- a/clients/rust/CHANGELOG.md +++ b/clients/rust/CHANGELOG.md @@ -116,6 +116,18 @@ Implements AHP 0.4.0. ### Added +- New annotations channel wire types (`ahp-session://annotations`): + `AnnotationsState`, `Annotation`, `AnnotationEntry`, + `AnnotationsSummary`; the client-dispatchable + `annotations/set` / `annotations/removed` / `annotations/entrySet` + / `annotations/entryRemoved` action variants — clients drive every annotation + mutation by dispatching these directly, assigning the `Annotation.id` / + `AnnotationEntry.id` themselves; + `MultiHostStateMirror.annotations()` and `SnapshotState::Annotations`. + Reducer logic is deferred (matches the changeset stub). +- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) + referencing annotations on a session's annotations channel by `resource` + URI, optionally narrowed to an `annotationIds` array. - `AnnotationsUpdatedAction` (`annotations/updated`) — partially updates an existing annotation's `turn_id` / `resource` / `range` / `resolved` without resending its entries. Handled by the annotations reducer (no-op on unknown @@ -169,18 +181,6 @@ Implements AHP 0.3.0. `idle → running → error` lifecycle of a changeset operation. - `AgentCustomization._meta` provider metadata field. - Optional `changes` field on `SessionSummary` (`ChangesSummary` with optional `additions`, `deletions`, and `files` counts) summarising a session's file-change footprint. -- New annotations channel wire types (`ahp-session://annotations`): - `AnnotationsState`, `Annotation`, `AnnotationEntry`, - `AnnotationsSummary`; the client-dispatchable - `annotations/set` / `annotations/removed` / `annotations/entrySet` - / `annotations/entryRemoved` action variants — clients drive every annotation - mutation by dispatching these directly, assigning the `Annotation.id` / - `AnnotationEntry.id` themselves; - `MultiHostStateMirror.annotations()` and `SnapshotState::Annotations`. - Reducer logic is deferred (matches the changeset stub). -- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) - referencing annotations on a session's annotations channel by `resource` - URI, optionally narrowed to an `annotationIds` array. ### Changed diff --git a/clients/swift/CHANGELOG.md b/clients/swift/CHANGELOG.md index 904caf74..c6d857ac 100644 --- a/clients/swift/CHANGELOG.md +++ b/clients/swift/CHANGELOG.md @@ -106,6 +106,17 @@ Implements AHP 0.4.0. ### Added +- New annotations channel wire types (`ahp-session://annotations`): + `AnnotationsState`, `Annotation`, `AnnotationEntry`, + `AnnotationsSummary`; and the client-dispatchable + `annotations/set` / `annotations/removed` / `annotations/entrySet` + / `annotations/entryRemoved` cases on `StateAction` — clients drive every + annotation mutation by dispatching these directly, assigning the + `Annotation.id` / `AnnotationEntry.id` themselves; and + `SnapshotState.annotations`. +- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) + referencing annotations on a session's annotations channel by `resource` + URI, optionally narrowed to an `annotationIds` array. - `annotationsReducer` implemented; annotations conformance fixtures (210–219) now pass. - `AnnotationsUpdatedAction` (`annotations/updated`) — partially updates an @@ -188,18 +199,6 @@ Implements AHP 0.3.0. `idle → running → error` lifecycle of a changeset operation. - `AgentCustomization._meta` provider metadata field. - Optional `changes` field on `SessionSummary` (`ChangesSummary` with optional `additions`, `deletions`, and `files` counts) summarising a session's file-change footprint. -- New annotations channel wire types (`ahp-session://annotations`): - `AnnotationsState`, `Annotation`, `AnnotationEntry`, - `AnnotationsSummary`; and the client-dispatchable - `annotations/set` / `annotations/removed` / `annotations/entrySet` - / `annotations/entryRemoved` cases on `StateAction` — clients drive every - annotation mutation by dispatching these directly, assigning the - `Annotation.id` / `AnnotationEntry.id` themselves; and - `SnapshotState.annotations`. - Reducer logic is deferred (matches the changeset/resource-watch parity). -- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) - referencing annotations on a session's annotations channel by `resource` - URI, optionally narrowed to an `annotationIds` array. ### Changed diff --git a/clients/typescript/CHANGELOG.md b/clients/typescript/CHANGELOG.md index 136c8d59..ab7e9ef7 100644 --- a/clients/typescript/CHANGELOG.md +++ b/clients/typescript/CHANGELOG.md @@ -53,6 +53,11 @@ hotfix escape hatch. - Hosted session summary caches now apply `_meta` updates from `root/sessionSummaryChanged` notifications. +- Corrected the `ACTION_INTRODUCED_IN` entries for `annotations/set`, + `annotations/removed`, `annotations/entrySet`, and `annotations/entryRemoved` + from `0.3.0` to `0.4.0`, so `isActionKnownToVersion` no longer reports the + annotations channel as available to peers negotiating `0.3.0` (it first + shipped in `0.4.0`). ## [0.4.0] — 2026-06-19 @@ -107,6 +112,17 @@ Implements AHP 0.4.0. ### Added +- New annotations channel (`ahp-session://annotations`): `AnnotationsState`, + `Annotation`, `AnnotationEntry`, `AnnotationsSummary`, + the `annotationsReducer`, and the client-dispatchable `annotations/set`, + `annotations/removed`, `annotations/entrySet`, and `annotations/entryRemoved` + actions — clients drive every annotation mutation by dispatching these + directly, assigning the `Annotation.id` / `AnnotationEntry.id` themselves. + `SessionSummary.annotations` surfaces the per-session `AnnotationsSummary` + for badge UI. +- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) + referencing annotations on a session's annotations channel by `resource` + URI, optionally narrowed to an `annotationIds` array. - `AnnotationsUpdatedAction` (`annotations/updated`) — partially updates an existing annotation's `turnId` / `resource` / `range` / `resolved` without resending its entries. Handled by `annotationsReducer` (no-op on unknown id). @@ -159,17 +175,6 @@ Implements AHP 0.3.0. `idle → running → error` lifecycle of a changeset operation. - `AgentCustomization._meta` provider metadata field. - Optional `changes` field on `SessionSummary` (`ChangesSummary` with optional `additions`, `deletions`, and `files` counts) summarising a session's file-change footprint. -- New annotations channel (`ahp-session://annotations`): `AnnotationsState`, - `Annotation`, `AnnotationEntry`, `AnnotationsSummary`, - the `annotationsReducer`, and the client-dispatchable `annotations/set`, - `annotations/removed`, `annotations/entrySet`, and `annotations/entryRemoved` - actions — clients drive every annotation mutation by dispatching these - directly, assigning the `Annotation.id` / `AnnotationEntry.id` themselves. - `SessionSummary.annotations` surfaces the per-session `AnnotationsSummary` - for badge UI. -- `MessageAnnotationsAttachment` (`annotations` `MessageAttachment` variant) - referencing annotations on a session's annotations channel by `resource` - URI, optionally narrowed to an `annotationIds` array. ### Changed diff --git a/types/version/registry.ts b/types/version/registry.ts index 473e317c..b6ebd689 100644 --- a/types/version/registry.ts +++ b/types/version/registry.ts @@ -131,11 +131,11 @@ export const ACTION_INTRODUCED_IN: { readonly [K in StateAction['type']]: string [ActionType.ChangesetOperationsChanged]: '0.2.0', [ActionType.ChangesetOperationStatusChanged]: '0.3.0', [ActionType.ChangesetCleared]: '0.2.0', - [ActionType.AnnotationsSet]: '0.3.0', + [ActionType.AnnotationsSet]: '0.4.0', [ActionType.AnnotationsUpdated]: '0.4.0', - [ActionType.AnnotationsRemoved]: '0.3.0', - [ActionType.AnnotationsEntrySet]: '0.3.0', - [ActionType.AnnotationsEntryRemoved]: '0.3.0', + [ActionType.AnnotationsRemoved]: '0.4.0', + [ActionType.AnnotationsEntrySet]: '0.4.0', + [ActionType.AnnotationsEntryRemoved]: '0.4.0', [ActionType.RootTerminalsChanged]: '0.1.0', [ActionType.RootConfigChanged]: '0.1.0', [ActionType.TerminalData]: '0.1.0',