Skip to content

Commit 95bc33f

Browse files
feat: add the AIR sessionIndex extension for fast session lists (#590)
## Summary Adds the opt-in AIR `sessionIndex` extension, so that an AIR client can show the latest sessions of a project quickly, with their state, and can rename, archive and unarchive them over ACP. The branch also adds recovery from a crashed Codex app-server, cheaper tool call update dedup, and fixes to token usage and `session/fork`. The extension follows these ACP RFDs. The transport differs (`_meta.jetbrains.air` request options and row fields, `_session/*` methods, AIR capability names), and so does the `archived` list filter: - **Session list extensions** (agentclientprotocol/agent-client-protocol#2323): `limit`, `updatedAt`-desc order, `includeWorktrees`, and the row fields `lastPromptAt`, `model`, `forkedFrom`, `state` and `lastTurnEndedAt`. The RFD's `list_changed` hint is replaced: the adapter pushes changed rows through a subscription (below). - **Session archive** (agentclientprotocol/agent-client-protocol#2161): - `archived` on every row and `session_info_update` on a change; - `-32002` for unknown sessions; - the list filter `archived` is a string with three values: `"unarchived"` (the default for omitted or `null`), `"archived"` (archived only) and `"all"`. #2161 has a boolean, whose `false` and `true` are `"unarchived"` and `"all"`. - **Archiving stops a session that is open here**, as `session/close` does. #2161 leaves execution alone; the session list extensions RFD proposes this change to #2161. - **Client-set titles** (agentclientprotocol/agent-client-protocol#1987): `_session/rename`. Everything is gated on the client declaring `sessionIndex` in `clientCapabilities._meta.jetbrains.air.capabilities`. The agent then lists these in `_meta.jetbrains.air.capabilities` of `initialize`: - `sessionIndex`; - `sessionArchive`: `_session/archive` and `_session/unarchive` (#2161's `archive` capability); - `sessionRename`: `_session/rename` (#1987's rename capability, `setTitle` there); - `sessionListSubscribe`: `_session/list/subscribe`. The client does not declare the last three. Clients that don't declare `sessionIndex`, meaning non-AIR clients and released AIR builds, keep main's session index behaviour: - the same `session/list` path, auth check and `thread/list` params (covered by a snapshot test); - `session/delete` still archives; - the same initialize capabilities; - no watchers and no notifications. ## Session index - **`session/list`**: - One `thread/list` per archive side with `cwd`, `limit` ≤ 100, `sortKey: "recency_at"`, `sourceKinds: []`, `modelProviders: []` and `useStateDbOnly: true`. - With `includeWorktrees`, it also lists the same relative subdirectory in each linked Git worktree, read from `<git-common-dir>/worktrees/*/gitdir` as the Codex TUI does. - `"unarchived"` and `"archived"` each read one Codex list. `"all"` reads both in parallel and merges them by recency, with ties unarchived first. - The adapter cursor holds the Codex cursor of each side and the last rows returned. It is bound to `cwd`, `archived` and `includeWorktrees`; a cursor from another scope fails with `-32602`. - A relative `cwd` gathers several Codex pages up to `limit`, and stops a scan without matches after 300 ms, answering with a cursor. - It doesn't wait for auth. - **Row fields** (`_meta.jetbrains.air`): - `archived`, always present; - `lastPromptAt` (`Thread.recencyAt`, the order key); - `model`; - `forkedFrom`; - `state`; - `lastTurnEndedAt`. `updatedAt` is `Thread.updatedAt`. There is no `cost`, and rows carry no token usage. - **`forkedFrom`** is `Thread.forkedFromId` when Codex gives it. `thread/list` doesn't, so otherwise the adapter reads `session_meta.payload.forked_from_id` from the first line of the rollout: - the read runs in the background, is bounded, and happens once per thread (negative answers are cached too); - a list never waits for it; - a subscription gets the row again when the read ends. - **Row `state`** is set only for a thread loaded here. The first that holds wins: - `requires_action`; - `reviewing`: Codex review mode, during a turn; - `running`; - `error`: the last turn failed, not a user cancel, or `Thread.status` is `systemError`. A new turn, a close or unload, or an app-server restart clears it. - `idle`. Threads that aren't loaded omit `state`. - **`_session/rename`** → `thread/name/set`. It is serialized with automatic titles per session, so an explicit title is never overwritten, also across close and reload. A failed rename keeps automatic titles on. Renaming an archived thread fails with `data.reason: "archived"`. - **`_session/archive`** → `thread/archive`, after closing a session that is open on this connection: - The close works as `session/close` does: it interrupts the running turn, ends the pending prompt and its permission and elicitation requests, and unsubscribes the thread. - `session_info_update` with `archived: true` is then the last update of that session. - A later prompt fails as for a closed session. - If `thread/archive` fails, the session stays closed and unarchived. - **`_session/unarchive`** → `thread/unarchive`. It loads nothing. Archive and unarchive are idempotent: the adapter checks `Thread.path` with `thread/read`. - **`session/delete`** → `thread/delete`, closing a loaded session first. - **Errors**: - a thread held by another process fails with `data.reason: "thread_active_writer"`; - an unknown thread fails with `-32002`; - invalid params or an invalid cursor fail with `-32602`. Documented in `docs/air-extensions.md`, with an extension → RFD mapping table and the remaining differences. ## Session list subscription The methods: - `_session/list/subscribe {cwd}` → `{subscriptionId}`. `cwd` is required and absolute, else `-32602`. A connection can hold at most 128 subscriptions; the next one fails with `-32602` and `data.reason: "too_many_subscriptions"`. - `_session/list/unsubscribe {subscriptionId}` → `{}`. It is idempotent. - Notification `_session/list/changes {subscriptionId, sessions, removed}`. How it behaves: - **Scope**: threads of the cwd, of its canonical path, and of the same subdirectory in the primary checkout and each linked worktree, from interactive sources, archived or not. - **Rows**: each change carries the full row exactly as `session/list` answers it. Subscribing reads no rows, only a small `thread/list` per archive state for the first marks. - The first change of each session after subscribing is sent in full. Later ones are sent only when `title`, `lastPromptAt`, `state`, `lastTurnEndedAt`, `model`, `forkedFrom` or `archived` differ. - `removed` lists deleted threads. - At most one change per thread per second, and nothing before the subscribe answer. - Best effort: no resync and no sequence numbers. - **Detection**: - The adapter's own app-server notifications are handled at once. - Other processes are seen through `fs.watch` of `state_<n>.sqlite-wal` and CODEX_HOME, with a 30 s fallback check. Each burst of writes leads to an `updated_at` scan per archive state. - Renames come from `session_index.jsonl` and archive moves from `archived_sessions/`. - A delete by another process of an unarchived thread is not seen. - **Recovery**: subscriptions survive an app-server crash. New modules: `SessionIndex*.ts` (incl. `SessionIndexWorktrees.ts`), `SessionListSubscriptions.ts`, `CodexHomeWatcher.ts`, `SessionNameLog.ts`, `SessionForkOrigins.ts`, `SessionWriteQueue.ts`. ### Measurements Docker (`node:22`, 2 CPUs, 2 GB), 10k threads, first page of 50: | Query (cold / warm p50 / p95, ms) | Before | After | |---|---|---| | Big project | 47 / 25 / 68 | 42 / 21 / 23 | | `archived: "all"` | 213 / 104 / 260 | 41 / 22 / 26 | | `archived: "all"` + worktrees | 167 / 70 / 203 | 125 / 26 / 30 | Under churn from another Codex app-server (a rename, archive or unarchive every 200 ms for 300 s): - a change reached the subscription with p50 158 ms and p95 162 ms, against 1.03 s and 2.0 s for the old `_session/list_changed` hint; - 0 changes were missed and 0 duplicated; - adapter plus app-server CPU was about 0.02 cores. ## Recover from a crashed Codex app-server Code is in `src/app-server-recovery/`. In Docker load tests, a cold `session/resume` of a 638 MB rollout got the app-server OOM-killed. Main then failed every later request with "Connection is disposed.", and a running prompt never ended. - **`CodexAppServerSupervisor`** owns the child: - It records the code, signal, uptime and stderr of every exit, and tells crashes from intentional stops. - It drains the output before disposing the connection. - It never SIGKILLs the `codex.js` wrapper. - A replacement starts with the same startup args as the first app-server, including main's hook trust override. - **`AppServerRecovery`** starts the app-server again lazily, on the next request that needs it: - It reuses the client's `initialize` handshake and the provider routing. - Backoff is 0/1/2/4 s, and it stops after 5 crashes in 5 min (`CODEX_ACP_APP_SERVER_CRASH_LIMIT` and `CODEX_ACP_APP_SERVER_CRASH_WINDOW_MS`). - An open session is resumed on its next use, with the model, effort, modes, directories and MCP servers that the adapter kept. - A session that the app-server died opening twice in 30 min is refused for the rest of that time. - **Request in flight**: fails with code 1001 and the cause, for example "killed by SIGKILL, which usually means it ran out of memory", plus the stderr tail. - An app-server that exits before its `initialize` handshake keeps main's wording and promises no restart: `Codex process has exited with code N:` plus stderr. An example is one that rejects an invalid hooks config. - The crash-loop error also carries the stderr of the last crash. - **Prompt in flight**: ends at once. - An AIR client gets `end_turn` with the `transport_lost` session failure; other clients get JSON-RPC 1001. - Open tool calls become `failed`, and permission and elicitation requests are cancelled. - A prompt the client already cancelled answers `cancelled`. - **What restarts a crashed app-server**: `session/list`, the `_session/*` requests and `_codex/hooks/list` and `_codex/hooks/trust` do. Close, cancel and shutdown never do. - **No crash**: behaviour is unchanged, and the fast paths add no `await`. ## Other changes - **Tool call update dedup**: `ToolCallReports` compares fields as a shared tree (`src/JsonSnapshot.ts`) instead of running `JSON.stringify` on every update. The same updates are sent and suppressed, checked by a differential test over about 300k random updates. Example: comparing 6 MB of diffs went from 7.4 ms to 0.2 ms. - **App-server logging**: `attachLogs` formats traffic only when `APP_SERVER_LOGS` is set. - **Token usage**: - Cache writes are subtracted from input and reported as `cachedWriteTokens`. - `PromptResponse.usage` and `_meta.quota` report the whole turn, not only the last model request. - A native subagent's usage no longer overwrites the parent session's usage. - **`session/fork`**: the fork stays subscribed. Before, a prompt sent to the fork before a `session/load` never ended. ## Test plan - [x] `npm run typecheck`, `npm test` (1483 passed), `npm run bundle:all` - [x] `RUN_E2E_TESTS=true` `e2e/hooks.test.ts`: the invalid-hooks `initialize` error matches main's - [x] Snapshot test that the legacy `thread/list` params are unchanged without `sessionIndex` - [x] Watcher tests on macOS and Linux (Docker `node:22`) - [x] Merge pagination fuzzers (empty pages, mutations, budget) - [x] Crash recovery unit tests with fake app-servers that die at controlled points, plus Docker SIGKILL reproduction - [x] End-to-end against a real app-server in a throwaway `CODEX_HOME` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 51f78d6 commit 95bc33f

65 files changed

Lines changed: 11863 additions & 217 deletions

File tree

Some content is hidden

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

‎docs/air-extensions.md‎

Lines changed: 262 additions & 2 deletions
Large diffs are not rendered by default.

‎readme-dev.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Set `CODEX_PATH` to run a different Codex binary; versions other than the one sp
1212
- `INITIAL_AGENT_MODE` - initial mode id: `read-only`, `workspace-write`, `agent`, or `agent-full-access`.
1313
- `NO_BROWSER` - hide browser-based ChatGPT auth when set.
1414
- `APP_SERVER_LOGS` - directory for adapter logs.
15+
- `CODEX_ACP_APP_SERVER_CRASH_LIMIT` - how many crashes of the Codex app-server in the crash window stop its automatic restart (default `5`).
16+
- `CODEX_ACP_APP_SERVER_CRASH_WINDOW_MS` - the crash window in milliseconds (default `300000`, 5 minutes).
1517

1618
### Quick start
1719

@@ -102,3 +104,21 @@ the adapter does not rely on notices being displayed.
102104
Command replies, review results, and terminal/retrying errors retain their existing response or
103105
failure channels. Clients advertising session compaction support continue to receive the dedicated
104106
compaction lifecycle instead of the legacy completion advisory.
107+
108+
109+
### App-server recovery
110+
111+
The adapter restarts the Codex app-server when it dies (for example, killed for lack of memory). Its code is in
112+
`src/app-server-recovery/`.
113+
114+
- A request that was waiting on the dead app-server fails with error `1001` and the cause, such as "was killed by
115+
SIGKILL, which usually means it ran out of memory". A running prompt ends at once: open tool calls become `failed`,
116+
open permission dialogs are cancelled, and an AIR client gets the `transport_lost` session failure.
117+
- An app-server that exits before its `initialize` handshake succeeded, such as one that rejects its startup config,
118+
fails the request with "Codex process has exited with code N:" and its stderr, and no promise of a restart.
119+
- The next request starts a new app-server with the same `initialize` handshake and provider routing. A session that
120+
was open is resumed on its next use, with the model, mode and settings that the adapter kept.
121+
- After `CODEX_ACP_APP_SERVER_CRASH_LIMIT` crashes in the crash window the adapter stops restarting it and says so,
122+
with the stderr of the last crash.
123+
A session that the app-server died opening twice in 30 minutes is not opened again for the rest of that time, so
124+
one session that is too large for the memory cannot take the other sessions down with it.

‎src/CodexAcpClient.ts‎

Lines changed: 69 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,22 @@ export class CodexAcpClient {
166166
return this.codexClient;
167167
}
168168

169+
/**
170+
* A client of the same configuration for another app-server: the same config and model provider. The routing
171+
* that the agent set at runtime (gateway auth, `providers/set`) is copied by {@link adoptRoutingFrom}.
172+
*/
173+
withAppServer(codexClient: CodexAppServerClient): CodexAcpClient {
174+
const client = new CodexAcpClient(codexClient, this.config, this.modelProvider ?? undefined);
175+
client.adoptRoutingFrom(this);
176+
return client;
177+
}
178+
179+
/** Takes the runtime routing of `previous`, the client that this client replaces. */
180+
adoptRoutingFrom(previous: CodexAcpClient): void {
181+
this.gatewayConfig = previous.gatewayConfig;
182+
this.gatewayConfigSource = previous.gatewayConfigSource;
183+
}
184+
169185
private readonly defaultClientInfo: ClientInfo = {
170186
name: `${packageJson.name}`, title: "Codex ACP", version: `${packageJson.version}`
171187
};
@@ -183,6 +199,14 @@ export class CodexAcpClient {
183199
}
184200
});
185201
this.configPath = response?.codexHome ?? null;
202+
this.isInitialized = true;
203+
}
204+
205+
private isInitialized = false;
206+
207+
/** The app-server `initialize` handshake of this client succeeded. */
208+
get initialized(): boolean {
209+
return this.isInitialized;
186210
}
187211

