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).

Implemented in all SDK clients:
- Node.js
- Python
- Go
- .NET

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

dotnet/src/Client.cs

@@ -613,6 +613,7 @@ public async Task DeleteSessionAsync(string sessionId, CancellationToken cancell
     /// <summary>
     /// Lists all sessions known to the Copilot server.
     /// </summary>
+    /// <param name="filter">Optional filter to narrow down the session list by cwd, git root, repository, or branch.</param>
     /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the operation.</param>
     /// <returns>A task that resolves with a list of <see cref="SessionMetadata"/> for all available sessions.</returns>
     /// <exception cref="InvalidOperationException">Thrown when the client is not connected.</exception>
@@ -625,12 +626,12 @@ public async Task DeleteSessionAsync(string sessionId, CancellationToken cancell
     /// }
     /// </code>
     /// </example>
-    public async Task<List<SessionMetadata>> ListSessionsAsync(CancellationToken cancellationToken = default)
+    public async Task<List<SessionMetadata>> ListSessionsAsync(SessionListFilter? filter = null, CancellationToken cancellationToken = default)
     {
         var connection = await EnsureConnectedAsync(cancellationToken);
 
         var response = await InvokeRpcAsync<ListSessionsResponse>(
-            connection.Rpc, "session.list", [], cancellationToken);
+            connection.Rpc, "session.list", [new ListSessionsRequest(filter)], cancellationToken);
 
         return response.Sessions;
     }
@@ -1149,6 +1150,9 @@ internal record DeleteSessionResponse(
         bool Success,
         string? Error);
 
+    internal record ListSessionsRequest(
+        SessionListFilter? Filter);
+
     internal record ListSessionsResponse(
         List<SessionMetadata> Sessions);
 
@@ -1218,6 +1222,7 @@ public override void WriteLine(string? message) =>
     [JsonSerializable(typeof(DeleteSessionResponse))]
     [JsonSerializable(typeof(GetLastSessionIdResponse))]
     [JsonSerializable(typeof(HooksInvokeResponse))]
+    [JsonSerializable(typeof(ListSessionsRequest))]
     [JsonSerializable(typeof(ListSessionsResponse))]
     [JsonSerializable(typeof(PermissionRequestResponse))]
     [JsonSerializable(typeof(PermissionRequestResult))]

dotnet/src/Types.cs

@@ -832,13 +832,45 @@ public class MessageOptions
 
 public delegate void SessionEventHandler(SessionEvent sessionEvent);
 
+/// <summary>
+/// Working directory context for a session.
+/// </summary>
+public class SessionContext
+{
+    /// <summary>Working directory where the session was created.</summary>
+    public string Cwd { get; set; } = string.Empty;
+    /// <summary>Git repository root (if in a git repo).</summary>
+    public string? GitRoot { get; set; }
+    /// <summary>GitHub repository in "owner/repo" format.</summary>
+    public string? Repository { get; set; }
+    /// <summary>Current git branch.</summary>
+    public string? Branch { get; set; }
+}
+
+/// <summary>
+/// Filter options for listing sessions.
+/// </summary>
+public class SessionListFilter
+{
+    /// <summary>Filter by exact cwd match.</summary>
+    public string? Cwd { get; set; }
+    /// <summary>Filter by git root.</summary>
+    public string? GitRoot { get; set; }
+    /// <summary>Filter by repository (owner/repo format).</summary>
+    public string? Repository { get; set; }
+    /// <summary>Filter by branch.</summary>
+    public string? Branch { get; set; }
+}
+
 public class SessionMetadata
 {
     public string SessionId { get; set; } = string.Empty;
     public DateTime StartTime { get; set; }
     public DateTime ModifiedTime { get; set; }
     public string? Summary { get; set; }
     public bool IsRemote { get; set; }
+    /// <summary>Working directory context (cwd, git info) from session creation.</summary>
+    public SessionContext? Context { get; set; }
 }
 
 internal class PingRequest
@@ -1025,6 +1057,8 @@ public class GetModelsResponse
 [JsonSerializable(typeof(PingRequest))]
 [JsonSerializable(typeof(PingResponse))]
 [JsonSerializable(typeof(ProviderConfig))]
+[JsonSerializable(typeof(SessionContext))]
+[JsonSerializable(typeof(SessionListFilter))]
 [JsonSerializable(typeof(SessionMetadata))]
 [JsonSerializable(typeof(SystemMessageConfig))]
 [JsonSerializable(typeof(ToolBinaryResult))]

go/README.md

@@ -80,7 +80,7 @@ func main() {
 - `CreateSession(config *SessionConfig) (*Session, error)` - Create a new session
 - `ResumeSession(sessionID string) (*Session, error)` - Resume an existing session
 - `ResumeSessionWithOptions(sessionID string, config *ResumeSessionConfig) (*Session, error)` - Resume with additional configuration
-- `ListSessions() ([]SessionMetadata, error)` - List all sessions known to the server
+- `ListSessions(filter *SessionListFilter) ([]SessionMetadata, error)` - List sessions (with optional filter)
 - `DeleteSession(sessionID string) error` - Delete a session permanently
 - `GetState() ConnectionState` - Get connection state
 - `Ping(message string) (*PingResponse, error)` - Ping the server

go/client.go

@@ -791,18 +791,24 @@ func (c *Client) ResumeSessionWithOptions(sessionID string, config *ResumeSessio
 // ListSessions returns metadata about all sessions known to the server.
 //
 // Returns a list of SessionMetadata for all available sessions, including their IDs,
-// timestamps, and optional summaries.
+// timestamps, optional summaries, and context information.
+//
+// An optional filter can be provided to filter sessions by cwd, git root, repository, or branch.
 //
 // Example:
 //
-//	sessions, err := client.ListSessions()
+//	sessions, err := client.ListSessions(nil)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //	for _, session := range sessions {
 //	    fmt.Printf("Session: %s\n", session.SessionID)
 //	}
-func (c *Client) ListSessions() ([]SessionMetadata, error) {
+//
+// Example with filter:
+//
+//	sessions, err := client.ListSessions(&SessionListFilter{Repository: "owner/repo"})
+func (c *Client) ListSessions(filter *SessionListFilter) ([]SessionMetadata, error) {
 	if c.client == nil {
 		if c.autoStart {
 			if err := c.Start(); err != nil {
@@ -813,7 +819,11 @@ func (c *Client) ListSessions() ([]SessionMetadata, error) {
 		}
 	}
 
-	result, err := c.client.Request("session.list", map[string]interface{}{})
+	params := map[string]interface{}{}
+	if filter != nil {
+		params["filter"] = filter
+	}
+	result, err := c.client.Request("session.list", params)
 	if err != nil {
 		return nil, err
 	}

go/e2e/session_test.go

@@ -779,7 +779,7 @@ func TestSession(t *testing.T) {
 		time.Sleep(200 * time.Millisecond)
 
 		// List sessions and verify they're included
-		sessions, err := client.ListSessions()
+		sessions, err := client.ListSessions(nil)
 		if err != nil {
 			t.Fatalf("Failed to list sessions: %v", err)
 		}
@@ -838,7 +838,7 @@ func TestSession(t *testing.T) {
 		time.Sleep(200 * time.Millisecond)
 
 		// Verify session exists in the list
-		sessions, err := client.ListSessions()
+		sessions, err := client.ListSessions(nil)
 		if err != nil {
 			t.Fatalf("Failed to list sessions: %v", err)
 		}
@@ -859,7 +859,7 @@ func TestSession(t *testing.T) {
 		}
 
 		// Verify session no longer exists in the list
-		sessionsAfter, err := client.ListSessions()
+		sessionsAfter, err := client.ListSessions(nil)
 		if err != nil {
 			t.Fatalf("Failed to list sessions after delete: %v", err)
 		}

go/types.go

@@ -552,13 +552,38 @@ type GetModelsResponse struct {
 	Models []ModelInfo `json:"models"`
 }
 
+// SessionContext contains working directory context for a session
+type SessionContext struct {
+	// Cwd is the working directory where the session was created
+	Cwd string `json:"cwd"`
+	// GitRoot is the git repository root (if in a git repo)
+	GitRoot string `json:"gitRoot,omitempty"`
+	// Repository is the GitHub repository in "owner/repo" format
+	Repository string `json:"repository,omitempty"`
+	// Branch is the current git branch
+	Branch string `json:"branch,omitempty"`
+}
+
+// SessionListFilter contains filter options for listing sessions
+type SessionListFilter struct {
+	// Cwd filters by exact working directory match
+	Cwd string `json:"cwd,omitempty"`
+	// GitRoot filters by git root
+	GitRoot string `json:"gitRoot,omitempty"`
+	// Repository filters by repository (owner/repo format)
+	Repository string `json:"repository,omitempty"`
+	// Branch filters by branch
+	Branch string `json:"branch,omitempty"`
+}
+
 // SessionMetadata contains metadata about a session
 type SessionMetadata struct {
-	SessionID    string  `json:"sessionId"`
-	StartTime    string  `json:"startTime"`
-	ModifiedTime string  `json:"modifiedTime"`
-	Summary      *string `json:"summary,omitempty"`
-	IsRemote     bool    `json:"isRemote"`
+	SessionID    string          `json:"sessionId"`
+	StartTime    string          `json:"startTime"`
+	ModifiedTime string          `json:"modifiedTime"`
+	Summary      *string         `json:"summary,omitempty"`
+	IsRemote     bool            `json:"isRemote"`
+	Context      *SessionContext `json:"context,omitempty"`
 }
 
 // ListSessionsResponse is the response from session.list

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,
         }));
     }