Skip to content

Commit 9181cce

Browse files
committed
feat: add a client-neutral recommended config value
A client opts in at initialize with clientCapabilities._meta.recommendedConfigValue { version: 1 }, under ACP v1 only. The model and reasoning effort selectors then carry _meta.recommendedConfigValue { version, value }: the isDefault model and the defaultReasoningEffort of the current model, sent only when the selector offers the value and computed again on a model switch. The record never changes the current value. The AIR form is unchanged, and a client that declares both gets both.
1 parent 4b88aaf commit 9181cce

8 files changed

Lines changed: 86 additions & 9 deletions

File tree

‎docs/air-extensions.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -852,6 +852,12 @@ When the client declares `recommendedValue`, a selector with a recommendation ca
852852

853853
Without the capability, the config options keep their old shape and carry no recommendation.
854854

855+
### Client-neutral form
856+
857+
A client that isn't AIR can opt in with `clientCapabilities._meta.recommendedConfigValue: { "version": 1 }`, an object whose `version` is an integer of at least 1, and gets `_meta.recommendedConfigValue: { "version": 1 }` back from `initialize`. ACP v2 ignores the opt-in.
858+
859+
A selector with a recommendation then carries `_meta.recommendedConfigValue: { "version": 1, "value": "medium" }`, under the same rules as above. A client that declares AIR too gets both records.
860+
855861
## Async tasks
856862

857863
Codex app-server owns shell commands that keep running after their tool call.

