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";
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 { isArchivedRolloutPath } from "./SessionIndexMutations" ;
1920import { 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`. */
5556export 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. */
58111export 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 */
601658export 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`. */
616673export 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