Skip to content

Commit ab513aa

Browse files
authored
feat: update ACP SDK to 2.4 and align protocol behavior (#727)
## Summary Upgrade `@agentclientprotocol/sdk` from 2.2.0 to 2.4.0 (schemas v1.29.1 and v2.0.0-alpha.13), including the newly released `stopWaitingOnCancel` support. - Stop waiting for cancelled permission requests without requiring a Client response. Keep async elicitation late-answer handling intact. - Add standard `session/set_title` on ACP v1 and v2, reusing existing persistence, normalization, write ordering, and automatic-title safeguards. - Reject empty system-prompt content before lifecycle changes, preserving existing client and AIR instructions. - Add cross-version regression coverage and document the title wire contract. ## AIR compatibility The existing AIR API is preserved: private methods, capability gates, response shapes, and `_meta` contracts are unchanged. Shared title internals are reused, but `_session/rename` retains its empty result and existing semantics. Standard ACP compatibility fixes also apply when the Client is AIR. The 33 AIR scenario snapshot changes were checked programmatically: their only change is the additive standard `sessionCapabilities.title: {}` initialization capability. Existing frozen baselines were not regenerated. ## Review scope Reviewed all four schemas, stable/draft protocol pages, and changed RFDs since schema v1.28.0 / v2.0.0-alpha.11. The SDK upgrade primarily adjusts existing permission-cancellation and system-prompt behavior. The already completed `session/set_title` change is retained. All other new RFD implementations are on hold: no session-status, auth-status, archive/unarchive, proxy, or background-work reporting/control features are added. The session-status prototype is not included in this PR. Unsupported optional capabilities remain unadvertised. No plan Markdown file is included. ## Validation - Published npm SDK 2.4.0 installed and verified; no local SDK substitution. - `npm run typecheck` — passed, including examples. - `npm test` — 2,418 passed, 39 skipped. - `npm run build` — passed. - `git diff --check` — passed. - Real Codex prompt smoke — completed with `end_turn`. - Real wire smoke against the built executable on both ACP v1 and v2 — normalized title returned and persistence verified through `session/list`. Separate integration/E2E suites and cross-platform bundles were not run. `npm audit` reports four unchanged dependency advisories; no unrelated dependency fixes were applied.
1 parent 3b35338 commit ab513aa

54 files changed

Lines changed: 243 additions & 67 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/session-title.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Client-set session titles
2+
3+
The adapter supports the unstable ACP `session/set_title` method on v1 and v2.
4+
It advertises `agentCapabilities.sessionCapabilities.title: {}` on v1 and
5+
`capabilities.session.title: {}` on v2. No Client capability or AIR extension
6+
is required.
7+
8+
```json
9+
{
10+
"jsonrpc": "2.0",
11+
"id": 1,
12+
"method": "session/set_title",
13+
"params": {
14+
"sessionId": "thread-id",
15+
"title": "Investigate timeout"
16+
}
17+
}
18+
```
19+
20+
`sessionId` and `title` are required strings. The session can be active or saved.
21+
The adapter collapses whitespace, trims the title, and caps it at 256 UTF-16 code
22+
units, including a trailing ellipsis when truncated. It does not split a
23+
surrogate pair at the truncation boundary.
24+
25+
On success, the result is `{"title": "Investigate timeout"}` with the normalized
26+
title. The response is sent only after Codex persists it. Later `session/list`
27+
results report that title. Active sessions also receive a `session_info_update`
28+
with it. Saved sessions are not loaded just to rename them.
29+
30+
Missing, `null`, non-string, or blank titles fail with `-32602`. Titles cannot
31+
be cleared through this method. Unknown sessions fail with `-32002` and
32+
`data.sessionId`. Codex may refuse to rename an archived, unpersisted, or
33+
externally locked session. Storage and process failures remain errors, not
34+
successful title changes.
35+
36+
A successful request suppresses the adapter's automatic title writes, including
37+
generation already in flight. It does not stop later user-initiated renames.
38+
The existing AIR `_session/rename` extension uses the same implementation and
39+
keeps its empty result and capability gate.

‎package-lock.json‎

Lines changed: 4 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@
6868
"vitest": "^5.0.1"
6969
},
7070
"dependencies": {
71-
"@agentclientprotocol/sdk": "~2.2.0",
71+
"@agentclientprotocol/sdk": "~2.4.0",
7272
"@openai/codex": "^0.165.0",
7373
"cross-spawn": "^7.0.6",
7474
"diff": "^9.0.0",

‎readme-dev.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,8 @@ to v2; it reuses the runtime environment variables above.
169169

170170
Both ACP versions advertise `systemPrompt: {}`: text-only `append` mode. Override and non-text
171171
content are rejected with `-32602` before a session is created or a fork is made.
172+
An empty `content` array is also rejected before any lifecycle change; it does not clear
173+
existing client or AIR instructions.
172174
Text blocks are joined with a blank line and appended to the existing developer-instruction
173175
baseline: AIR `customInstructions` when supplied, otherwise configured Codex developer instructions.
174176
Codex's base instructions and workspace context remain intact. Requests without `systemPrompt`

‎src/ACPSessionConnection.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ export class AcpV2Connection {
207207
const response = await this.client.request(
208208
acpV2.methods.client.session.requestPermission,
209209
toV2RequestPermissionRequest(request),
210-
options,
210+
{...options, stopWaitingOnCancel: true},
211211
);
212212
return toV1RequestPermissionResponse(response);
213213
}, options?.cancellationSignal);