‎src/CodexAcpServer.ts‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,7 @@ import {
258258
import {
259259
NEUTRAL_PERMISSION_PRESENTATION_META_KEY,
260260
NEUTRAL_QUESTION_CUSTOM_ANSWER_META_KEY,
261+
NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY,
261262
neutralPresentationCapability,
262263
} from "./permissions/metadata";
263264

@@ -992,6 +993,9 @@ export class CodexAcpServer {
992993
...(this.capabilities.neutralQuestionCustomAnswer ? {
993994
[NEUTRAL_QUESTION_CUSTOM_ANSWER_META_KEY]: neutralPresentationCapability(),
994995
} : {}),
996+
...(this.capabilities.neutralRecommendedConfigValue ? {
997+
[NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY]: neutralPresentationCapability(),
998+
} : {}),
995999
// The session index for a client that opted in without AIR, see `docs/air-extensions.md`.
9961000
...(neutralSessionIndex ? {
9971001
[NEUTRAL_SESSION_INDEX_META_KEY]: neutralSessionIndex,
@@ -3389,10 +3393,11 @@ export class CodexAcpServer {
33893393

33903394
private createSessionConfigOptions(sessionState: SessionState): Array<acp.SessionConfigOption> {
33913395
const currentModelId = ModelId.fromString(sessionState.currentModelId);
3392-
const useRecommendedValue = clientSupportsAirCapability(
3393-
this.clientCapabilities,
3394-
AIR_RECOMMENDED_CONFIG_VALUE_KEY,
3395-
);
3396+
const records = {
3397+
air: clientSupportsAirCapability(this.clientCapabilities, AIR_RECOMMENDED_CONFIG_VALUE_KEY),
3398+
neutral: this.capabilities.neutralRecommendedConfigValue,
3399+
};
3400+
const useRecommendedValue = records.air || records.neutral;
33963401
const currentModel = this.findCurrentModel(sessionState.availableModels, sessionState.currentModelId);
33973402
const recommendedModelId = useRecommendedValue
33983403
? sessionState.availableModels.find(model => model.isDefault)?.id
@@ -3403,14 +3408,15 @@ export class CodexAcpServer {
34033408
];
34043409
// A gateway that lists none of the Codex models leaves no model to offer, so there is no model option at all.
34053410
if (sessionState.availableModels.length > 0) {
3406-
configOptions.push(createModelConfigOption(sessionState.availableModels, currentModelId.model, recommendedModelId));
3411+
configOptions.push(createModelConfigOption(sessionState.availableModels, currentModelId.model, recommendedModelId, records));
34073412
}
34083413
if (sessionState.supportedReasoningEfforts.length > 0) {
34093414
configOptions.push(
34103415
createReasoningEffortConfigOption(
34113416
sessionState.supportedReasoningEfforts,
34123417
currentModelId.effort,
34133418
useRecommendedValue ? currentModel?.defaultReasoningEffort : undefined,
3419+
records,
34143420
),
34153421
);
34163422
}

‎src/ModelConfigOption.ts‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import type {SessionConfigOption} from "@agentclientprotocol/sdk/unstable";
22
import type {ReasoningEffort} from "./app-server";
33
import type {Model, ReasoningEffortOption} from "./app-server/v2";
44
import {AIR_RECOMMENDED_CONFIG_VALUE_KEY, withAirMeta} from "./AirExtension";
5+
import {NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY} from "./permissions/metadata";
56

67
export const MODEL_CONFIG_ID = "model";
78
export const REASONING_EFFORT_CONFIG_ID = "reasoning_effort";
@@ -52,10 +53,21 @@ function modelOptions(availableModels: ReadonlyArray<Model>, currentBaseModelId:
5253
return options;
5354
}
5455

56+
/** Which `_meta` records carry a recommendation. The client can opt into either, or both. */
57+
export type RecommendationRecords = {readonly air: boolean; readonly neutral: boolean};
58+
59+
function recommendationMeta(value: string, records: RecommendationRecords): Record<string, unknown> {
60+
return {
61+
...(records.air ? withAirMeta(undefined, AIR_RECOMMENDED_CONFIG_VALUE_KEY, value) : {}),
62+
...(records.neutral ? {[NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY]: {version: 1, value}} : {}),
63+
};
64+
}
65+
5566
export function createModelConfigOption(
5667
availableModels: Array<Model>,
5768
currentBaseModelId: string,
5869
recommendedModelId?: string,
70+
records: RecommendationRecords = {air: true, neutral: false},
5971
): SessionConfigOption {
6072
const options = modelOptions(availableModels, currentBaseModelId);
6173

@@ -71,7 +83,7 @@ export function createModelConfigOption(
7183
currentValue: currentBaseModelId,
7284
options,
7385
...(recommendation
74-
? {_meta: withAirMeta(undefined, AIR_RECOMMENDED_CONFIG_VALUE_KEY, recommendation)}
86+
? {_meta: recommendationMeta(recommendation, records)}
7587
: {}),
7688
};
7789
}
@@ -80,6 +92,7 @@ export function createReasoningEffortConfigOption(
8092
supportedReasoningEfforts: Array<ReasoningEffortOption>,
8193
currentEffort: string,
8294
recommendedEffort?: string,
95+
records: RecommendationRecords = {air: true, neutral: false},
8396
): SessionConfigOption {
8497
const recommendation = findSupportedEffort(supportedReasoningEfforts, recommendedEffort);
8598
return {
@@ -95,7 +108,7 @@ export function createReasoningEffortConfigOption(
95108
description: option.description,
96109
})),
97110
...(recommendation
98-
? {_meta: withAirMeta(undefined, AIR_RECOMMENDED_CONFIG_VALUE_KEY, recommendation)}
111+
? {_meta: recommendationMeta(recommendation, records)}
99112
: {}),
100113
};
101114
}

‎src/__tests__/CodexACPAgent/initialize-v2.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,10 +145,11 @@ describe('CodexACPAgent - initialize over ACP v2', () => {
145145

146146
it("ignores the client-neutral presentation opt-ins", () => {
147147
const capabilities = ClientCapabilities.fromV2(toV1ClientCapabilitiesView({
148-
_meta: {permissionPresentation: {version: 1}, questionCustomAnswer: {version: 1}},
148+
_meta: {permissionPresentation: {version: 1}, questionCustomAnswer: {version: 1}, recommendedConfigValue: {version: 1}},
149149
}));
150150
expect(capabilities.neutralPermissionPresentation).toBe(false);
151151
expect(capabilities.neutralQuestionCustomAnswer).toBe(false);
152+
expect(capabilities.neutralRecommendedConfigValue).toBe(false);
152153
});
153154

154155
it('ignores the client-neutral agent file-change report opt-in', async () => {

‎src/__tests__/CodexACPAgent/initialize.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ describe('CodexACPAgent - initialize', () => {
261261
expect((both._meta as any).jetbrains).toEqual((airOnly._meta as any).jetbrains);
262262
});
263263

264-
it.each(['permissionPresentation', 'questionCustomAnswer'])('advertises the client-neutral %s only to a client that opts in', async (key) => {
264+
it.each(['permissionPresentation', 'questionCustomAnswer', 'recommendedConfigValue'])('advertises the client-neutral %s only to a client that opts in', async (key) => {
265265
const optedIn = await agent.initialize({
266266
protocolVersion: acp.PROTOCOL_VERSION,
267267
clientCapabilities: {_meta: {[key]: {version: 2}}},

‎src/__tests__/CodexACPAgent/session-config-options.test.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,47 @@ describe("Session config options", () => {
209209
});
210210
});
211211

212+
it("recommends through the neutral record without changing the selection, and recomputes effort on a model switch", async () => {
213+
const {fast, slow} = buildModels();
214+
const {response, codexAcpAgent} = await createSession("fast-model[medium]", [fast, slow], {
215+
_meta: {recommendedConfigValue: {version: 1}},
216+
});
217+
218+
expect(response.configOptions?.find(option => option.id === MODEL_CONFIG_ID)).toMatchObject({
219+
currentValue: "fast-model",
220+
_meta: {recommendedConfigValue: {version: 1, value: "fast-model"}},
221+
});
222+
const effort = response.configOptions?.find(option => option.id === REASONING_EFFORT_CONFIG_ID);
223+
expect(effort).toMatchObject({
224+
currentValue: "medium",
225+
_meta: {recommendedConfigValue: {version: 1, value: "medium"}},
226+
});
227+
expect(effort?._meta).not.toHaveProperty("jetbrains");
228+
229+
const switched = await codexAcpAgent.setSessionConfigOption({
230+
sessionId: "session-id",
231+
configId: MODEL_CONFIG_ID,
232+
value: "slow-model",
233+
});
234+
expect(switched.configOptions?.find(option => option.id === MODEL_CONFIG_ID)).toMatchObject({
235+
currentValue: "slow-model",
236+
_meta: {recommendedConfigValue: {value: "fast-model"}},
237+
});
238+
expect(switched.configOptions?.find(option => option.id === REASONING_EFFORT_CONFIG_ID)).toHaveProperty(
239+
"_meta.recommendedConfigValue.value",
240+
"low",
241+
);
242+
});
243+
244+
it("sends no recommendation to a client that does not opt in", async () => {
245+
const {fast, slow} = buildModels();
246+
const {response} = await createSession("fast-model[medium]", [fast, slow]);
247+
248+
for (const id of [MODEL_CONFIG_ID, REASONING_EFFORT_CONFIG_ID]) {
249+
expect(response.configOptions?.find(option => option.id === id)?._meta).toBeUndefined();
250+
}
251+
});
252+
212253
it("omits a model recommendation when the catalog has no default", async () => {
213254
const {fast, slow} = buildModels();
214255
fast.isDefault = false;

‎src/permissions/metadata.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ export const PERMISSION_PROMPT_META_KEY = "permission_prompt";
2828
export const NEUTRAL_PERMISSION_PRESENTATION_META_KEY = "permissionPresentation";
2929
/** The top-level `_meta` key of the client-neutral question custom answer. */
3030
export const NEUTRAL_QUESTION_CUSTOM_ANSWER_META_KEY = "questionCustomAnswer";
31+
/** The top-level `_meta` key of the client-neutral recommended config value. */
32+
export const NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY = "recommendedConfigValue";
3133

3234
/** The `initialize` answer for a client that opted into a client-neutral presentation contract. */
3335
export function neutralPresentationCapability(): {version: number} {

‎src/tool-calls/ClientCapabilities.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
clientRequestsNeutralPresentation,
1717
NEUTRAL_PERMISSION_PRESENTATION_META_KEY,
1818
NEUTRAL_QUESTION_CUSTOM_ANSWER_META_KEY,
19+
NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY,
1920
} from "../permissions/metadata";
2021

2122
/** The `_meta` key of a command output chunk. */
@@ -52,6 +53,7 @@ type ClientCapabilityValues = {
5253
readonly permissionPromptFields: boolean;
5354
readonly neutralPermissionPresentation: boolean;
5455
readonly neutralQuestionCustomAnswer: boolean;
56+
readonly neutralRecommendedConfigValue: boolean;
5557
};
5658

5759
/**
@@ -77,6 +79,7 @@ export class ClientCapabilities {
7779
permissionPromptFields: false,
7880
neutralPermissionPresentation: false,
7981
neutralQuestionCustomAnswer: false,
82+
neutralRecommendedConfigValue: false,
8083
});
8184

8285
/** The client declares `_meta.jetbrains.air`. */
@@ -103,6 +106,8 @@ export class ClientCapabilities {
103106
readonly neutralPermissionPresentation: boolean;
104107
/** A question's note field carries `_meta.questionCustomAnswer`. Only ACP v1 reads the opt-in. */
105108
readonly neutralQuestionCustomAnswer: boolean;
109+
/** Model and effort selectors carry `_meta.recommendedConfigValue`. Only ACP v1 reads the opt-in. */
110+
readonly neutralRecommendedConfigValue: boolean;
106111

107112
private constructor(values: ClientCapabilityValues) {
108113
this.airClient = values.airClient;
@@ -119,6 +124,7 @@ export class ClientCapabilities {
119124
this.permissionPromptFields = values.permissionPromptFields;
120125
this.neutralPermissionPresentation = values.neutralPermissionPresentation;
121126
this.neutralQuestionCustomAnswer = values.neutralQuestionCustomAnswer;
127+
this.neutralRecommendedConfigValue = values.neutralRecommendedConfigValue;
122128
}
123129

124130
static from(capabilities: acp.ClientCapabilities | null | undefined): ClientCapabilities {
@@ -153,6 +159,7 @@ export class ClientCapabilities {
153159
permissionPromptFields: false,
154160
neutralPermissionPresentation: clientRequestsNeutralPresentation(capabilities, NEUTRAL_PERMISSION_PRESENTATION_META_KEY),
155161
neutralQuestionCustomAnswer: clientRequestsNeutralPresentation(capabilities, NEUTRAL_QUESTION_CUSTOM_ANSWER_META_KEY),
162+
neutralRecommendedConfigValue: clientRequestsNeutralPresentation(capabilities, NEUTRAL_RECOMMENDED_CONFIG_VALUE_META_KEY),
156163
});
157164
}
158165

@@ -185,6 +192,7 @@ export class ClientCapabilities {
185192
// A v2 request has its own title and description, so v2 ignores both client-neutral opt-ins.
186193
neutralPermissionPresentation: false,
187194
neutralQuestionCustomAnswer: false,
195+
neutralRecommendedConfigValue: false,
188196
});
189197
}
190198

0 commit comments

Comments
 (0)