1
>
/*---------------------------------------------------------------------------------------------
state.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
// allow-any-unicode-comment-file
7
>
// DO NOT EDIT -- auto-generated by scripts/sync-agent-host-protocol.ts
8
>
9
>
import type { StringOrMarkdown, FileEdit, ErrorInfo } from '../common/state.js';
10
>
11
>
// ─── Changesets ──────────────────────────────────────────────────────────────
12
>
13
>
/**
14
>
* Catalogue entry describing one changeset the server can produce for a
15
>
* session.
16
>
*
17
>
* Catalogue entries are intentionally lightweight — just enough to render a
18
>
* chip or list row without subscribing. Full per-changeset detail
19
>
* ({@link ChangesetState}) lives on the subscribable URI obtained by
20
>
* expanding {@link uriTemplate}.
21
>
*
22
>
* @category Changesets
23
>
*/
24
>
export interface Changeset {
25
>
/** Human-readable label, e.g. `"Uncommitted Changes"`. */
26
>
label: string;
27
>
/**
28
>
* RFC 6570 URI template. Clients parse the variables directly out of the
29
>
* template using the standard `{name}` syntax — they are not redeclared
30
>
* here.
31
>
*
32
>
* Only the following template shapes are defined by this protocol; any
33
>
* other variable name MUST be ignored by clients (there is no
34
>
* protocol-defined way to obtain values for unknown variables):
35
>
*
36
>
* | Variables in template | Meaning |
37
>
* | ------------------------------------------- | ------------------------------------------------------------------------------------ |
38
>
* | _(none)_ | A static, session-wide changeset. The template is itself a subscribable URI. |
39
>
* | `{turnId}` | Per-turn slice. Expand with a `Turn.id` from the session. |
40
>
* | `{originalTurnId}` and `{modifiedTurnId}` | Diff between two turns. Both variables MUST be present. |
41
>
*
42
>
* Future protocol versions MAY add new well-known variables.
43
>
*/
44
>
uriTemplate: string;
45
>
/** Optional longer description. */
46
>
description?: string;
47
>
/**
48
>
* Advisory hint describing what kind of changeset this is, so clients can
49
>
* group, sort, or render an appropriate icon without parsing
50
>
* {@link uriTemplate}. Recognized values include:
51
>
*
52
>
* - `'session'`: a static, session-wide changeset covering all changes the
53
>
* agent has produced in this session.
54
>
* - `'branch'`: changes relative to a base branch (e.g. a feature branch
55
>
* diffed against `main`).
56
>
* - `'uncommitted'`: the workspace's current uncommitted changes.
57
>
* - `'turn'`: changes produced by a single turn. Typically paired with a
58
>
* `{turnId}` variable in {@link uriTemplate}.
59
>
* - `'compare-turns'`: a diff between two turns. Typically paired with
60
>
* `{originalTurnId}` and `{modifiedTurnId}` variables in
61
>
* {@link uriTemplate}.
62
>
*
63
>
* Implementations MAY provide additional values; clients SHOULD fall back
64
>
* to a reasonable default when an unknown value is encountered.
65
>
*/
66
>
changeKind: string;
67
>
/**
68
>
* Optional capability declarations for this changeset. Absent (or an empty
69
>
* object) means the changeset advertises no optional capabilities.
70
>
*
71
>
* Because the catalogue entry is delivered up-front on
72
>
* {@link ChangesetState | the session's changeset list}, clients can decide
73
>
* whether to surface capability-gated UI (such as review checkboxes) without
74
>
* first subscribing to the changeset URI. Mirrors the presence-flag
75
>
* convention of `ClientCapabilities`.
76
>
*/
77
>
capabilities?: ChangesetCapabilities;
78
>
}
79
>
80
>
/**
81
>
* Optional capabilities a changeset advertises on its catalogue
82
>
* {@link Changeset} entry.
83
>
*
84
>
* Each field is a presence flag: an empty object `{}` means "supported",
85
>
* absence means "not supported". Sub-fields on individual capabilities are
86
>
* reserved for future per-capability options.
87
>
*
88
>
* @category Changesets
89
>
*/
90
>
export interface ChangesetCapabilities {
91
>
/**
92
>
* The changeset supports the per-file **review** workflow. When declared,
93
>
* clients MAY surface a GitHub-style "Viewed" toggle per file and dispatch
94
>
* {@link ChangesetFilesReviewChangedAction | `changeset/filesReviewChanged`} to
95
>
* set each file's {@link ChangesetFile.reviewed} flag. Clients that omit
96
>
* handling MUST treat the changeset as non-reviewable.
97
>
*/
98
>
review?: Record<string, never>;
99
>
}
100
>
101
>
/**
102
>
* Computation lifecycle of a {@link ChangesetState}.
103
>
*
104
>
* @category Changesets
105
>
*/
106
>
export const enum ChangesetStatus {
107
>
/** The server is still computing the contents of this changeset. */
108
>
Computing = 'computing',
109
>
/** The changeset has been fully computed and is up-to-date. */
110
>
Ready = 'ready',
111
>
/**
112
>
* Computation failed. The cause is described by
113
>
* {@link ChangesetState.error}.
114
>
*/
115
>
Error = 'error',
116
>
}
117
>
118
>
/**
119
>
* Full state for a single changeset, returned when a client subscribes to
120
>
* an expanded changeset URI.
121
>
*
122
>
* The client already knows the URI it subscribed to, so this state does
123
>
* not redundantly carry it (or the catalogue's `id`, `label`, etc.).
124
>
* Aggregate counts (`additions`, `deletions`, `files`) are likewise
125
>
* omitted: clients trivially compute them from `files[].edit.diff`.
126
>
*
127
>
* @category Changesets
128
>
*/
129
>
export interface ChangesetState {
130
>
/** Computation lifecycle. */
131
>
status: ChangesetStatus;
132
>
/** Present iff `status === ChangesetStatus.Error`. */
133
>
error?: ErrorInfo;
134
>
/** Files in this changeset, keyed by {@link ChangesetFile.id}. */
135
>
files: ChangesetFile[];
136
>
/**
137
>
* Operations the client may invoke against this changeset. Omit when no
138
>
* operations are available.
139
>
*/
140
>
operations?: ChangesetOperation[];
141
>
}
142
>
143
>
/**
144
>
* One file entry within a {@link ChangesetState}.
145
>
*
146
>
* @category Changesets
147
>
*/
148
>
export interface ChangesetFile {
149
>
/**
150
>
* Stable identifier within the changeset. Typically `after.uri`
151
>
* (or `before.uri` for deletions).
152
>
*/
153
>
id: string;
154
>
/**
155
>
* Reuses the existing {@link FileEdit} shape. Clients derive line
156
>
* additions, deletions, and rename/create/delete semantics from this.
157
>
*/
158
>
edit: FileEdit;
159
>
/**
160
>
* Whether a reviewer has marked this file as reviewed (the GitHub-style
161
>
* "Viewed" checkbox). Absent is equivalent to `false` — clients MUST treat
162
>
* a missing value as not-yet-reviewed.
163
>
*
164
>
* Requires the changeset to advertise {@link ChangesetCapabilities.review}.
165
>
* Clients toggle it by dispatching
166
>
* {@link ChangesetFilesReviewChangedAction | `changeset/filesReviewChanged`};
167
>
* the server MAY also originate it (e.g. an agent self-reviewing its own
168
>
* output).
169
>
*
170
>
* There is no content version in the protocol, so review is **not** reset
171
>
* automatically when a file's contents change under a stable id. The server,
172
>
* which is the authority on what changed, resets review explicitly — either
173
>
* by re-emitting the file (via {@link ChangesetFileSetAction} or
174
>
* {@link ChangesetContentChangedAction}) without `reviewed: true`, or by
175
>
* dispatching `changeset/filesReviewChanged` with `reviewed: false`.
176
>
*/
177
>
reviewed?: boolean;
178
>
/**
179
>
* Server-defined opaque metadata, surfaced to operations and tooling
180
>
* but not interpreted by the protocol.
181
>
*/
182
>
_meta?: Record<string, unknown>;
183
>
}
184
>
185
>
/**
186
>
* Execution lifecycle of a {@link ChangesetOperation}.
187
>
*
188
>
* An operation is invoked imperatively via `invokeChangesetOperation`, but
189
>
* its progress and outcome are reflected back into changeset state so that
190
>
* every subscriber observes a consistent view (e.g. a spinner on a "Create
191
>
* Pull Request" button, or an inline error after a failed "revert").
192
>
*
193
>
* @category Changesets
194
>
*/
195
>
export const enum ChangesetOperationStatus {
196
>
/**
197
>
* The operation is ready to be invoked. This is the default when
198
>
* {@link ChangesetOperation.status} is omitted.
199
>
*/
200
>
Idle = 'idle',
201
>
/** An invocation of this operation is currently in flight. */
202
>
Running = 'running',
203
>
/**
204
>
* The most recent invocation failed. The cause is described by
205
>
* {@link ChangesetOperation.error}.
206
>
*/
207
>
Error = 'error',
208
>
/**
209
>
* The operation is currently disabled and cannot be invoked.
210
>
*/
211
>
Disabled = 'disabled',
212
>
}
213
>
214
>
/**
215
>
* Where a {@link ChangesetOperation} can be invoked.
216
>
*
217
>
* @category Changesets
218
>
*/
219
>
export const enum ChangesetOperationScope {
220
>
/** Applies to the whole changeset. */
221
>
Changeset = 'changeset',
222
>
/** Applies to a single file within the changeset. */
223
>
Resource = 'resource',
224
>
/** Applies to a line range within a single file. */
225
>
Range = 'range',
226
>
}
227
>
228
>
/**
229
>
* A server-declared invokable verb the client can run against a
230
>
* changeset, a file, or a range — `"stage"`, `"revert"`, `"create-pr"`,
231
>
* and so on.
232
>
*
233
>
* The term "operation" is used deliberately to avoid colliding with the
234
>
* protocol-level [Actions](/guide/actions) that mutate state.
235
>
*
236
>
* @category Changesets
237
>
*/
238
>
export interface ChangesetOperation {
239
>
/** Stable identifier, unique within this changeset. */
240
>
id: string;
241
>
/** Human-readable button/menu label. */
242
>
label: string;
243
>
/** Optional longer description shown on hover or in tooltips. */
244
>
description?: string;
245
>
/** Where this operation can be invoked. */
246
>
scopes: ChangesetOperationScope[];
247
>
/**
248
>
* Optional confirmation prompt to show before invoking. When present,
249
>
* the client MUST display this message to the user (typically in a
250
>
* confirmation dialog) and only invoke the operation after the user
251
>
* accepts. The presence of this field also signals that the operation
252
>
* is destructive — clients SHOULD style the affirmative button
253
>
* accordingly (e.g. with a warning colour).
254
>
*/
255
>
confirmation?: StringOrMarkdown;
256
>
/** Optional generic icon hint, e.g. `"check"`, `"trash"`. */
257
>
icon?: string;
258
>
/** Optional group identifier, used to group related operations together. */
259
>
group?: string;
260
>
/**
261
>
* Current execution status. The server sets
262
>
* {@link ChangesetOperationStatus.Running | Running} while an invocation
263
>
* is in flight, {@link ChangesetOperationStatus.Error | Error} when the
264
>
* most recent invocation failed, and
265
>
* {@link ChangesetOperationStatus.Idle | Idle} otherwise.
266
>
*
267
>
* Clients SHOULD reflect this state in the UI — e.g. disabling the
268
>
* control or showing a spinner while `Running`, and surfacing
269
>
* {@link error} while `Error`.
270
>
*/
271
>
status: ChangesetOperationStatus;
272
>
/**
273
>
* Cause of failure. Present iff
274
>
* `status === ChangesetOperationStatus.Error`; otherwise omitted.
275
>
*/
276
>
error?: ErrorInfo;
277
>
}