Changeset Channel
Reference for the ahp-changeset:/<id> channel — server-owned views of file changes (uncommitted, session-wide, per-turn, etc.) that clients can subscribe to and invoke operations on. See the Changesets guide for an overview of the model.
JSON Schema: state.schema.json
State Types
ChangesetSummary
Catalogue entry describing one changeset the server can produce for a session.
Catalogue entries are intentionally lightweight — just enough to render a chip or list row without subscribing. Full per-changeset detail ({@link ChangesetState}) lives on the subscribable URI obtained by expanding {@link uriTemplate}.
| Field | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Human-readable label, e.g. "Uncommitted Changes". |
uriTemplate | string | Yes | RFC 6570 URI template. Clients parse the variables directly out of the template using the standard {name} syntax — they are not redeclared here.Only the following template shapes are defined by this protocol; any other variable name MUST be ignored by clients (there is no protocol-defined way to obtain values for unknown variables): | Variables in template | Meaning | | ------------------------------------------- | ------------------------------------------------------------------------------------ | | (none) | A static, session-wide changeset. The template is itself a subscribable URI. | | {turnId} | Per-turn slice. Expand with a Turn.id from the session. | | {originalTurnId} and {modifiedTurnId} | Diff between two turns. Both variables MUST be present. |Future protocol versions MAY add new well-known variables. |
description | string | No | Optional longer description. |
additions | number | No | Aggregate line additions across the changeset, when known. |
deletions | number | No | Aggregate line deletions across the changeset, when known. |
files | number | No | Number of files in the changeset, when known. |
ChangesetStatus
Computation lifecycle of a {@link ChangesetState}.
| Member | Value | Description |
|---|---|---|
Computing | 'computing' | The server is still computing the contents of this changeset. |
Ready | 'ready' | The changeset has been fully computed and is up-to-date. |
Error | 'error' | Computation failed. The cause is described by {@link ChangesetState.error}. |
ChangesetState
Full state for a single changeset, returned when a client subscribes to an expanded changeset URI.
The client already knows the URI it subscribed to, so this state does not redundantly carry it (or the catalogue's id, label, etc.). Aggregate counts (additions, deletions, files) are likewise omitted: clients trivially compute them from files[].edit.diff.
| Field | Type | Required | Description |
|---|---|---|---|
status | ChangesetStatus | Yes | Computation lifecycle. |
error | ErrorInfo | No | Present iff status === ChangesetStatus.Error. |
files | ChangesetFile[] | Yes | Files in this changeset, keyed by {@link ChangesetFile.id}. |
operations | ChangesetOperation[] | No | Operations the client may invoke against this changeset. Omit when no operations are available. |
ChangesetFile
One file entry within a {@link ChangesetState}.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable identifier within the changeset. Typically after.uri (or before.uri for deletions). |
edit | FileEdit | Yes | Reuses the existing {@link FileEdit} shape. Clients derive line additions, deletions, and rename/create/delete semantics from this. |
_meta | Record<string, unknown> | No | Server-defined opaque metadata, surfaced to operations and tooling but not interpreted by the protocol. |
ChangesetOperationScope
Where a {@link ChangesetOperation} can be invoked.
| Member | Value | Description |
|---|---|---|
Changeset | 'changeset' | Applies to the whole changeset. |
Resource | 'resource' | Applies to a single file within the changeset. |
Range | 'range' | Applies to a line range within a single file. |
ChangesetOperation
A server-declared invokable verb the client can run against a changeset, a file, or a range — "stage", "revert", "create-pr", and so on.
The term "operation" is used deliberately to avoid colliding with the protocol-level Actions that mutate state.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable identifier, unique within this changeset. |
label | string | Yes | Human-readable button/menu label. |
description | string | No | Optional longer description shown on hover or in tooltips. |
scopes | ChangesetOperationScope[] | Yes | Where this operation can be invoked. |
confirmation | StringOrMarkdown | No | Optional confirmation prompt to show before invoking. When present, the client MUST display this message to the user (typically in a confirmation dialog) and only invoke the operation after the user accepts. The presence of this field also signals that the operation is destructive — clients SHOULD style the affirmative button accordingly (e.g. with a warning colour). |
icon | string | No | Optional generic icon hint, e.g. "check", "trash". |
Actions
Mutate ChangesetState. Scoped to a changeset URI via the enclosing ActionEnvelope.channel.
JSON Schema: actions.schema.json
changeset/statusChanged
The {@link ChangesetState.status} for this changeset transitioned (e.g. computing → ready). The error payload is set together with status whenever it transitions to {@link ChangesetStatus.Error | Error}.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.ChangesetStatusChanged | Yes | |
status | ChangesetStatus | Yes | New computation lifecycle status. |
error | ErrorInfo | No | Cause when status === ChangesetStatus.Error; otherwise omitted. |
changeset/fileSet
Upsert a {@link ChangesetFile} in the changeset — adds a new entry, or replaces an existing one identified by {@link ChangesetFile.id}.
| Field | Type | Description |
|---|---|---|
type | ActionType.ChangesetFileSet | |
file | ChangesetFile | The new or replacement file entry. |
changeset/fileRemoved
Remove a {@link ChangesetFile} from the changeset by its id.
Typically dispatched when a file is reverted, staged out, or otherwise no longer in scope (e.g. a renamed file is replaced by a new entry).
| Field | Type | Description |
|---|---|---|
type | ActionType.ChangesetFileRemoved | |
fileId | string | The {@link ChangesetFile.id} of the file to remove. |
changeset/operationsChanged
The set of operations available on this changeset changed. Full replacement semantics: operations replaces the previous list (or removes it entirely when operations is undefined).
| Field | Type | Description |
|---|---|---|
type | ActionType.ChangesetOperationsChanged | |
operations | ChangesetOperation[] | undefined | Updated operation list. Pass undefined to clear all operations. |
changeset/cleared
Drop every file from the changeset.
Two cases use this:
- The underlying source moved (branch switched, fork point invalidated, …) and the server is recomputing from scratch — subsequent {@link ChangesetFileSetAction} entries will repopulate it.
- The owning session has ended and the URI is becoming un-subscribable — the server will unsubscribe all clients shortly after dispatching this action.
Clients SHOULD release any references on receipt and SHOULD NOT distinguish the two cases from the action alone — instead, react to the corresponding session-level lifecycle signal (e.g. root/sessionRemoved) for the "going away" case.
| Field | Type | Description |
|---|---|---|
type | ActionType.ChangesetCleared |
Commands
JSON Schema: commands.schema.json
invokeChangesetOperation
Invokes a server-defined {@link ChangesetOperation} against a changeset, a single file, or a line range.
The server validates that operationId exists in the changeset's current operations list and that the requested target.kind is contained in the operation's scopes. Invalid combinations result in a JSON-RPC error.
State changes resulting from invocation flow back through the normal changeset/* action stream on the relevant changeset URIs. Clients SHOULD NOT synthesise local optimistic changes for invocations unless the server explicitly opts in via a future capability.
| Property | Value |
|---|---|
| Direction | Client → Server |
| Type | Request |
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
channel | URI | Yes | The expanded changeset URI. |
operationId | string | Yes | Matches {@link ChangesetOperation.id} from the changeset's operations list. |
target | ChangesetOperationTarget | No | Target of the operation. Required iff the chosen scope is 'resource' or 'range'. Omit for changeset-scoped operations. |
Result:
| Field | Type | Required | Description |
|---|---|---|---|
message | StringOrMarkdown | No | Optional human-readable message describing the result. |
followUp | ChangesetOperationFollowUp | No | Optional follow-up: a URI to open (e.g. a PR), a content ref, etc. |