Session List

• Author(s): @ahmedhesham6
• Champion: @benbrandt

​

Elevator pitch

​

Status quo

1. Discover existing sessions - Clients cannot query what sessions exist on an agent
2. Display session history - Users cannot see a list of their past conversations
3. Manage multiple sessions - Switching between sessions requires clients to track session IDs themselves
4. Clean up old sessions - No way to discover stale or abandoned sessions for cleanup

• Poor user experience - Users cannot browse their conversation history or resume previous sessions easily
• Client-side complexity - Each client must implement its own session tracking and persistence
• Inconsistent behavior - Different clients handle session management differently, leading to fragmented experiences

• Requires persistent storage on the client side
• Can get out of sync if sessions are created/destroyed outside the client
• Doesn’t work across different client instances or devices
• Cannot leverage agent-side session metadata or state

​

What we propose to do about it

1. Return a list of sessions with essential metadata:
   • sessionId - Unique identifier
   • createdAt - Timestamp when session was created
   • updatedAt - Timestamp of last update to the session
   • cwd - Working directory for the session
   • title - Optional human-readable title (could be auto-generated from first prompt)
   • _meta - Optional agent-specific metadata
2. Support filtering and pagination:
   • Filter by creation date, last accessed date, or working directory
   • Limit the number of results returned
   • Search by title or agent-provided metadata
3. Be an optional capability:
   • Agents advertise listSessions: true in initialization if they support this feature
   • Clients check for this capability before attempting to call session/list
   • Agents without persistent session storage don’t need to implement this

​

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "createdAfter": "2025-10-20T00:00:00Z",
    "limit": 20,
    "cursor": "eyJwYWdlIjogMn0=",
    "search": "auth"
  }
}

​

Request Parameters

• cwd (string) - Filter sessions by working directory
• createdAfter (string) - ISO 8601 timestamp, only return sessions created after this time
• createdBefore (string) - ISO 8601 timestamp, only return sessions created before this time
• updatedAfter (string) - ISO 8601 timestamp, only return sessions updated after this time
• limit (number) - Maximum number of results to return (default: 50, max: 1000)
• cursor (string) - Opaque cursor token from a previous response’s nextCursor field for cursor-based pagination
• search (string) - Free-text search across titles or agent metadata

​

Minimal Request Example

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {}
}

​

JSON-RPC Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123def456",
        "createdAt": "2025-10-29T10:30:00Z",
        "updatedAt": "2025-10-29T14:22:15Z",
        "cwd": "/home/user/project",
        "title": "Implement session list API",
        "_meta": {
          "messageCount": 12,
          "hasErrors": false
        }
      },
      {
        "sessionId": "sess_xyz789ghi012",
        "createdAt": "2025-10-28T09:15:00Z",
        "updatedAt": "2025-10-28T16:45:30Z",
        "cwd": "/home/user/another-project",
        "title": "Debug authentication flow"
      },
      {
        "sessionId": "sess_uvw345rst678",
        "createdAt": "2025-10-27T14:00:00Z",
        "updatedAt": "2025-10-27T15:30:00Z",
        "cwd": "/home/user/project"
      }
    ],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

​

Response Fields

• sessions (array) - Array of session information objects
• nextCursor (string, optional) - Opaque cursor token. If present, pass this in the next request’s cursor parameter to fetch the next page. If absent, there are no more results.

• sessionId (string, required) - Unique identifier for the session
• createdAt (string, required) - ISO 8601 timestamp when session was created
• updatedAt (string, required) - ISO 8601 timestamp of last activity
• cwd (string, required) - Working directory for the session
• title (string, optional) - Human-readable title (may be auto-generated from first prompt)
• _meta (object, optional) - Agent-specific metadata (e.g., message count, error status, tags)

​

Empty Result Example

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": []
  }
}

​

Shiny future

1. Clients can build session browsers - Users can view a list of all their conversations, sorted by recency or relevance
2. Session switching becomes seamless - Users can easily switch between ongoing conversations
3. Better resource management - Clients can identify and clean up old or inactive sessions
4. Cross-device continuity - Users could potentially access their sessions from different devices (if agent supports it)
5. Improved UX patterns:
   • “Recent conversations” sidebar
   • Search through past sessions
   • Archive/delete old sessions
   • Resume interrupted work easily

