refactor(sdk): move session storage to connection-level setStorageProvider

Replace per-session sessionStore config with a connection-level
setStorageProvider() method that sets storage once for all sessions.

Changes:
- Remove sessionStore from SessionConfig, ResumeSessionConfig, and
  ListSessionsOptions types
- Add StorageProviderConfig type alias
- Add CopilotClient.setStorageProvider() method that calls
  session.setStorageProvider RPC
- Replace per-session store maps with single storageProviderConfig field
- Update createSessionStoreHandler to use connection-level config
- Rewrite E2E tests for new setStorageProvider flow

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

nodejs/src/client.ts

@@ -178,14 +178,8 @@ export class CopilotClient {
     private _rpc: ReturnType<typeof createServerRpc> | null = null;
     private processExitPromise: Promise<never> | null = null; // Rejects when CLI process exits
     private negotiatedProtocolVersion: number | null = null;
-    /** Per-session store configs, keyed by sessionId. Used to route sessionStore.* RPC requests. */
-    private sessionStoreConfigs: Map<string, SessionStoreConfig> = new Map();
-    /**
-     * Stores used during listSessions() calls. Keyed by an incrementing ID to support concurrent calls.
-     * The latest registered store is used when the server calls sessionStore.list.
-     */
-    private listSessionsStores: Map<number, SessionStoreConfig> = new Map();
-    private listSessionsStoreNextId = 0;
+    /** Connection-level storage provider config set via setStorageProvider(). */
+    private storageProviderConfig: SessionStoreConfig | null = null;
 
     /**
      * Typed server-scoped RPC methods.
@@ -351,6 +345,40 @@ export class CopilotClient {
         }
     }
 
+    /**
+     * Declare this client as the session data storage provider.
+     * Must be called before creating any sessions. Only one client can be the
+     * storage provider at a time.
+     *
+     * @param config - The storage provider configuration with callbacks for persistence
+     * @throws Error if the client is not connected and autoStart is disabled
+     *
+     * @example
+     * ```typescript
+     * await client.setStorageProvider({
+     *   descriptor: "redis://localhost/sessions",
+     *   onLoad: async (sessionId) => loadEventsFromRedis(sessionId),
+     *   onAppend: async (events, sessionId) => appendEventsToRedis(events, sessionId),
+     *   onTruncate: async (upToEventId, sessionId) => truncateEventsInRedis(upToEventId, sessionId),
+     *   onListSessions: async () => listSessionsFromRedis(),
+     *   onDelete: async (sessionId) => deleteSessionFromRedis(sessionId),
+     * });
+     * ```
+     */
+    async setStorageProvider(config: SessionStoreConfig): Promise<void> {
+        if (!this.connection) {
+            if (this.options.autoStart) {
+                await this.start();
+            } else {
+                throw new Error("Client not connected. Call start() first.");
+            }
+        }
+        await this.connection!.sendRequest("session.setStorageProvider", {
+            descriptor: config.descriptor,
+        });
+        this.storageProviderConfig = config;
+    }
+
     /**
      * Stops the CLI server and closes all active sessions.
      *
@@ -408,8 +436,7 @@ export class CopilotClient {
             }
         }
         this.sessions.clear();
-        this.sessionStoreConfigs.clear();
-        this.listSessionsStores.clear();
+        this.storageProviderConfig = null;
 
         // Close connection
         if (this.connection) {
@@ -494,8 +521,7 @@ export class CopilotClient {
 
         // Clear sessions immediately without trying to destroy them
         this.sessions.clear();
-        this.sessionStoreConfigs.clear();
-        this.listSessionsStores.clear();
+        this.storageProviderConfig = null;
 
         // Force close connection
         if (this.connection) {
@@ -603,12 +629,6 @@ export class CopilotClient {
         }
         this.sessions.set(sessionId, session);
 
-        // Register session store callbacks before the RPC so that
-        // store requests arriving during session creation are handled.
-        if (config.sessionStore) {
-            this.sessionStoreConfigs.set(sessionId, config.sessionStore);
-        }
-
         try {
             const response = await this.connection!.sendRequest("session.create", {
                 ...(await getTraceContext(this.onGetTraceContext)),
@@ -640,9 +660,6 @@ export class CopilotClient {
                 skillDirectories: config.skillDirectories,
                 disabledSkills: config.disabledSkills,
                 infiniteSessions: config.infiniteSessions,
-                sessionStore: config.sessionStore
-                    ? { descriptor: config.sessionStore.descriptor }
-                    : undefined,
             });
 
             const { workspacePath } = response as {
@@ -652,7 +669,6 @@ export class CopilotClient {
             session["_workspacePath"] = workspacePath;
         } catch (e) {
             this.sessions.delete(sessionId);
-            this.sessionStoreConfigs.delete(sessionId);
             throw e;
         }
 
@@ -719,11 +735,6 @@ export class CopilotClient {
         }
         this.sessions.set(sessionId, session);
 
-        // Register session store callbacks before the RPC
-        if (config.sessionStore) {
-            this.sessionStoreConfigs.set(sessionId, config.sessionStore);
-        }
-
         try {
             const response = await this.connection!.sendRequest("session.resume", {
                 ...(await getTraceContext(this.onGetTraceContext)),
@@ -756,9 +767,6 @@ export class CopilotClient {
                 disabledSkills: config.disabledSkills,
                 infiniteSessions: config.infiniteSessions,
                 disableResume: config.disableResume,
-                sessionStore: config.sessionStore
-                    ? { descriptor: config.sessionStore.descriptor }
-                    : undefined,
             });
 
             const { workspacePath } = response as {
@@ -768,7 +776,6 @@ export class CopilotClient {
             session["_workspacePath"] = workspacePath;
         } catch (e) {
             this.sessions.delete(sessionId);
-            this.sessionStoreConfigs.delete(sessionId);
             throw e;
         }
 
@@ -985,7 +992,6 @@ export class CopilotClient {
 
         // Remove from local sessions map if present
         this.sessions.delete(sessionId);
-        this.sessionStoreConfigs.delete(sessionId);
     }
 
     /**
@@ -1008,50 +1014,34 @@ export class CopilotClient {
 
         // Support both plain filter and full options object
         const options: ListSessionsOptions | undefined =
-            filterOrOptions && "sessionStore" in filterOrOptions
+            filterOrOptions && "filter" in filterOrOptions
                 ? (filterOrOptions as ListSessionsOptions)
                 : filterOrOptions
                   ? { filter: filterOrOptions as SessionListFilter }
                   : undefined;
 
-        // Register the store for the duration of this RPC call (supports concurrent calls)
-        let storeId: number | undefined;
-        if (options?.sessionStore) {
-            storeId = this.listSessionsStoreNextId++;
-            this.listSessionsStores.set(storeId, options.sessionStore);
-        }
-
-        try {
-            const response = await this.connection.sendRequest("session.list", {
-                filter: options?.filter,
-                sessionStore: options?.sessionStore
-                    ? { descriptor: options.sessionStore.descriptor }
-                    : undefined,
-            });
-            const { sessions } = response as {
-                sessions: Array<{
-                    sessionId: string;
-                    startTime: string;
-                    modifiedTime: string;
-                    summary?: string;
-                    isRemote: boolean;
-                    context?: SessionContext;
-                }>;
-            };
+        const response = await this.connection.sendRequest("session.list", {
+            filter: options?.filter,
+        });
+        const { sessions } = response as {
+            sessions: Array<{
+                sessionId: string;
+                startTime: string;
+                modifiedTime: string;
+                summary?: string;
+                isRemote: boolean;
+                context?: SessionContext;
+            }>;
+        };
 
-            return sessions.map((s) => ({
-                sessionId: s.sessionId,
-                startTime: new Date(s.startTime),
-                modifiedTime: new Date(s.modifiedTime),
-                summary: s.summary,
-                isRemote: s.isRemote,
-                context: s.context,
-            }));
-        } finally {
-            if (storeId !== undefined) {
-                this.listSessionsStores.delete(storeId);
-            }
-        }
+        return sessions.map((s) => ({
+            sessionId: s.sessionId,
+            startTime: new Date(s.startTime),
+            modifiedTime: new Date(s.modifiedTime),
+            summary: s.summary,
+            isRemote: s.isRemote,
+            context: s.context,
+        }));
     }
 
     /**
@@ -1533,43 +1523,38 @@ export class CopilotClient {
 
     /**
      * Create a {@link SessionStoreHandler} that routes each RPC call to the
-     * appropriate {@link SessionStoreConfig} registered for the given session.
+     * connection-level storage provider set via {@link setStorageProvider}.
      */
     private createSessionStoreHandler(): SessionStoreHandler {
-        const getStore = (sessionId: string): SessionStoreConfig => {
-            const store = this.sessionStoreConfigs.get(sessionId);
-            if (!store) {
-                throw new Error(`No session store registered for session ${sessionId}`);
+        const getStore = (): SessionStoreConfig => {
+            if (!this.storageProviderConfig) {
+                throw new Error("No storage provider configured. Call setStorageProvider() first.");
             }
-            return store;
+            return this.storageProviderConfig;
         };
 
         return {
             load: async (params) => {
-                const store = getStore(params.sessionId);
+                const store = getStore();
                 const events = await store.onLoad(params.sessionId);
                 // Events are opaque on the wire but typed in the SDK consumer API
                 return { events: events as Record<string, unknown>[] };
             },
             append: async (params) => {
-                const store = getStore(params.sessionId);
+                const store = getStore();
                 await store.onAppend(params.events as SessionEvent[], params.sessionId);
             },
             truncate: async (params) => {
-                const store = getStore(params.sessionId);
+                const store = getStore();
                 return store.onTruncate(params.upToEventId, params.sessionId);
             },
             list: async () => {
-                // Use the most recently registered store for listing.
-                const store = Array.from(this.listSessionsStores.values()).pop();
-                if (!store) {
-                    throw new Error("No session store registered for listing");
-                }
+                const store = getStore();
                 const sessions = await store.onListSessions();
                 return { sessions };
             },
             delete: async (params) => {
-                const store = getStore(params.sessionId);
+                const store = getStore();
                 await store.onDelete(params.sessionId);
             },
         };

nodejs/src/index.ts

@@ -45,6 +45,7 @@ export type {
     SessionMetadata,
     SessionStoreConfig,
     SessionStoreHandler,
+    StorageProviderConfig,
     ClientApiHandlers,
     SystemMessageAppendConfig,
     SystemMessageConfig,

nodejs/src/types.ts

@@ -857,15 +857,6 @@ export interface SessionConfig {
      * but executes earlier in the lifecycle so no events are missed.
      */
     onEvent?: SessionEventHandler;
-
-    /**
-     * Session event store callbacks. When provided, the client handles all
-     * event persistence instead of the server's default file-based storage.
-     *
-     * The server calls back into these callbacks over RPC whenever it needs
-     * to load, append, truncate, list, or delete session events.
-     */
-    sessionStore?: SessionStoreConfig;
 }
 
 /**
@@ -894,8 +885,7 @@ export type ResumeSessionConfig = Pick<
     | "disabledSkills"
     | "infiniteSessions"
     | "onEvent"
-    | "sessionStore"
-> & {
+>& {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.
@@ -1046,9 +1036,7 @@ export interface SessionContext {
 export interface SessionStoreConfig {
     /**
      * Opaque descriptor identifying this storage backend.
-     * Used for UI display (e.g., `"redis://localhost/sessions"`) and to verify
-     * resume-consistency — two stores are considered equivalent if and only if
-     * their descriptors are identical strings.
+     * Used for UI display (e.g., `"redis://localhost/sessions"`).
      */
     descriptor: string;
 
@@ -1074,15 +1062,20 @@ export interface SessionStoreConfig {
 }
 
 /**
- * Options for listing sessions, optionally with a session store.
+ * Options for listing sessions.
  */
 export interface ListSessionsOptions {
     /** Filter to narrow down which sessions to return. */
     filter?: SessionListFilter;
-    /** When provided, list sessions from this store instead of the server's default. */
-    sessionStore?: SessionStoreConfig;
 }
 
+/**
+ * Configuration for becoming the session data storage provider.
+ * Same shape as SessionStoreConfig — call client.setStorageProvider(config)
+ * to claim storage before creating sessions.
+ */
+export type StorageProviderConfig = SessionStoreConfig;
+
 /**
  * Filter options for listing sessions
  */