AGENTS.md

1# Protocol versioning instructions
2 
3This directory contains the VS Code-facing wrappers around the Agent Host
4Protocol (AHP) state model. Read this before modifying protocol types.
5 
6## Overview
7 
8- `sessionState.ts`, `sessionActions.ts`, `sessionReducers.ts`, and
9  `sessionProtocol.ts` are VS Code-facing wrappers and re-exports.
10- `protocol/**` is generated from the sibling `agent-host-protocol` repo by
11  `scripts/sync-agent-host-protocol.ts`. Generated files carry a `DO NOT EDIT`
12  banner; update the source protocol repo and sync the copy into VS Code.
13- `protocol/version/registry.ts` contains `PROTOCOL_VERSION`,
14  `ACTION_INTRODUCED_IN`, `NOTIFICATION_INTRODUCED_IN`, and version helper
15  functions. There is no `versions/` directory in this tree.
16 
17## Current changeset surface
18 
19The generated protocol includes the Changesets model:
20 
21- `SessionSummary.changesets` is the lightweight catalogue shown in lists.
22- The old `session/diffsChanged` shape is replaced by five `changeset/*`
23  actions: `statusChanged`, `fileSet`, `fileRemoved`, `operationsChanged`, and
24  `cleared`.
25- `invokeChangesetOperation` lets clients invoke server-defined verbs against a
26  changeset. The wire command and dispatch path exist even when no concrete
27  operations are advertised yet.
28- Changeset actions are scoped to an expanded changeset URI
29  (`<sessionUri>/changeset/<id>`); see `../changesetUri.ts` for the build/parse
30  helpers.
31- Session teardown uses `changeset/cleared` plus the corresponding
32  session-level lifecycle notification. There is no separate `changeset/disposed`
33  action in the VS Code protocol copy.
34 
35## Updating generated protocol types
36 
371. Update the source files in the sibling `agent-host-protocol` repo.
382. Run `npx tsx scripts/sync-agent-host-protocol.ts` from the VS Code repo.
393. If VS Code consumers need short aliases or type guards, update the wrapper
40   files in this directory after the sync.
414. Compile. The generated registry catches missing action/notification version
42   map entries.
43 
44## Adding optional fields to existing types
45 
46Optional protocol fields are usually backwards-compatible. Add the field in the
47source protocol repo, sync `protocol/**`, and add wrapper exports only when VS
48Code code needs them.
49 
50## Adding new action types
51 
52Adding a new server-produced action type is backwards-compatible when old clients
53can ignore it safely. Old clients at the same protocol version ignore unknown
54action types by leaving reducer state unchanged.
55 
561. Add the action interface and union membership in the source protocol repo.
572. Add the action to `ACTION_INTRODUCED_IN` in
58   `protocol/version/registry.ts` through the generated sync.
593. Add the reducer case in the source protocol repo and sync it into
60   `protocol/reducers.ts`.
614. Re-export the new action from `sessionActions.ts` when VS Code callers need
62   the type directly.
635. Update `../../../protocol.md` and any affected AHP docs.
64 
65## When to bump the protocol version
66 
67Bump `PROTOCOL_VERSION` in `protocol/version/registry.ts` when you need a
68capability boundary; for example, when a client must know whether the server
69supports a feature before sending a command or rendering UI.
70 
71When bumping:
72 
731. Update the source protocol repo's version registry and sync it into
74   `protocol/version/registry.ts`.
752. Assign new action and notification types to the new version in
76   `ACTION_INTRODUCED_IN` or `NOTIFICATION_INTRODUCED_IN`.
773. Update capability types when the feature needs client-visible capability
78   negotiation.
794. Update `../../../protocol.md` version history and affected AHP docs.
80 
81## Adding new notification types
82 
83Use the same process as new action types, but register the new notification in
84`NOTIFICATION_INTRODUCED_IN`.
85 
86## What the compiler catches
87 
88| Mistake                                                               | Compile error                   |
89| --------------------------------------------------------------------- | ------------------------------- |
90| Add action to union, forget `ACTION_INTRODUCED_IN` entry              | Mapped type index is incomplete |
91| Add notification to union, forget `NOTIFICATION_INTRODUCED_IN` entry  | Mapped type index is incomplete |
92| Remove action or notification type that the registry still references | Registry key no longer exists   |
93