• Better visibility into active sessions
• Opportunity to implement session lifecycle policies
• Foundation for future features like session sharing or collaboration

​

Implementation details and plan

​

Phase 1: Core Protocol Changes

1. Update schema.json to add:
   • session/list method definition
   • ListSessionsRequest and ListSessionsResponse types
   • SessionInfo type
   • listSessions capability flag
2. Update protocol documentation in /docs/protocol/session-setup.mdx:
   • Document the new endpoint
   • Explain when to use it vs. maintaining client-side session tracking
   • Provide examples of common use cases

​

Phase 2: Reference Implementation

3. Implement in Rust SDK (rust/agent.rs and rust/client.rs):
   • Add list_sessions method to agent trait
   • Provide default implementation (empty list) for agents without persistence
   • Add client method to call session/list
4. Add to TypeScript SDKs (if applicable):
   • Update TypeScript types
   • Add client methods

​

Phase 3: Example Implementation

5. Create example agent that demonstrates:
   • In-memory session registry
   • Automatic title generation from first prompt
   • Session lifecycle management (cleanup after N days)
   • Pagination and filtering

​

Compatibility Considerations

• Backward compatible: Existing agents continue working without implementing this
• Capability-based: Clients check for listSessions capability before using
• No breaking changes: No modifications to existing endpoints

​

Security Considerations

• Session isolation: Agents must ensure sessions are only listed for the authenticated client
• Resource limits: Agents should enforce reasonable limits on pagination to prevent abuse

​

Frequently asked questions

​

What alternative approaches did you consider, and why did you settle on this one?

1. Client-side session tracking only - This is the current approach, but it has limitations:
   • Doesn’t work across devices
   • Can get out of sync
   • Adds complexity to every client implementation
2. Session events/notifications - Push notifications when sessions are created/destroyed:
   • More complex to implement
   • Requires long-lived connections
   • Still requires client-side state management
   • Better suited as a future enhancement, not a replacement
3. File-based session manifest - Agent writes session list to a file that clients read:
   • Couples agent and client file system access
   • Doesn’t work for remote agents
   • No standard format

• Consistent with existing protocol design - Uses same RPC patterns as other endpoints
• Flexible - Supports filtering, pagination, and agent-specific metadata
• Optional - Agents can opt-in based on their architecture
• Simple - Single request/response pattern, easy to implement and use

​

Why not make this mandatory for all agents?

• Allows simple, stateless agents to remain compliant
• Reduces implementation burden
• Lets agents evolve session management over time

​

How does this interact with session/load?

1. Client calls session/list to get available sessions
2. User selects a session
3. Client calls session/load with the chosen sessionId

​

Should we include session content in the list response?

• Performance - Full conversation history could be large
• Privacy - Listing sessions might be less sensitive than exposing full content
• Separation of concerns - Use session/load to get full session content

​

What about session deletion?

​

How should pagination work for large session lists?

• Request includes limit and optional cursor
• Response includes nextCursor when more results are available
• Clients should treat a missing nextCursor as the end of results
• Clients MUST treat cursors as opaque tokens: don’t parse, modify, or persist them across sessions
• The cursor MUST be a string; never send a raw JSON object as the cursor
• Servers SHOULD provide stable cursors and handle invalid cursors gracefully

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "createdAfter": "2025-10-20T00:00:00Z",
    "limit": 20,
    "cursor": "eyJwYWdlIjogMn0=",
    "search": "auth"
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      /* ... */
    ],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

​

Revision history

• 2025-10-29: Initial draft proposal
• 2025-10-30: Update to use _meta field for agent-specific metadata
• 2025-10-30: Switch from offset-based to cursor-based pagination using continuation tokens
• 2025-10-30: Rename lastAccessedAt to updatedAt for consistency
• 2025-10-30: Remove preview field from SessionInfo (out of scope)
• 2025-10-30: Remove session orphaning from problem statement
• 2025-10-30: Replace sortBy/sortOrder with search parameter; remove total count from response
• 2025-10-31: Update pagination: continuationToken → cursor, nextContinuationToken → nextCursor, remove hasMore