‎src/AcpAgentRouter.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ function createRouter(
194194
.onRequest(acp.methods.agent.session.close, (ctx) => getAgent(ctx.params).closeSession(ctx.params))
195195
.onRequest(acp.methods.agent.session.setMode, (ctx) => getAgent(ctx.params).setSessionMode(ctx.params))
196196
.onRequest(acp.methods.agent.session.setConfigOption, (ctx) => getAgent(ctx.params).setSessionConfigOption(ctx.params))
197+
.onRequest(acp.methods.agent.session.setTitle, (ctx) => getAgent(ctx.params).sessionIndex.setTitle(ctx.params))
197198
.onRequest(acp.methods.agent.authenticate, (ctx) => getAgent().authenticate(ctx.params, ctx.requestId, ctx.signal))
198199
.onRequest(acp.methods.agent.logout, (ctx) => getAgent().logout(ctx.params))
199200
.onRequest(acp.methods.agent.providers.list, (ctx) => getAgent().listProviders(ctx.params))
@@ -228,6 +229,7 @@ function createRouter(
228229
.onRequest(acpV2.methods.agent.session.close, (ctx) => getAgent(ctx.params).closeSession(ctx.params))
229230
// No `session/set_mode`: v2 removed the modes API; modes are config options.
230231
.onRequest(acpV2.methods.agent.session.setConfigOption, (ctx) => getAgent(ctx.params).setSessionConfigOptionV2(ctx.params))
232+
.onRequest(acpV2.methods.agent.session.setTitle, (ctx) => getAgent(ctx.params).sessionIndex.setTitle(ctx.params))
231233
// The v1-only `authentication/status|logout` extensions are not registered on v2.
232234
.onRequest(acpV2.methods.agent.auth.login, (ctx) => getAgent().authenticateV2(ctx.params, ctx.requestId, ctx.signal))
233235
.onRequest(acpV2.methods.agent.auth.logout, (ctx) => getAgent().logoutV2(ctx.params))

‎src/AcpClientDelivery.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -204,8 +204,10 @@ export class AcpClientDelivery {
204204
try {
205205
const setup = this.waitForSessionSetup(sessionId, cancellationSignal);
206206
if (setup) await setup;
207+
// Permission cancellation is a denial. Async elicitations still inspect late answers.
207208
return await this.withElicitationRequest(method, params,
208-
() => this.client.request(method, params, {...options, cancellationSignal}));
209+
() => this.client.request(method, params, {...options, cancellationSignal,
210+
stopWaitingOnCancel: method === acp.methods.client.session.requestPermission || options?.stopWaitingOnCancel === true}));
209211
} finally {
210212
requests.delete(controller);
211213
if (requests.size === 0) this.sessionRequests.delete(sessionId);

‎src/ClientSystemPrompt.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ export function clientSystemPromptText(value: unknown): string | undefined {
1515
|| !("content" in value) || !Array.isArray(value.content)) {
1616
throw RequestError.invalidParams(undefined, "systemPrompt requires append mode and text content");
1717
}
18+
if (value.content.length === 0) {
19+
throw RequestError.invalidParams(undefined, "systemPrompt content must not be empty");
20+
}
1821
const blocks: string[] = [];
1922
for (const block of value.content) {
2023
if (block === null || typeof block !== "object" || block.type !== "text" || typeof block.text !== "string") {

‎src/CodexAcpServer.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -822,6 +822,7 @@ export class CodexAcpServer {
822822
close: { },
823823
delete: { },
824824
fork: { },
825+
title: {},
825826
additionalDirectories: {},
826827
subagents: {},
827828
systemPrompt: {},
@@ -906,6 +907,7 @@ export class CodexAcpServer {
906907
delete: {},
907908
additionalDirectories: {},
908909
fork: {},
910+
title: {},
909911
systemPrompt: {},
910912
},
911913
},

‎src/SessionIndexService.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
/**
22
* The AIR `sessionIndex` extension as `CodexAcpServer` serves it: the session list, `_session/rename`,
3-
* `_session/archive`, `_session/unarchive`, `session/delete` and `_session/list/subscribe`. Nothing here runs
4-
* for a client that does not declare `sessionIndex`. See `SessionIndex.ts` and `docs/air-extensions.md`.
3+
* `_session/archive`, `_session/unarchive`, `session/delete` and `_session/list/subscribe`.
4+
* `session/set_title` shares its title writer without requiring AIR capabilities.
5+
* See `SessionIndex.ts` and `docs/air-extensions.md`.
56
*/
67

78
import path from "node:path";
@@ -236,11 +237,16 @@ export class SessionIndexService {
236237
/** `_session/rename`. */
237238
async rename({sessionId, title}: SessionRenameRequest): Promise<Record<string, never>> {
238239
this.require(SESSION_RENAME_METHOD);
239-
await this.host.ensureAppServer();
240-
await this.titles.rename(sessionId, title);
240+
await this.setTitle({sessionId, title});
241241
return {};
242242
}
243243

244+
/** Standard title requests share persistence, normalization and automatic-title suppression with AIR. */
245+
async setTitle({sessionId, title}: acp.SetSessionTitleRequest): Promise<acp.SetSessionTitleResponse> {
246+
await this.host.ensureAppServer();
247+
return {title: await this.titles.rename(sessionId, title)};
248+
}
249+
244250
/**
245251
* `_session/archive` and `_session/unarchive`, as `session/archive` and `session/unarchive` of ACP RFD #2161.
246252
* Both are idempotent and work for a session that is not loaded. Archiving stops a session that is open here,

0 commit comments

Comments
 (0)