Expose session context in listSessions and add filtering

Adds SessionContext to SessionMetadata so SDK consumers can see the
working directory and repository information for each session.

Also adds optional filter parameter to listSessions() for filtering
by context fields (cwd, gitRoot, repository, branch).

Fixes #413
Fixes #200

Author: jmoseley

cookbook/nodejs/multiple-sessions.md

@@ -63,6 +63,11 @@ console.log(session.sessionId); // "user-123-chat"
 const sessions = await client.listSessions();
 console.log(sessions);
 // [{ sessionId: "user-123-chat", ... }, ...]
+
+// Sessions include context (cwd, git info) from when they were created
+for (const s of sessions) {
+    console.log(`${s.sessionId} - ${s.context?.cwd ?? "unknown"}`);
+}
 ```
 
 ## Deleting sessions

cookbook/nodejs/persisting-sessions.md

@@ -64,6 +64,16 @@ console.log(sessions);
 //   { sessionId: "user-123-conversation", ... },
 //   { sessionId: "user-456-conversation", ... },
 // ]
+
+// Each session includes context from when it was created
+for (const session of sessions) {
+    console.log(`Session: ${session.sessionId}`);
+    if (session.context) {
+        console.log(`  Directory: ${session.context.cwd}`);
+        console.log(`  Repository: ${session.context.repository}`);
+        console.log(`  Branch: ${session.context.branch}`);
+    }
+}
 ```
 
 ### Deleting a session permanently

nodejs/README.md

@@ -111,6 +111,22 @@ Get current connection state.
 
 List all available sessions.
 
+**SessionMetadata:**
+
+- `sessionId: string` - Unique session identifier
+- `startTime: Date` - When the session was created
+- `modifiedTime: Date` - When the session was last modified
+- `summary?: string` - Optional session summary
+- `isRemote: boolean` - Whether the session is remote
+- `context?: SessionContext` - Working directory context from session creation
+
+**SessionContext:**
+
+- `cwd: string` - Working directory where the session was created
+- `gitRoot?: string` - Git repository root (if in a git repo)
+- `repository?: string` - GitHub repository in "owner/repo" format
+- `branch?: string` - Current git branch
+
 ##### `deleteSession(sessionId: string): Promise<void>`
 
 Delete a session and its data from disk.

nodejs/src/client.ts

@@ -30,6 +30,7 @@ import type {
     ResumeSessionConfig,
     SessionConfig,
     SessionEvent,
+    SessionListFilter,
     SessionMetadata,
     Tool,
     ToolCallRequestPayload,
@@ -749,19 +750,25 @@ export class CopilotClient {
      * }
      * ```
      */
-    async listSessions(): Promise<SessionMetadata[]> {
+    async listSessions(filter?: SessionListFilter): Promise<SessionMetadata[]> {
         if (!this.connection) {
             throw new Error("Client not connected");
         }
 
-        const response = await this.connection.sendRequest("session.list", {});
+        const response = await this.connection.sendRequest("session.list", { filter });
         const { sessions } = response as {
             sessions: Array<{
                 sessionId: string;
                 startTime: string;
                 modifiedTime: string;
                 summary?: string;
                 isRemote: boolean;
+                context?: {
+                    cwd: string;
+                    gitRoot?: string;
+                    repository?: string;
+                    branch?: string;
+                };
             }>;
         };
 
@@ -771,6 +778,7 @@ export class CopilotClient {
             modifiedTime: new Date(s.modifiedTime),
             summary: s.summary,
             isRemote: s.isRemote,
+            context: s.context,
         }));
     }
 

nodejs/src/index.ts

@@ -35,6 +35,7 @@ export type {
     SessionEventHandler,
     SessionEventPayload,
     SessionEventType,
+    SessionListFilter,
     SessionMetadata,
     SystemMessageAppendConfig,
     SystemMessageConfig,

nodejs/src/types.ts

@@ -833,6 +833,34 @@ export type SessionEventHandler = (event: SessionEvent) => void;
  */
 export type ConnectionState = "disconnected" | "connecting" | "connected" | "error";
 
+/**
+ * Working directory context for a session
+ */
+export interface SessionContext {
+    /** Working directory where the session was created */
+    cwd: string;
+    /** Git repository root (if in a git repo) */
+    gitRoot?: string;
+    /** GitHub repository in "owner/repo" format */
+    repository?: string;
+    /** Current git branch */
+    branch?: string;
+}
+
+/**
+ * Filter options for listing sessions
+ */
+export interface SessionListFilter {
+    /** Filter by exact cwd match */
+    cwd?: string;
+    /** Filter by git root */
+    gitRoot?: string;
+    /** Filter by repository (owner/repo format) */
+    repository?: string;
+    /** Filter by branch */
+    branch?: string;
+}
+
 /**
  * Metadata about a session
  */
@@ -842,6 +870,8 @@ export interface SessionMetadata {
     modifiedTime: Date;
     summary?: string;
     isRemote: boolean;
+    /** Working directory context (cwd, git info) from session creation */
+    context?: SessionContext;
 }
 
 /**

nodejs/test/e2e/session.test.ts

@@ -22,6 +22,31 @@ describe("Sessions", async () => {
         await expect(() => session.getMessages()).rejects.toThrow(/Session not found/);
     });
 
+    it("should list sessions with context field", async () => {
+        // Create a new session
+        const session = await client.createSession();
+        expect(session.sessionId).toMatch(/^[a-f0-9-]+$/);
+
+        // List sessions and find the one we just created
+        const sessions = await client.listSessions();
+        const ourSession = sessions.find((s) => s.sessionId === session.sessionId);
+
+        expect(ourSession).toBeDefined();
+        expect(ourSession?.context).toBeDefined();
+        // cwd should be set to some path
+        expect(ourSession?.context?.cwd).toMatch(/^(\/|[A-Za-z]:)/);
+        // gitRoot, repository, and branch are optional
+        if (ourSession?.context?.gitRoot) {
+            expect(typeof ourSession.context.gitRoot).toBe("string");
+        }
+        if (ourSession?.context?.repository) {
+            expect(typeof ourSession.context.repository).toBe("string");
+        }
+        if (ourSession?.context?.branch) {
+            expect(typeof ourSession.context.branch).toBe("string");
+        }
+    });
+
     it("should have stateful conversation", async () => {
         const session = await client.createSession();
         const assistantMessage = await session.sendAndWait({ prompt: "What is 1+1?" });