feat: Add agent_users table to associate sessions with users

[ecanlar]

Summary

• Introduces an agent_users table across all SQL-based session backends (SQLiteSession, AsyncSQLiteSession, SQLAlchemySession) to associate sessions with application-level users
• Adds optional user_id parameter to session constructors and a get_sessions_for_user() query method
• Mirrors the User → Session relationship pattern from Google's ADK, enabling multi-user agent applications without custom mapping layers

Motivation

Currently sessions exist independently with no built-in way to link them to users. Every developer building multi-user applications ends up creating their own user-session mapping layer on top of the SDK. This PR adds first-class support for this common pattern.

Changes

Schema

-- New table
CREATE TABLE agent_users (
    user_id TEXT PRIMARY KEY,
    metadata TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- New column on agent_sessions
ALTER TABLE agent_sessions ADD COLUMN user_id TEXT REFERENCES agent_users(user_id) ON DELETE SET NULL;
CREATE INDEX idx_agent_sessions_user_id ON agent_sessions (user_id);

API

# Create a session linked to a user
session = SQLiteSession("session-1", db_path="./data.db", user_id="alice")

# Retrieve all sessions for a user
session_ids = await session.get_sessions_for_user("alice")

Files modified

File	Change
src/agents/memory/session.py	Add user_id attribute to Session protocol and SessionABC
src/agents/memory/sqlite_session.py	Add agent_users table, user_id FK, get_sessions_for_user()
src/agents/extensions/memory/async_sqlite_session.py	Same changes for async SQLite backend
src/agents/extensions/memory/sqlalchemy_session.py	Same changes for SQLAlchemy backend
tests/test_session.py	Add tests for user association and user_id attribute

Test plan

• All 34 existing session tests pass (backward compatible — user_id defaults to None)
• New test_sqlite_session_user_association — verifies multi-user session queries
• New test_sqlite_session_user_id_attribute — verifies user_id is stored on instance

Closes #2808

[seratch]

For the reason I mentioned at #2808 (comment), we don't plan to have this change at least for now.