Skip to content

Commit a1bfcc7

Browse files
committed
feat: adapt the client-neutral session index to v2.4.0
Upstream v2.4.0 (agentclientprotocol#669) adds `_session/batch_get` with the agent capability `sessionBatchGet`, listed with the AIR session index capabilities, and moves the rollout reads of SessionListSubscriptions to `listedThreadEntry`/`isInteractiveSource` (agentclientprotocol#689). Neither absorbs the client-neutral session index (no upstream PR). Keep the downstream behaviour: a client that is not AIR and declares `_meta.sessionIndex: {version}` on ACP v1 gets the same session index under `_meta.sessionIndex`. `batchGet` builds its rows with the client's namespace, so the neutral answer of initialize now lists `sessionBatchGet` like AIR's, and the docs name `_session/batch_get` among the unchanged requests. The conflicts in docs, SessionIndexService and SessionListSubscriptions take upstream's lines next to the downstream ones. A new test (neutral batch_get rows equal AIR's under `_meta.sessionIndex`) and the updated initialize test fail without the adaptation. Adapted from aff30ea (original bf6dd64).
1 parent 9d0f02a commit a1bfcc7

8 files changed

Lines changed: 369 additions & 60 deletions

File tree

‎docs/air-extensions.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1012,7 +1012,8 @@ This section covers only the AIR bridge.
10121012
## Session index
10131013

10141014
AIR uses `session/list` as its index of Codex threads when it declares `sessionIndex`.
1015-
Everything in this section applies only to such a client. The `initialize` answer to it lists `sessionIndex`,
1015+
Everything in this section applies only to such a client, or to a client that is not AIR and opts in as in
1016+
[Client-neutral session index](#client-neutral-session-index). The `initialize` answer to AIR lists `sessionIndex`,
10161017
`sessionBatchGet`, `sessionArchive`, `sessionRename`, `sessionListSubscribe` and `sessionWorktrees` in `_meta.jetbrains.air.capabilities`.
10171018
Another client, AIR included, keeps the old `session/list`, `session/delete` and `initialize` answers.
10181019
ACP v1 and v2 connections get the same session index.
@@ -1375,6 +1376,39 @@ Remaining differences:
13751376
- Archive stops a session that is open here, as `session/close` does; #2161 leaves execution alone. The ACP session
13761377
list extensions RFD proposes this change to #2161.
13771378

1379+
### Client-neutral session index
1380+
1381+
A client that is not AIR gets the same session index without declaring `_meta.jetbrains.air`, which would also
1382+
change its tool call contract and subagent reports. It declares, in `initialize.clientCapabilities._meta`:
1383+
1384+
```json
1385+
{ "sessionIndex": { "version": 1 } }
1386+
```
1387+
1388+
- Accepted only when `sessionIndex` is an object whose `version` is an integer of at least 1. Anything else
1389+
enables nothing.
1390+
- An AIR client is governed only by its `sessionIndex` capability; its top-level `_meta.sessionIndex` is ignored.
1391+
- The opt-in is an ACP v1 extension. On an ACP v2 connection only AIR gets the session index.
1392+
- The `initialize` answer has
1393+
`_meta.sessionIndex: {"version": 1, "capabilities": ["sessionBatchGet", "sessionArchive", "sessionRename", "sessionListSubscribe", "sessionWorktrees"]}`
1394+
and no `_meta.jetbrains`.
1395+
1396+
The payloads and rules are the ones of this section, with `_meta.sessionIndex` in place of `_meta.jetbrains.air`.
1397+
The payloads carry no `version`:
1398+
1399+
| AIR | Client-neutral |
1400+
| --- | --- |
1401+
| `session/list` `_meta.jetbrains.air.list {limit, includeWorktrees, archived}` | `_meta.sessionIndex.list {limit, includeWorktrees, archived}` |
1402+
| row `_meta.jetbrains.air.{archived, lastPromptAt, model, forkedFrom, state, lastTurnEndedAt, agentWorktree}` | row `_meta.sessionIndex.{…}` |
1403+
| `_session/list/changes` rows | the same rows, `_meta.sessionIndex` |
1404+
| `_session/batch_get` rows | the same rows, `_meta.sessionIndex` |
1405+
| `session_info_update._meta.jetbrains.air.archived` | `session_info_update._meta.sessionIndex.archived` |
1406+
| `_session/batch_get`, `_session/rename`, `_session/archive`, `_session/unarchive`, `_session/list/subscribe`, `_session/list/unsubscribe`, `_session/list/changes` | unchanged |
1407+
1408+
- The adapter reads the list options only from the client's own namespace.
1409+
- `session/delete` deletes the thread, as for AIR with `sessionIndex`.
1410+
- Everything else is what a client that is not AIR gets: tool calls, subagent reports, `goal` and `async-tasks`.
1411+
13781412
## Context compaction
13791413

13801414
The adapter implements the ACP session compaction RFD. See [Session compaction](session-compaction.md).

‎src/CodexAcpServer.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,7 @@ import {
217217
clientSupportsAirCapability,
218218
JETBRAINS_META_KEY,
219219
} from "./AirExtension";
220+
import {NEUTRAL_SESSION_INDEX_META_KEY} from "./SessionIndex";
220221
import {SessionIndexService} from "./SessionIndexService";
221222
import type {SessionIndexTitleState} from "./SessionIndexTitles";
222223
import {ASYNC_TASK_STOP_METHOD, asyncTaskCapability} from "./async-tasks/AsyncTaskExtension";
@@ -558,7 +559,7 @@ export class CodexAcpServer {
558559
*/
559560
private providerRequests = 0;
560561
private appliedProviderRequest = 0;
561-
/** The AIR `sessionIndex` extension, see `SessionIndexService.ts`. */
562+
/** The `sessionIndex` extension, for AIR or a client-neutral opt-in, see `SessionIndexService.ts`. */
562563
readonly sessionIndex = new SessionIndexService({
563564
connection: () => this.connection,
564565
client: () => this.codexAcpClient,
@@ -844,7 +845,7 @@ export class CodexAcpServer {
844845
this.reportingConnection.reports.compareMeta = this.capabilities.airToolCallContract;
845846
// Boolean config options are baseline on v2, so there is nothing to probe.
846847
this.booleanConfigOptionsSupported = true;
847-
this.sessionIndex.configure(clientCapabilities);
848+
this.sessionIndex.configure(clientCapabilities, {neutral: false});
848849
await this.runWithProcessCheck(() => this.codexAcpClient.initialize({clientInfo: params.info}));
849850
this.sessionIndex.observe(this.codexAcpClient);
850851
this.publishFirstAuthStatusAfterResponse();
@@ -912,6 +913,7 @@ export class CodexAcpServer {
912913
AIR_RECOMMENDED_CONFIG_VALUE_KEY,
913914
...this.sessionIndex.agentCapabilities(),
914915
];
916+
const neutralSessionIndex = this.sessionIndex.neutralCapability();
915917
const goalCapability = {
916918
version: GOAL_EXTENSION_VERSION,
917919
controlMethod: GOAL_CONTROL_METHOD,
@@ -929,6 +931,10 @@ export class CodexAcpServer {
929931
...(this.capabilities.asyncTasks && !this.capabilities.airClient ? {
930932
"async-tasks": asyncTaskCapability(),
931933
} : {}),
934+
// The session index for a client that opted in without AIR, see `docs/air-extensions.md`.
935+
...(neutralSessionIndex ? {
936+
[NEUTRAL_SESSION_INDEX_META_KEY]: neutralSessionIndex,
937+
} : {}),
932938
...(this.capabilities.airClient ? {
933939
[JETBRAINS_META_KEY]: {
934940
[AIR_META_KEY]: {

‎src/SessionIndex.ts‎

Lines changed: 69 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
/**
2-
* The AIR `sessionIndex` extension: the session list that AIR uses as its
2+
* The `sessionIndex` extension: the session list that a client uses as its
33
* index of Codex threads, and the requests that change an entry of it.
44
*
55
* Everything here applies only to a client that declares `sessionIndex` in
6-
* `clientCapabilities._meta.jetbrains.air.capabilities`. Other clients keep
6+
* `clientCapabilities._meta.jetbrains.air.capabilities` (AIR) or, without AIR,
7+
* `clientCapabilities._meta.sessionIndex: {version}`. Other clients keep
78
* the `session/list` path of {@link CodexAcpClient.listSessions}.
89
* See `docs/air-extensions.md`.
910
*/
@@ -13,7 +14,7 @@ import {RequestError} from "@agentclientprotocol/sdk/unstable";
1314
import {z} from "zod";
1415
import type {ServerNotification} from "./app-server";
1516
import type {Thread, ThreadListParams, ThreadListResponse, ThreadStatus, Turn} from "./app-server/v2";
16-
import {AIR_META_KEY, JETBRAINS_META_KEY, withAirMeta} from "./AirExtension";
17+
import {AIR_META_KEY, clientSupportsAirCapability, isAirClient, JETBRAINS_META_KEY, withAirMeta} from "./AirExtension";
1718
import {listedSessionTitle} from "./SessionTitle";
1819
import {isArchivedRolloutPath} from "./SessionIndexMutations";
1920
import {logger} from "./Logger";
@@ -54,6 +55,58 @@ export const MAX_SESSION_INDEX_LIMIT = 100;
5455
/** The `_meta.jetbrains.air` key of the archive state of a session list row or `session_info_update`. */
5556
export const AIR_ARCHIVED_KEY = "archived";
5657

58+
/** The top-level `_meta` key of the session index for a client that is not AIR. */
59+
export const NEUTRAL_SESSION_INDEX_META_KEY = "sessionIndex";
60+
export const NEUTRAL_SESSION_INDEX_VERSION = 1;
61+
62+
/**
63+
* Where the session index reads and writes metadata for a client: `_meta.jetbrains.air` for AIR, and the
64+
* top-level `_meta.sessionIndex` for a client that opted in without AIR. The payloads are the same.
65+
*/
66+
export interface SessionIndexMeta {
67+
/** The payload object of the namespace in `meta`, or `{}`. */
68+
read(meta: unknown): Record<string, unknown>;
69+
/** `meta` with `key` set in the namespace, other keys kept. */
70+
write(meta: Record<string, unknown> | null | undefined, key: string, value: unknown): Record<string, unknown>;
71+
}
72+
73+
export const AIR_SESSION_INDEX_META: SessionIndexMeta = {
74+
read: (meta) => asRecord(asRecord(asRecord(meta)[JETBRAINS_META_KEY])[AIR_META_KEY]),
75+
write: withAirMeta,
76+
};
77+
78+
export const NEUTRAL_SESSION_INDEX_META: SessionIndexMeta = {
79+
read: (meta) => asRecord(asRecord(meta)[NEUTRAL_SESSION_INDEX_META_KEY]),
80+
write: (meta, key, value) => {
81+
const root = asRecord(meta);
82+
return {...root, [NEUTRAL_SESSION_INDEX_META_KEY]: {...asRecord(root[NEUTRAL_SESSION_INDEX_META_KEY]), [key]: value}};
83+
},
84+
};
85+
86+
/**
87+
* The session index namespace of a client, or `null` when it has no session index. AIR is governed only by its
88+
* `sessionIndex` capability and its top-level `_meta.sessionIndex` is ignored. Another client opts in with
89+
* `_meta.sessionIndex: {version}`, an integer of at least 1.
90+
*/
91+
export function sessionIndexMetaOf(capabilities: acp.ClientCapabilities | null | undefined): SessionIndexMeta | null {
92+
if (isAirClient(capabilities)) {
93+
return clientSupportsAirCapability(capabilities, AIR_SESSION_INDEX_KEY) ? AIR_SESSION_INDEX_META : null;
94+
}
95+
const declared = capabilities?._meta?.[NEUTRAL_SESSION_INDEX_META_KEY];
96+
if (declared === null || typeof declared !== "object" || Array.isArray(declared)) return null;
97+
const version = (declared as Record<string, unknown>)["version"];
98+
return typeof version === "number" && Number.isInteger(version) && version >= 1 ? NEUTRAL_SESSION_INDEX_META : null;
99+
}
100+
101+
/**
102+
* The fields of a row that the adapter wrote, whichever namespace holds them: a row carries exactly one.
103+
* For the readers that do not know the client, as the list subscriptions.
104+
*/
105+
export function sessionIndexRowFields(row: acp.SessionInfo): Record<string, unknown> {
106+
const air = AIR_SESSION_INDEX_META.read(row._meta);
107+
return Object.keys(air).length > 0 ? air : NEUTRAL_SESSION_INDEX_META.read(row._meta);
108+
}
109+
57110
/** The `archived` list option: which Codex lists the session index reads. */
58111
export type SessionIndexArchivedFilter = "unarchived" | "archived" | "all";
59112

@@ -146,15 +199,18 @@ export const sessionListSubscriptionParamsParser = z.preprocess(
146199
);
147200

148201
/**
149-
* Reads `_meta.jetbrains.air.list` of a `session/list` request.
202+
* Reads `list` of the client's namespace, `_meta.jetbrains.air.list` or `_meta.sessionIndex.list`, of a
203+
* `session/list` request.
150204
*
151205
* @throws RequestError `invalidParams` for a `limit` that is not an integer of at least 1, an `archived` that is
152206
* not `"unarchived"`, `"archived"` or `"all"`, or an `includeWorktrees` that is not a boolean. Omitted and
153207
* `null` mean the default for each.
154208
*/
155-
export function readSessionIndexListOptions(meta: Record<string, unknown> | null | undefined): SessionIndexListOptions {
156-
const jetbrains = asRecord(asRecord(meta)[JETBRAINS_META_KEY]);
157-
const list = asRecord(asRecord(jetbrains[AIR_META_KEY])[AIR_SESSION_LIST_KEY]);
209+
export function readSessionIndexListOptions(
210+
meta: Record<string, unknown> | null | undefined,
211+
namespace: SessionIndexMeta = AIR_SESSION_INDEX_META,
212+
): SessionIndexListOptions {
213+
const list = asRecord(namespace.read(meta)[AIR_SESSION_LIST_KEY]);
158214
return {
159215
limit: readLimit(list["limit"]),
160216
archived: readArchivedFilter(list["archived"]),
@@ -469,6 +525,7 @@ export function sessionIndexSessionInfo(
469525
archived: boolean,
470526
activity: SessionActivity | null,
471527
agentWorktree = false,
528+
namespace: SessionIndexMeta = AIR_SESSION_INDEX_META,
472529
): acp.SessionInfo {
473530
const airFields: Record<string, unknown> = {[AIR_ARCHIVED_KEY]: archived};
474531
// Codex moves `recencyAt` when a turn starts and orders threads by it: the time of the last prompt.
@@ -481,7 +538,7 @@ export function sessionIndexSessionInfo(
481538
if (agentWorktree) airFields[AIR_AGENT_WORKTREE_KEY] = true;
482539
let meta: Record<string, unknown> | undefined;
483540
for (const [key, value] of Object.entries(airFields)) {
484-
meta = withAirMeta(meta, key, value);
541+
meta = namespace.write(meta, key, value);
485542
}
486543
return {
487544
sessionId: thread.id,
@@ -596,10 +653,10 @@ export class SessionIndexActivity {
596653

597654
/**
598655
* What the client shows of a row, without `updatedAt`: a row whose signature did not change is not sent again.
599-
* `title` and the AIR fields `lastPromptAt`, `state`, `lastTurnEndedAt`, `model`, `forkedFrom` and `archived`.
656+
* `title` and the row fields `lastPromptAt`, `state`, `lastTurnEndedAt`, `model`, `forkedFrom` and `archived`.
600657
*/
601658
export function sessionIndexRowSignature(row: acp.SessionInfo): string {
602-
const air = asRecord(asRecord(asRecord(row._meta)[JETBRAINS_META_KEY])[AIR_META_KEY]);
659+
const air = sessionIndexRowFields(row);
603660
return JSON.stringify([
604661
row.title ?? null,
605662
air[AIR_LAST_PROMPT_AT_KEY] ?? null,
@@ -612,9 +669,9 @@ export function sessionIndexRowSignature(row: acp.SessionInfo): string {
612669
]);
613670
}
614671

615-
/** The AIR field `forkedFrom` of a row: the thread that its thread was forked from, else `null`. */
672+
/** The row field `forkedFrom`, in either namespace: the thread that its thread was forked from, else `null`. */
616673
export function sessionIndexRowForkedFrom(row: acp.SessionInfo): string | null {
617-
const forkedFrom = asRecord(asRecord(asRecord(row._meta)[JETBRAINS_META_KEY])[AIR_META_KEY])[AIR_FORKED_FROM_KEY];
674+
const forkedFrom = sessionIndexRowFields(row)[AIR_FORKED_FROM_KEY];
618675
return typeof forkedFrom === "string" ? forkedFrom : null;
619676
}
620677

0 commit comments

Comments
 (0)