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";
1314import { z } from "zod" ;
1415import type { ServerNotification } from "./app-server" ;
1516import 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" ;
1718import { listedSessionTitle } from "./SessionTitle" ;
1819import { 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`. */
4748export 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. */
50103export 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 */
560617export 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 ,
0 commit comments