Add encryption support using cryptography to Sessions implementation

[maxmekiska]

EncryptedSession

This PR adds EncryptedSession, a wrapper that provides transparent encryption for any session implementation with TTL-based message expiration.

Key Features

• Per session key derivation: Uses HKDF with session ID as salt for cryptographic isolation.
• TTL-based expiration: Messages automatically expire and are silently skipped during retrieval.
• Transparent encryption: Drop in wrapper for existing sessions (SQLiteSession, SQLAlchemySession).
• Auto-retry pop: pop_item() automatically skips expired items to find valid ones.

Usage

from agents.extensions.memory import EncryptedSession
from agents.extensions.memory import SQLiteSession

# Wrap any existing session
session = EncryptedSession(
    session_id="user-123",
    underlying_session=SQLiteSession("user-123"),
    encryption_key="your-key",
    ttl=600
)

await Runner.run(agent, "Hello", session=session)

Implementation Details

• Uses Fernet encryption with per-message TTL validation.
• Conversation history remains fully functional while being stored encrypted, with automatic expiration of old messages.

[edmondtam1]

Brilliant!

[seratch]

@rm-openai Overall, this enhancement looks good to me (except the env name). Do you have any suggestions or concerns?

[rm-openai]

@codex review

[chatgpt-codex-connector]

Codex Review: Here are some suggestions.

Reply with @codex fix comments to fix any unresolved comments.

About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you open a pull request for review, mark a draft as ready, or comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex fix this CI failure" or "@codex address that feedback".

[maxmekiska]

@rm-openai Overall, this enhancement looks good to me (except the env name). Do you have any suggestions or concerns?

Thanks for the review! I removed the environment variable logic and left it up to the user to decide how to provide the encryption key.

[maxmekiska]

Update

I believe I've resolved the CI issue. The problem was that cryptography wasn't properly included in the uv.lock file when UV_FROZEN=1 was set, causing import failures in tests and type checking.

Solution

1. Added cryptography to the lock file via uv add --optional encrypt cryptography
2. Removed the redundant types-cryptography dependency (cryptography ships with built-in types since v3.4+)
3. Updated the lock file to include the missing dependency for the CI environment

The CI should now pass since UV_FROZEN=1 will use the updated lock file that includes cryptography.

[maxmekiska]

Cleaned commit history.

[seratch]

Can you fix the following error with Python 3.9?

2025-09-12T06:36:50.3297600Z ==================================== ERRORS ====================================
2025-09-12T06:36:50.3298323Z _______ ERROR collecting tests/extensions/memory/test_encrypt_session.py _______
2025-09-12T06:36:50.3299644Z ImportError while importing test module '/home/runner/work/openai-agents-python/openai-agents-python/tests/extensions/memory/test_encrypt_session.py'.
2025-09-12T06:36:50.3301101Z Hint: make sure your test modules/packages have valid Python names.
2025-09-12T06:36:50.3301588Z Traceback:
2025-09-12T06:36:50.3302231Z ../../../.local/share/uv/python/cpython-3.9.23-linux-x86_64-gnu/lib/python3.9/importlib/__init__.py:127: in import_module
2025-09-12T06:36:50.3303105Z     return _bootstrap._gcd_import(name[level:], package, level)
2025-09-12T06:36:50.3303726Z tests/extensions/memory/test_encrypt_session.py:14: in <module>
2025-09-12T06:36:50.3304409Z     from agents.extensions.memory.encrypt_session import EncryptedSession
2025-09-12T06:36:50.3305079Z src/agents/extensions/memory/encrypt_session.py:32: in <module>
2025-09-12T06:36:50.3305659Z     from typing import Any, Literal, TypedDict, TypeGuard, cast
2025-09-12T06:36:50.3306632Z E   ImportError: cannot import name 'TypeGuard' from 'typing' (/home/runner/.local/share/uv/python/cpython-3.9.23-linux-x86_64-gnu/lib/python3.9/typing.py)
2025-09-12T06:36:50.3307570Z =========================== short test summary info ============================
2025-09-12T06:36:50.3308049Z ERROR tests/extensions/memory/test_encrypt_session.py
2025-09-12T06:36:50.3308558Z !!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
2025-09-12T06:36:50.3309031Z =============================== 1 error in 4.59s ===============================
2025-09-12T06:36:50.6243452Z make: *** [Makefile:44: old_version_tests] Error 2
2025-09-12T06:36:50.6259143Z ##[error]Process completed with exit code 2.

[maxmekiska]

Can you fix the following error with Python 3.9?

2025-09-12T06:36:50.3297600Z ==================================== ERRORS ====================================
2025-09-12T06:36:50.3298323Z _______ ERROR collecting tests/extensions/memory/test_encrypt_session.py _______
2025-09-12T06:36:50.3299644Z ImportError while importing test module '/home/runner/work/openai-agents-python/openai-agents-python/tests/extensions/memory/test_encrypt_session.py'.
2025-09-12T06:36:50.3301101Z Hint: make sure your test modules/packages have valid Python names.
2025-09-12T06:36:50.3301588Z Traceback:
2025-09-12T06:36:50.3302231Z ../../../.local/share/uv/python/cpython-3.9.23-linux-x86_64-gnu/lib/python3.9/importlib/__init__.py:127: in import_module
2025-09-12T06:36:50.3303105Z     return _bootstrap._gcd_import(name[level:], package, level)
2025-09-12T06:36:50.3303726Z tests/extensions/memory/test_encrypt_session.py:14: in <module>
2025-09-12T06:36:50.3304409Z     from agents.extensions.memory.encrypt_session import EncryptedSession
2025-09-12T06:36:50.3305079Z src/agents/extensions/memory/encrypt_session.py:32: in <module>
2025-09-12T06:36:50.3305659Z     from typing import Any, Literal, TypedDict, TypeGuard, cast
2025-09-12T06:36:50.3306632Z E   ImportError: cannot import name 'TypeGuard' from 'typing' (/home/runner/.local/share/uv/python/cpython-3.9.23-linux-x86_64-gnu/lib/python3.9/typing.py)
2025-09-12T06:36:50.3307570Z =========================== short test summary info ============================
2025-09-12T06:36:50.3308049Z ERROR tests/extensions/memory/test_encrypt_session.py
2025-09-12T06:36:50.3308558Z !!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
2025-09-12T06:36:50.3309031Z =============================== 1 error in 4.59s ===============================
2025-09-12T06:36:50.6243452Z make: *** [Makefile:44: old_version_tests] Error 2
2025-09-12T06:36:50.6259143Z ##[error]Process completed with exit code 2.

Thanks, this should pass now.

split type imports between typing and typing_extensions:

from typing_extensions import Literal, TypedDict, TypeGuard
from typing import Any, cast

[maxmekiska]

@seratch I have implemented all the suggestions, and tests are now passing. Could you take a final look and let me know if you have any further suggestions. Thanks!