188212
getHomePath(): string | null {
@@ -213,6 +237,7 @@ export class CodexAcpClient {
213237
private async authenticateWithApiKey(authRequest: ApiKeyAuthRequest): Promise<Boolean> {
214238
const apiKey = authRequest._meta?.["api-key"]?.apiKey ?? this.readApiKeyFromEnv();
215239
const loginCompletedPromise = this.awaitNextLoginCompleted();
240+
loginCompletedPromise.catch(() => {});
216241
await this.codexClient.accountLogin({
217242
type: "apiKey",
218243
apiKey,
@@ -226,6 +251,7 @@ export class CodexAcpClient {
226251
return true;
227252
}
228253
const loginCompletedPromise = this.awaitNextLoginCompleted();
254+
loginCompletedPromise.catch(() => {});
229255
const loginResponse = await this.codexClient.accountLogin({type: "chatgpt"});
230256
if (loginResponse.type == "chatgpt") {
231257
await open(loginResponse.authUrl);
@@ -267,6 +293,7 @@ export class CodexAcpClient {
267293
throw RequestError.invalidRequest(undefined, "Device code authentication requires URL elicitation support");
268294
}
269295
const loginCompletedPromise = this.awaitNextLoginCompleted();
296+
loginCompletedPromise.catch(() => {});
270297
const loginResponse = await this.codexClient.accountLogin({type: "chatgptDeviceCode"});
271298
if (loginResponse.type !== "chatgptDeviceCode") {
272299
return false;
@@ -276,33 +303,41 @@ export class CodexAcpClient {
276303
message: `Sign in to ChatGPT and enter this code: ${loginResponse.userCode}`,
277304
elicitationId: loginResponse.loginId,
278305
}));
279-
const first = await Promise.race([
280-
loginCompletedPromise.then(result => ({
281-
type: "loginCompleted" as const,
282-
result,
283-
})),
284-
elicitationResponsePromise.then(response => ({
285-
type: "elicitationResponse" as const,
286-
response,
287-
})),
288-
]);
289-
290-
if (first.type === "loginCompleted") {
291-
await urlElicitationRequester.completeElicitation();
292-
return first.result.success;
293-
}
306+
try {
307+
const first = await Promise.race([
308+
loginCompletedPromise.then(result => ({
309+
type: "loginCompleted" as const,
310+
result,
311+
})),
312+
elicitationResponsePromise.then(response => ({
313+
type: "elicitationResponse" as const,
314+
response,
315+
})),
316+
]);
317+
318+
if (first.type === "loginCompleted") {
319+
await urlElicitationRequester.completeElicitation();
320+
return first.result.success;
321+
}
294322

295-
if (!acp.CreateElicitationResponse.isAccept(first.response)) {
296-
await this.codexClient.accountLoginCancel({loginId: loginResponse.loginId});
297-
throw RequestError.requestCancelled(
298-
{methodId: "chat-gpt-device-code", action: first.response.action},
299-
"ChatGPT device code sign-in was cancelled",
300-
);
301-
}
323+
if (!acp.CreateElicitationResponse.isAccept(first.response)) {
324+
await this.codexClient.accountLoginCancel({loginId: loginResponse.loginId});
325+
throw RequestError.requestCancelled(
326+
{methodId: "chat-gpt-device-code", action: first.response.action},
327+
"ChatGPT device code sign-in was cancelled",
328+
);
329+
}
302330

303-
const result = await loginCompletedPromise;
304-
await urlElicitationRequester.completeElicitation();
305-
return result.success;
331+
const result = await loginCompletedPromise;
332+
await urlElicitationRequester.completeElicitation();
333+
return result.success;
334+
} catch (error) {
335+
// A lost app-server ends the login: the open URL elicitation must not stay open in the client.
336+
if (this.codexClient.connectionLoss.lost) {
337+
await Promise.resolve(urlElicitationRequester.completeElicitation()).catch(() => {});
338+
}
339+
throw error;
340+
}
306341
}
307342

308343
private authenticateWithGateway(authRequest: GatewayAuthRequest): boolean {
@@ -383,6 +418,7 @@ export class CodexAcpClient {
383418

384419
async logout(): Promise<void> {
385420
const accountUpdatedPromise = this.awaitNextAccountUpdated();
421+
accountUpdatedPromise.catch(() => {});
386422
await this.codexClient.accountLogout();
387423
await accountUpdatedPromise;
388424
}
@@ -663,7 +699,10 @@ export class CodexAcpClient {
663699
}
664700
}
665701

666-
async forkSession(request: acp.ForkSessionRequest): Promise<SessionMetadata> {
702+
async forkSession(
703+
request: acp.ForkSessionRequest,
704+
releaseFailedFork: (threadId: string) => Promise<void> = threadId => this.closeSession(threadId),
705+
): Promise<SessionMetadata> {
667706
const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
668707
return await runForkSession(request, additionalDirectories, {
669708
codexClient: this.codexClient,
@@ -675,6 +714,7 @@ export class CodexAcpClient {
675714
createCurrentModelId: (models, model, reasoningEffort) =>
676715
this.createModelId(models, model, reasoningEffort).toString(),
677716
getCollaborationMode: sessionId => this.getCollaborationMode(sessionId),
717+
releaseFailedFork,
678718
});
679719
}
680720

@@ -1196,13 +1236,14 @@ export class CodexAcpClient {
11961236
method: "account/login/completed" | "account/updated",
11971237
mapEvent: (event: T) => T,
11981238
): Promise<T> {
1199-
return await new Promise((resolve) => {
1200-
let disposable: Disposable | undefined;
1239+
let disposable: Disposable | undefined;
1240+
const notified = new Promise<T>((resolve) => {
12011241
disposable = this.codexClient.connection.onNotification(method, (event: T) => {
12021242
disposable?.dispose();
12031243
resolve(mapEvent(event));
12041244
});
12051245
});
1246+
return await this.codexClient.waitWhileConnected(method, notified, () => disposable?.dispose());
12061247
}
12071248

12081249
async listMcpServers(params: ListMcpServerStatusParams): Promise<ListMcpServerStatusResponse> {

0 commit comments

Comments
 (0)