Skip to content

Commit a680425

Browse files
committed
feat: negotiate a client-neutral agent file-change report
1 parent d1c5326 commit a680425

9 files changed

Lines changed: 588 additions & 25 deletions

‎docs/air-extensions.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -864,6 +864,7 @@ It returns `{ "stopped": true }` after app-server accepts the termination.
864864

865865
Standard ACP describes a change from one tool call. It has no complete file list for one prompt turn.
866866
The version 1 `agentFileChangeReport` extension adds that list.
867+
A client that is not AIR can opt in without the AIR namespace, see [Client-neutral agent file-change report](#client-neutral-agent-file-change-report).
867868

868869
### Request
869870

@@ -937,6 +938,57 @@ The client must match the request id.
937938
It must ignore a duplicate, stale, malformed, or unavailable report.
938939
Rollback is outside this extension. The adapter advertises no `undo` or `rollback` command.
939940

941+
### Client-neutral agent file-change report
942+
943+
A client that is not AIR can get the same report without the `_meta.jetbrains.air` namespace.
944+
It opts in with `initialize.clientCapabilities._meta`:
945+
946+
```json
947+
{ "agentFileChangeReport": { "version": 1 } }
948+
```
949+
950+
- Accepted only when `agentFileChangeReport` is an object whose `version` is an integer of at least 1. Anything else
951+
enables nothing.
952+
- The opt-in is an ACP v1 extension. The `initialize` answer of an opted-in client has the top-level
953+
`_meta.agentFileChangeReport: {"version": 1}`.
954+
- ACP v2 ignores the opt-in.
955+
956+
The client asks for a report with the top-level `_meta` of `session/prompt`:
957+
958+
```json
959+
{ "_meta": { "agentFileChangeReportRequest": { "version": 1, "requestId": "a-unique-request-id" } } }
960+
```
961+
962+
The [request](#request) rules apply: a malformed request is ignored.
963+
The adapter retains the turn diffs of a prompt only when it has a valid request.
964+
965+
The report goes in the top-level `_meta.agentFileChangeReport` of the `session_info_update`:
966+
967+
```json
968+
{
969+
"sessionUpdate": "session_info_update",
970+
"_meta": {
971+
"agentFileChangeReport": {
972+
"version": 1,
973+
"requestId": "a-unique-request-id",
974+
"status": "reported",
975+
"paths": ["/workspace/src/App.ts"],
976+
"declaredComplete": false,
977+
"truncated": false,
978+
"uncertainty": "Codex turn diffs may omit same-content renames and changes made outside apply_patch, including shell commands, version-control commands, generators, and child processes."
979+
}
980+
}
981+
}
982+
```
983+
984+
The report object, its limits, its timing, the [Codex source](#codex-source) and the [unavailable reasons](#unavailable-report) are those of the AIR form.
985+
986+
- A client that declares both the AIR `agentFileChangeReport` capability and the client-neutral opt-in gets only the
987+
client-neutral form: the adapter reads only the top-level request and ignores one in the AIR namespace.
988+
Its AIR capability list still names `agentFileChangeReport`.
989+
- AIR clients that do not send the client-neutral opt-in use the AIR form, unchanged. They get no report for a
990+
top-level request.
991+
940992
## Session failure
941993

942994
The `sessionFailure` extension sends warnings and errors as durable transcript entries.

‎src/AgentFileChangeReport.ts‎

Lines changed: 76 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
import fs from "node:fs";
22
import path from "node:path";
33
import {parsePatch} from "diff";
4+
import type * as acp from "@agentclientprotocol/sdk/unstable";
45
import {
6+
AIR_AGENT_FILE_CHANGE_REPORT_KEY,
57
AIR_AGENT_FILE_CHANGE_REPORT_REQUEST_KEY,
8+
AIR_EXTENSION_VERSION,
9+
AIR_EXTENSION_VERSION_KEY,
610
AIR_META_KEY,
711
JETBRAINS_META_KEY,
812
} from "./AirExtension";
@@ -14,6 +18,17 @@ export const AGENT_FILE_CHANGE_REPORT_MAX_TOTAL_BYTES = 256 * 1_024;
1418
export const AGENT_FILE_CHANGE_REPORT_MAX_UNCERTAINTY_LENGTH = 2_000;
1519
export const AGENT_FILE_CHANGE_REPORT_MAX_DIFF_BYTES = 8 * 1_024 * 1_024;
1620

21+
/** The top-level `_meta` key of the client-neutral opt-in, advert and report. */
22+
export const NEUTRAL_AGENT_FILE_CHANGE_REPORT_META_KEY = "agentFileChangeReport";
23+
/** The top-level `session/prompt._meta` key of the client-neutral report request. */
24+
export const NEUTRAL_AGENT_FILE_CHANGE_REPORT_REQUEST_META_KEY = "agentFileChangeReportRequest";
25+
26+
/**
27+
* How a client asks for and gets the report: not at all, in the AIR namespace, or in the client-neutral top-level
28+
* `_meta`. Both forms use the same request validation, builders, limits and timing.
29+
*/
30+
export type AgentFileChangeReportFormat = "none" | "air" | "neutral";
31+
1732
const TURN_DIFF_UNCERTAINTY = "Codex turn diffs may omit same-content renames and changes made outside apply_patch, including shell commands, version-control commands, generators, and child processes.";
1833

1934
export interface AgentFileChangeReportRequest {
@@ -72,12 +87,72 @@ export function captureAgentFileChangeWorkspace(
7287
};
7388
}
7489

90+
/** The `initialize` answer `_meta.agentFileChangeReport` for a client that opted into the client-neutral form. */
91+
export function neutralAgentFileChangeReportCapability(): {version: number} {
92+
return {version: AGENT_FILE_CHANGE_REPORT_VERSION};
93+
}
94+
95+
/**
96+
* Whether the client opted into the client-neutral report with
97+
* `clientCapabilities._meta.agentFileChangeReport: {version}`, an integer of at least 1.
98+
*/
99+
export function clientRequestsNeutralAgentFileChangeReport(
100+
capabilities: acp.ClientCapabilities | null | undefined,
101+
): boolean {
102+
const declared = asRecord(capabilities?._meta?.[NEUTRAL_AGENT_FILE_CHANGE_REPORT_META_KEY]);
103+
const version = declared?.["version"];
104+
return typeof version === "number" && Number.isInteger(version) && version >= 1;
105+
}
106+
75107
export function parseAgentFileChangeReportRequest(
76108
meta: Record<string, unknown> | null | undefined,
77109
): AgentFileChangeReportRequest | null {
78110
const jetbrains = asRecord(meta?.[JETBRAINS_META_KEY]);
79111
const air = asRecord(jetbrains?.[AIR_META_KEY]);
80-
const request = asRecord(air?.[AIR_AGENT_FILE_CHANGE_REPORT_REQUEST_KEY]);
112+
return validateAgentFileChangeReportRequest(air?.[AIR_AGENT_FILE_CHANGE_REPORT_REQUEST_KEY]);
113+
}
114+
115+
export function parseNeutralAgentFileChangeReportRequest(
116+
meta: Record<string, unknown> | null | undefined,
117+
): AgentFileChangeReportRequest | null {
118+
return validateAgentFileChangeReportRequest(meta?.[NEUTRAL_AGENT_FILE_CHANGE_REPORT_REQUEST_META_KEY]);
119+
}
120+
121+
/** The prompt's report request in the negotiated form. A request in the other form is ignored. */
122+
export function agentFileChangeReportRequestFor(
123+
format: AgentFileChangeReportFormat,
124+
meta: Record<string, unknown> | null | undefined,
125+
): AgentFileChangeReportRequest | null {
126+
switch (format) {
127+
case "none":
128+
return null;
129+
case "air":
130+
return parseAgentFileChangeReportRequest(meta);
131+
case "neutral":
132+
return parseNeutralAgentFileChangeReportRequest(meta);
133+
}
134+
}
135+
136+
/** The `session_info_update._meta` that carries the report in the negotiated form. */
137+
export function agentFileChangeReportMeta(
138+
format: Exclude<AgentFileChangeReportFormat, "none">,
139+
report: AgentFileChangeReport,
140+
): Record<string, unknown> {
141+
if (format === "neutral") {
142+
return {[NEUTRAL_AGENT_FILE_CHANGE_REPORT_META_KEY]: report};
143+
}
144+
return {
145+
[JETBRAINS_META_KEY]: {
146+
[AIR_META_KEY]: {
147+
[AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
148+
[AIR_AGENT_FILE_CHANGE_REPORT_KEY]: report,
149+
},
150+
},
151+
};
152+
}
153+
154+
function validateAgentFileChangeReportRequest(value: unknown): AgentFileChangeReportRequest | null {
155+
const request = asRecord(value);
81156
if (request === null
82157
|| !hasOnlyKeys(request, ["version", "requestId"])
83158
|| request["version"] !== AGENT_FILE_CHANGE_REPORT_VERSION) {

‎src/CodexAcpServer.ts‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -242,14 +242,18 @@ import {clientSupportsCompaction, CodexSessionCompactions, createCompactionUpdat
242242
import {CodexSessionToolCalls} from "./CodexSessionToolCalls";
243243
import {
244244
type AgentFileChangeReport,
245+
type AgentFileChangeReportFormat,
245246
type AgentFileChangeReportRequest,
246247
type AgentFileChangeReportUnavailableReason,
247248
type AgentFileChangeWorkspace,
248249
AgentFileChangeReportError,
250+
agentFileChangeReportMeta,
251+
agentFileChangeReportRequestFor,
252+
NEUTRAL_AGENT_FILE_CHANGE_REPORT_META_KEY,
253+
neutralAgentFileChangeReportCapability,
249254
captureAgentFileChangeWorkspace,
250255
createReportedAgentFileChangeReport,
251256
createUnavailableAgentFileChangeReport,
252-
parseAgentFileChangeReportRequest,
253257
} from "./AgentFileChangeReport";
254258

255259

@@ -425,10 +429,6 @@ const DENY_ALL_ELICITATIONS: ElicitationHandler = {
425429
handleUserInput: async () => ({answers: {}}),
426430
};
427431

428-
function clientSupportsAgentFileChangeReports(capabilities: acp.ClientCapabilities | null): boolean {
429-
return clientSupportsAirCapability(capabilities, AIR_AGENT_FILE_CHANGE_REPORT_KEY);
430-
}
431-
432432
interface ActiveAuthState {
433433
account: Account | null;
434434
authConfigured: boolean;
@@ -974,6 +974,11 @@ export class CodexAcpServer {
974974
...(protocolVersion === 1 && this.capabilities.sessionFailureFormat === "neutral" ? {
975975
[NEUTRAL_SESSION_FAILURE_META_KEY]: neutralSessionFailureCapability(),
976976
} : {}),
977+
// The client-neutral agent file-change report, see `docs/air-extensions.md`. It is an ACP v1 extension,
978+
// so `ClientCapabilities.fromV2` never selects it.
979+
...(protocolVersion === 1 && this.capabilities.agentFileChangeReportFormat === "neutral" ? {
980+
[NEUTRAL_AGENT_FILE_CHANGE_REPORT_META_KEY]: neutralAgentFileChangeReportCapability(),
981+
} : {}),
977982
// The session index for a client that opted in without AIR, see `docs/air-extensions.md`.
978983
...(neutralSessionIndex ? {
979984
[NEUTRAL_SESSION_INDEX_META_KEY]: neutralSessionIndex,
@@ -4120,6 +4125,7 @@ export class CodexAcpServer {
41204125

41214126
private async publishAgentFileChangeReport(
41224127
sessionState: SessionState,
4128+
format: Exclude<AgentFileChangeReportFormat, "none">,
41234129
turnId: string | null,
41244130
request: AgentFileChangeReportRequest,
41254131
unavailableReason: AgentFileChangeReportUnavailableReason,
@@ -4147,14 +4153,7 @@ export class CodexAcpServer {
41474153
const session = new ACPSessionConnection(this.connection, sessionState.sessionId);
41484154
await session.update({
41494155
sessionUpdate: "session_info_update",
4150-
_meta: {
4151-
[JETBRAINS_META_KEY]: {
4152-
[AIR_META_KEY]: {
4153-
[AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
4154-
[AIR_AGENT_FILE_CHANGE_REPORT_KEY]: report,
4155-
},
4156-
},
4157-
},
4156+
_meta: agentFileChangeReportMeta(format, report),
41584157
});
41594158
} catch (error) {
41604159
logger.error("Failed to publish agent file-change report", error);
@@ -4969,9 +4968,8 @@ export class CodexAcpServer {
49694968
// Awaited only when a clear is sent, so a prompt with no held suggestion starts in the same tick.
49704969
const clearing = sessionState.promptSuggestions?.clear();
49714970
if (clearing) await clearing;
4972-
const agentFileChangeReportRequest = clientSupportsAgentFileChangeReports(this.clientCapabilities)
4973-
? parseAgentFileChangeReportRequest(params._meta)
4974-
: null;
4971+
const agentFileChangeReportFormat = this.capabilities.agentFileChangeReportFormat;
4972+
const agentFileChangeReportRequest = agentFileChangeReportRequestFor(agentFileChangeReportFormat, params._meta);
49754973
const agentFileChangeWorkspace = agentFileChangeReportRequest === null
49764974
? null
49774975
: captureAgentFileChangeWorkspace(sessionState.cwd, sessionState.additionalDirectories);
@@ -5588,7 +5586,9 @@ export class CodexAcpServer {
55885586
} catch (error) {
55895587
logger.error("Failed to publish terminal compaction or subagent state during prompt cleanup", error);
55905588
}
5591-
if (agentFileChangeReportRequest !== null && agentFileChangeWorkspace !== null) {
5589+
if (agentFileChangeReportFormat !== "none"
5590+
&& agentFileChangeReportRequest !== null
5591+
&& agentFileChangeWorkspace !== null) {
55925592
if (promptWasCancelled || activePrompt.signal.aborted || this.sessionIsClosing(params.sessionId)) {
55935593
agentFileChangeReportTurnId = null;
55945594
agentFileChangeReportUnavailableReason = "cancelled";
@@ -5599,6 +5599,7 @@ export class CodexAcpServer {
55995599
}
56005600
await this.publishAgentFileChangeReport(
56015601
sessionState,
5602+
agentFileChangeReportFormat,
56025603
agentFileChangeReportTurnId,
56035604
agentFileChangeReportRequest,
56045605
agentFileChangeReportUnavailableReason,

‎src/__tests__/AgentFileChangeReport.test.ts‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,14 @@ import {
77
AGENT_FILE_CHANGE_REPORT_MAX_PATH_LENGTH,
88
AGENT_FILE_CHANGE_REPORT_MAX_TOTAL_BYTES,
99
AgentFileChangeReportError,
10+
agentFileChangeReportMeta,
11+
agentFileChangeReportRequestFor,
1012
captureAgentFileChangeWorkspace,
13+
clientRequestsNeutralAgentFileChangeReport,
1114
createReportedAgentFileChangeReport,
15+
createUnavailableAgentFileChangeReport,
1216
parseAgentFileChangeReportRequest,
17+
parseNeutralAgentFileChangeReportRequest,
1318
} from "../AgentFileChangeReport";
1419

1520
function modified(pathname: string): string {
@@ -56,6 +61,71 @@ describe("agent file-change report", () => {
5661
}
5762
});
5863

64+
it("accepts a client-neutral request by the rules of the AIR request", () => {
65+
expect(parseNeutralAgentFileChangeReportRequest({
66+
agentFileChangeReportRequest: {version: 1, requestId: "alas-turn:0123.abc_DEF-9"},
67+
})).toEqual({version: 1, requestId: "alas-turn:0123.abc_DEF-9"});
68+
expect(parseNeutralAgentFileChangeReportRequest({
69+
agentFileChangeReportRequest: {version: 1, requestId: "x".repeat(128)},
70+
})).toEqual({version: 1, requestId: "x".repeat(128)});
71+
});
72+
73+
it.each([
74+
{name: "an unknown version", request: {version: 2, requestId: "request-id"}},
75+
{name: "a string version", request: {version: "1", requestId: "request-id"}},
76+
{name: "no version", request: {requestId: "request-id"}},
77+
{name: "no request id", request: {version: 1}},
78+
{name: "an empty request id", request: {version: 1, requestId: ""}},
79+
{name: "a numeric request id", request: {version: 1, requestId: 42}},
80+
{name: "a request id with spaces", request: {version: 1, requestId: "contains spaces"}},
81+
{name: "a request id with a slash", request: {version: 1, requestId: "session/prompt"}},
82+
{name: "an oversized request id", request: {version: 1, requestId: "x".repeat(129)}},
83+
{name: "an extra key", request: {version: 1, requestId: "request-id", extra: true}},
84+
{name: "literal true", request: true},
85+
{name: "an array", request: [{version: 1, requestId: "request-id"}]},
86+
{name: "null", request: null},
87+
])("ignores a client-neutral request with $name", ({request}) => {
88+
expect(parseNeutralAgentFileChangeReportRequest({agentFileChangeReportRequest: request})).toBeNull();
89+
});
90+
91+
it("reads a request only in the negotiated form", () => {
92+
const request = {version: 1, requestId: "request-id"};
93+
const neutral = {agentFileChangeReportRequest: request};
94+
const air = {jetbrains: {air: {agentFileChangeReportRequest: request}}};
95+
96+
expect(agentFileChangeReportRequestFor("neutral", neutral)).toEqual(request);
97+
expect(agentFileChangeReportRequestFor("neutral", air)).toBeNull();
98+
expect(agentFileChangeReportRequestFor("air", air)).toEqual(request);
99+
expect(agentFileChangeReportRequestFor("air", neutral)).toBeNull();
100+
expect(agentFileChangeReportRequestFor("none", {...neutral, ...air})).toBeNull();
101+
expect(agentFileChangeReportRequestFor("neutral", undefined)).toBeNull();
102+
});
103+
104+
it.each([
105+
{name: "version 1", declared: {version: 1}, expected: true},
106+
{name: "a later version", declared: {version: 2}, expected: true},
107+
{name: "version 0", declared: {version: 0}, expected: false},
108+
{name: "a fractional version", declared: {version: 1.5}, expected: false},
109+
{name: "a string version", declared: {version: "1"}, expected: false},
110+
{name: "no version", declared: {}, expected: false},
111+
{name: "literal true", declared: true, expected: false},
112+
{name: "an array", declared: [{version: 1}], expected: false},
113+
{name: "null", declared: null, expected: false},
114+
])("reads the client-neutral opt-in with $name as $expected", ({declared, expected}) => {
115+
expect(clientRequestsNeutralAgentFileChangeReport({_meta: {agentFileChangeReport: declared}})).toBe(expected);
116+
});
117+
118+
it("carries the same report object in each form", () => {
119+
const report = createUnavailableAgentFileChangeReport("request-id", "cancelled");
120+
121+
expect(JSON.stringify(agentFileChangeReportMeta("neutral", report))).toBe(
122+
'{"agentFileChangeReport":{"version":1,"requestId":"request-id","status":"unavailable","reason":"cancelled"}}',
123+
);
124+
expect(JSON.stringify(agentFileChangeReportMeta("air", report))).toBe(
125+
'{"jetbrains":{"air":{"version":1,"agentFileChangeReport":{"version":1,"requestId":"request-id","status":"unavailable","reason":"cancelled"}}}}',
126+
);
127+
});
128+
59129
it("extracts add, update, delete, rename, and binary paths from an aggregated diff", () => {
60130
const diff = [
61131
modified("src/Main.kt"),

0 commit comments

Comments
 (0)