Skip to content

Commit bf6dd64

Browse files
committed
feat: expose the session index to clients without the AIR declaration
A client that is not AIR can opt in to the session index with initialize.clientCapabilities._meta.sessionIndex: {version: 1}. It gets the same bounded session/list, row metadata, linked-worktree scope, archive filter, _session/rename, _session/archive, _session/unarchive and the session list subscription as an AIR client that declares sessionIndex, with every payload under top-level _meta.sessionIndex instead of _meta.jetbrains.air. The initialize answer lists sessionArchive, sessionRename and sessionListSubscribe under _meta.sessionIndex, and session/delete deletes the thread. Declaring AIR would also switch the tool call contract and the subagent reports, so the opt-in leaves the client classification alone. An AIR client is governed only by its AIR capability and its top-level sessionIndex key is ignored. AIR clients and clients that do not opt in are unchanged.
1 parent f431e5c commit bf6dd64

8 files changed

Lines changed: 286 additions & 53 deletions

File tree

‎docs/air-extensions.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -997,7 +997,8 @@ This section covers only the AIR bridge.
997997
## Session index
998998

999999
AIR uses `session/list` as its index of Codex threads when it declares `sessionIndex`.
1000-
Everything in this section applies only to such a client. The `initialize` answer to it lists `sessionIndex`,
1000+
Everything in this section applies only to such a client, or to a client that is not AIR and opts in as in
1001+
[Client-neutral session index](#client-neutral-session-index). The `initialize` answer to AIR lists `sessionIndex`,
10011002
`sessionArchive`, `sessionRename` and `sessionListSubscribe` in `_meta.jetbrains.air.capabilities`.
10021003
Another client, AIR included, keeps the old `session/list`, `session/delete` and `initialize` answers.
10031004

@@ -1247,6 +1248,37 @@ Remaining differences:
12471248
- Archive stops a session that is open here, as `session/close` does; #2161 leaves execution alone. The ACP session
12481249
list extensions RFD proposes this change to #2161.
12491250

1251+
### Client-neutral session index
1252+
1253+
A client that is not AIR gets the same session index without declaring `_meta.jetbrains.air`, which would also
1254+
change its tool call contract and subagent reports. It declares, in `initialize.clientCapabilities._meta`:
1255+
1256+
```json
1257+
{ "sessionIndex": { "version": 1 } }
1258+
```
1259+
1260+
- Accepted only when `sessionIndex` is an object whose `version` is an integer of at least 1. Anything else
1261+
enables nothing.
1262+
- An AIR client is governed only by its `sessionIndex` capability; its top-level `_meta.sessionIndex` is ignored.
1263+
- The `initialize` answer has
1264+
`_meta.sessionIndex: {"version": 1, "capabilities": ["sessionArchive", "sessionRename", "sessionListSubscribe"]}`
1265+
and no `_meta.jetbrains`.
1266+
1267+
The payloads and rules are the ones of this section, with `_meta.sessionIndex` in place of `_meta.jetbrains.air`.
1268+
The payloads carry no `version`:
1269+
1270+
| AIR | Client-neutral |
1271+
| --- | --- |
1272+
| `session/list` `_meta.jetbrains.air.list {limit, includeWorktrees, archived}` | `_meta.sessionIndex.list {limit, includeWorktrees, archived}` |
1273+
| row `_meta.jetbrains.air.{archived, lastPromptAt, model, forkedFrom, state, lastTurnEndedAt}` | row `_meta.sessionIndex.{…}` |
1274+
| `_session/list/changes` rows | the same rows, `_meta.sessionIndex` |
1275+
| `session_info_update._meta.jetbrains.air.archived` | `session_info_update._meta.sessionIndex.archived` |
1276+
| `_session/rename`, `_session/archive`, `_session/unarchive`, `_session/list/subscribe`, `_session/list/unsubscribe`, `_session/list/changes` | unchanged |
1277+
1278+
- The adapter reads the list options only from the client's own namespace.
1279+
- `session/delete` deletes the thread, as for AIR with `sessionIndex`.
1280+
- Everything else is what a client that is not AIR gets: tool calls, subagent reports, `goal` and `async-tasks`.
1281+
12501282
## Context compaction
12511283

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

‎src/CodexAcpServer.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@ import {
174174
clientSupportsAirCapability,
175175
JETBRAINS_META_KEY,
176176
} from "./AirExtension";
177+
import {NEUTRAL_SESSION_INDEX_META_KEY} from "./SessionIndex";
177178
import {SessionIndexService} from "./SessionIndexService";
178179
import type {SessionIndexTitleState} from "./SessionIndexTitles";
179180
import {ASYNC_TASK_STOP_METHOD, asyncTaskCapability} from "./async-tasks/AsyncTaskExtension";
@@ -381,7 +382,7 @@ export class CodexAcpServer {
381382
private readonly recovery: AppServerRecovery<SessionState> | null;
382383
private initializeRequest: acp.InitializeRequest | null = null;
383384
private providerUpdate: Promise<void> | null = null;
384-
/** The AIR `sessionIndex` extension, see `SessionIndexService.ts`. */
385+
/** The `sessionIndex` extension, for AIR or a client-neutral opt-in, see `SessionIndexService.ts`. */
385386
readonly sessionIndex = new SessionIndexService({
386387
connection: () => this.connection,
387388
client: () => this.codexAcpClient,
@@ -477,6 +478,8 @@ export class CodexAcpServer {
477478
controlMethod: GOAL_CONTROL_METHOD,
478479
actions: [...GOAL_CONTROL_ACTIONS],
479480
};
481+
// The session index for a client that opted in without AIR, see `docs/air-extensions.md`.
482+
const neutralSessionIndex = this.sessionIndex.neutralCapability();
480483
const sessionCapabilities: SubagentAwareSessionCapabilities = {
481484
resume: { },
482485
list: { },
@@ -527,6 +530,9 @@ export class CodexAcpServer {
527530
...(this.capabilities.asyncTasks && !this.capabilities.airClient ? {
528531
"async-tasks": asyncTaskCapability(),
529532
} : {}),
533+
...(neutralSessionIndex ? {
534+
[NEUTRAL_SESSION_INDEX_META_KEY]: neutralSessionIndex,
535+
} : {}),
530536
// Only AIR gets the AIR extension, see `docs/air-extensions.md`.
531537
...(this.capabilities.airClient ? {
532538
[JETBRAINS_META_KEY]: {

‎src/SessionIndex.ts‎

Lines changed: 67 additions & 10 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";
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 {logger} from "./Logger";
1920

@@ -46,6 +47,58 @@ export const MAX_SESSION_INDEX_LIMIT = 100;
4647
/** The `_meta.jetbrains.air` key of the archive state of a session list row or `session_info_update`. */
4748
export const AIR_ARCHIVED_KEY = "archived";
4849

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

@@ -107,15 +160,18 @@ export const sessionListSubscriptionParamsParser = z.preprocess(
107160
);
108161

109162
/**
110-
* Reads `_meta.jetbrains.air.list` of a `session/list` request.
163+
* Reads `list` of the client's namespace, `_meta.jetbrains.air.list` or `_meta.sessionIndex.list`, of a
164+
* `session/list` request.
111165
*
112166
* @throws RequestError `invalidParams` for a `limit` that is not an integer of at least 1, an `archived` that is
113167
* not `"unarchived"`, `"archived"` or `"all"`, or an `includeWorktrees` that is not a boolean. Omitted and
114168
* `null` mean the default for each.
115169
*/
116-
export function readSessionIndexListOptions(meta: Record<string, unknown> | null | undefined): SessionIndexListOptions {
117-
const jetbrains = asRecord(asRecord(meta)[JETBRAINS_META_KEY]);
118-
const list = asRecord(asRecord(jetbrains[AIR_META_KEY])[AIR_SESSION_LIST_KEY]);
170+
export function readSessionIndexListOptions(
171+
meta: Record<string, unknown> | null | undefined,
172+
namespace: SessionIndexMeta = AIR_SESSION_INDEX_META,
173+
): SessionIndexListOptions {
174+
const list = asRecord(namespace.read(meta)[AIR_SESSION_LIST_KEY]);
119175
return {
120176
limit: readLimit(list["limit"]),
121177
archived: readArchivedFilter(list["archived"]),
@@ -429,6 +485,7 @@ export function sessionIndexSessionInfo(
429485
thread: Thread,
430486
archived: boolean,
431487
activity: SessionActivity | null,
488+
namespace: SessionIndexMeta = AIR_SESSION_INDEX_META,
432489
): acp.SessionInfo {
433490
const airFields: Record<string, unknown> = {[AIR_ARCHIVED_KEY]: archived};
434491
// Codex moves `recencyAt` when a turn starts and orders threads by it: the time of the last prompt.
@@ -440,7 +497,7 @@ export function sessionIndexSessionInfo(
440497
if (activity?.lastTurnEndedAt !== undefined) airFields[AIR_LAST_TURN_ENDED_AT_KEY] = activity.lastTurnEndedAt;
441498
let meta: Record<string, unknown> | undefined;
442499
for (const [key, value] of Object.entries(airFields)) {
443-
meta = withAirMeta(meta, key, value);
500+
meta = namespace.write(meta, key, value);
444501
}
445502
return {
446503
sessionId: thread.id,
@@ -555,10 +612,10 @@ export class SessionIndexActivity {
555612

556613
/**
557614
* What the client shows of a row, without `updatedAt`: a row whose signature did not change is not sent again.
558-
* `title` and the AIR fields `lastPromptAt`, `state`, `lastTurnEndedAt`, `model`, `forkedFrom` and `archived`.
615+
* `title` and the row fields `lastPromptAt`, `state`, `lastTurnEndedAt`, `model`, `forkedFrom` and `archived`.
559616
*/
560617
export function sessionIndexRowSignature(row: acp.SessionInfo): string {
561-
const air = asRecord(asRecord(asRecord(row._meta)[JETBRAINS_META_KEY])[AIR_META_KEY]);
618+
const air = sessionIndexRowFields(row);
562619
return JSON.stringify([
563620
row.title ?? null,
564621
air[AIR_LAST_PROMPT_AT_KEY] ?? null,

‎src/SessionIndexService.ts‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
/**
2-
* The AIR `sessionIndex` extension as `CodexAcpServer` serves it: the session list, `_session/rename`,
2+
* The `sessionIndex` extension as `CodexAcpServer` serves it: the session list, `_session/rename`,
33
* `_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`.
4+
* for a client that does not declare `sessionIndex`, as AIR or as a client-neutral opt-in.
5+
* See `SessionIndex.ts` and `docs/air-extensions.md`.
56
*/
67

78
import path from "node:path";
89
import type * as acp from "@agentclientprotocol/sdk";
910
import {RequestError} from "@agentclientprotocol/sdk";
1011
import {ACPSessionConnection, type AcpClientConnection} from "./ACPSessionConnection";
11-
import {clientSupportsAirCapability, withAirMeta} from "./AirExtension";
1212
import type {ServerNotification} from "./app-server";
1313
import type {CodexAcpClient} from "./CodexAcpClient";
1414
import type {SessionState} from "./CodexAcpServer";
@@ -22,6 +22,9 @@ import {
2222
AIR_SESSION_INDEX_KEY,
2323
AIR_SESSION_LIST_SUBSCRIBE_KEY,
2424
AIR_SESSION_RENAME_KEY,
25+
AIR_SESSION_INDEX_META,
26+
NEUTRAL_SESSION_INDEX_META,
27+
NEUTRAL_SESSION_INDEX_VERSION,
2528
readSessionIndexListOptions,
2629
readSessionIndexPage,
2730
SESSION_ARCHIVE_METHOD,
@@ -31,8 +34,10 @@ import {
3134
SESSION_RENAME_METHOD,
3235
SESSION_UNARCHIVE_METHOD,
3336
SessionIndexActivity,
37+
sessionIndexMetaOf,
3438
sessionIndexSessionInfo,
3539
type SessionArchiveRequest,
40+
type SessionIndexMeta,
3641
type SessionIndexListOptions,
3742
type SessionRenameRequest,
3843
} from "./SessionIndex";
@@ -62,8 +67,8 @@ export interface SessionIndexHost {
6267
type SessionPage = {sessions: acp.SessionInfo[], nextCursor: string | null};
6368

6469
export class SessionIndexService {
65-
/** The client declared the AIR `sessionIndex` capability. */
66-
enabled = false;
70+
/** Where this client's session index metadata goes, or `null` when it did not declare `sessionIndex`. */
71+
private meta: SessionIndexMeta | null = null;
6772
private readonly activity: SessionIndexActivity;
6873
private readonly writes = new SessionWriteQueue();
6974
private readonly titles: SessionIndexTitles;
@@ -98,19 +103,34 @@ export class SessionIndexService {
98103

99104
/** Reads the client capabilities of `initialize`. */
100105
configure(clientCapabilities: acp.ClientCapabilities | undefined): void {
101-
this.enabled = clientSupportsAirCapability(clientCapabilities, AIR_SESSION_INDEX_KEY);
106+
this.meta = sessionIndexMetaOf(clientCapabilities);
107+
}
108+
109+
/** The client declared `sessionIndex`, as AIR or as a client-neutral opt-in. */
110+
get enabled(): boolean {
111+
return this.meta !== null;
102112
}
103113

104114
/**
105-
* The AIR capabilities to answer: only a client that declares `sessionIndex` gets them. `sessionArchive` and
106-
* `sessionRename` name the requests that come with it; the client need not declare them.
115+
* The AIR capabilities to answer: only an AIR client that declares `sessionIndex` gets them. `sessionArchive`
116+
* and `sessionRename` name the requests that come with it; the client need not declare them.
107117
*/
108118
agentCapabilities(): string[] {
109-
return this.enabled
119+
return this.meta === AIR_SESSION_INDEX_META
110120
? [AIR_SESSION_INDEX_KEY, AIR_SESSION_ARCHIVE_KEY, AIR_SESSION_RENAME_KEY, AIR_SESSION_LIST_SUBSCRIBE_KEY]
111121
: [];
112122
}
113123

124+
/** The `_meta.sessionIndex` answer of `initialize` to a client-neutral opt-in, or `null`. */
125+
neutralCapability(): {version: number, capabilities: string[]} | null {
126+
return this.meta === NEUTRAL_SESSION_INDEX_META
127+
? {
128+
version: NEUTRAL_SESSION_INDEX_VERSION,
129+
capabilities: [AIR_SESSION_ARCHIVE_KEY, AIR_SESSION_RENAME_KEY, AIR_SESSION_LIST_SUBSCRIBE_KEY],
130+
}
131+
: null;
132+
}
133+
114134
/**
115135
* Feeds the thread notifications of an app-server, for every thread, to the session index. Each client is
116136
* observed once, and only the client that runs now counts: a crashed one that still reports is ignored.
@@ -148,7 +168,7 @@ export class SessionIndexService {
148168
* reads the local state DB and works without one.
149169
*/
150170
async list(params: acp.ListSessionsRequest): Promise<SessionPage> {
151-
const options = readSessionIndexListOptions(params._meta);
171+
const options = readSessionIndexListOptions(params._meta, this.requireMeta());
152172
const cwd = params.cwd?.trim() || null;
153173
return await this.readRows(cwd, options, params.cursor ?? null);
154174
}
@@ -232,14 +252,14 @@ export class SessionIndexService {
232252
if (archived ? open : this.host.session(sessionId) !== undefined) {
233253
await new ACPSessionConnection(this.host.connection(), sessionId).update({
234254
sessionUpdate: "session_info_update",
235-
_meta: withAirMeta(undefined, AIR_ARCHIVED_KEY, archived),
255+
_meta: this.requireMeta().write(undefined, AIR_ARCHIVED_KEY, archived),
236256
});
237257
}
238258
return {};
239259
}
240260

241261
/**
242-
* Deletes the thread for `session/delete`: AIR then means "delete", not "done", because it has
262+
* Deletes the thread for `session/delete`: a `sessionIndex` client then means "delete", not "done", because it has
243263
* `_session/archive` for that. A thread that this connection had open but Codex never persisted (no
244264
* prompt yet) is gone with the close, so it counts as deleted.
245265
*/
@@ -274,6 +294,11 @@ export class SessionIndexService {
274294
}
275295
}
276296

297+
private requireMeta(): SessionIndexMeta {
298+
if (this.meta === null) throw new Error("The client did not declare sessionIndex");
299+
return this.meta;
300+
}
301+
277302
private async readRows(cwd: string | null, options: SessionIndexListOptions, cursor: string | null): Promise<SessionPage> {
278303
// Codex filters by an absolute cwd. A relative one keeps the basename filter of the old path, which the
279304
// adapter applies to each page of the unfiltered list.
@@ -305,7 +330,7 @@ export class SessionIndexService {
305330
if (activity?.state !== undefined) this.rowsWithState.add(thread.id);
306331
else this.rowsWithState.delete(thread.id);
307332
return this.withActiveAdditionalDirectories(
308-
sessionIndexSessionInfo(thread, entry.archived, activity),
333+
sessionIndexSessionInfo(thread, entry.archived, activity, this.requireMeta()),
309334
);
310335
});
311336
}

‎src/SessionListSubscriptions.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ import type {ServerNotification} from "./app-server";
2626
import type {Thread, ThreadListParams, ThreadListResponse, ThreadReadParams, ThreadReadResponse} from "./app-server/v2";
2727
import {CodexHomeWatcher, type CodexHomeWatcherListener} from "./CodexHomeWatcher";
2828
import {logger} from "./Logger";
29-
import {sessionIndexRowSignature} from "./SessionIndex";
29+
import {AIR_STATE_KEY, sessionIndexRowFields, sessionIndexRowSignature} from "./SessionIndex";
3030
import {isArchivedRolloutPath, isMissingThreadError} from "./SessionIndexMutations";
3131
import {SessionNameLog} from "./SessionNameLog";
3232

@@ -324,10 +324,7 @@ export class SessionListSubscriptions {
324324
this.appServerGeneration++;
325325
if (this.subscriptions.size === 0) return;
326326
const loaded = [...this.groups.values()].flatMap(group => [...group.rows]
327-
.filter(([, {row}]) => {
328-
const meta = row._meta as Record<string, any> | undefined;
329-
return meta?.["jetbrains"]?.["air"]?.["state"] !== undefined;
330-
})
327+
.filter(([, {row}]) => sessionIndexRowFields(row)[AIR_STATE_KEY] !== undefined)
331328
.map(([threadId]) => threadId));
332329
for (const threadId of new Set([...threadIds, ...loaded])) this.threadChanged(threadId);
333330
// Threads whose reads failed with the old app-server, or waited for a new one, are read now.

0 commit comments

Comments
 (0)