proposal(environments): SupportsPersistence Protocol for multi-turn sessions

[thoriqakbar0]

Summary

This PR introduces a SupportsPersistence Protocol that defines how environments can support multi-turn sessions. LocalREPL is provided as the reference implementation.

The Problem

Every completion() call spawns a fresh environment that gets destroyed afterward. Variables, computed results, loaded contexts — all gone.

The Solution

A SupportsPersistence Protocol that any environment can implement:

@runtime_checkable
class SupportsPersistence(Protocol):
    def add_context(self, payload, index=None) -> int
    def get_context_count(self) -> int
    def add_history(self, messages, index=None) -> int
    def get_history_count(self) -> int
    def update_handler_address(self, address) -> None

Usage

with RLM(backend="openai", persistent=True) as rlm:
    result1 = rlm.completion("Document 1...", root_prompt="Summarize")
    # context_0 = Document 1, variables computed
    
    result2 = rlm.completion("Document 2...", root_prompt="Compare with previous")
    # context_1 = Document 2, can still access context_0 and prior variables

What's Included

• SupportsPersistence Protocol with comprehensive documentation
• LocalREPL implementation as reference
• Versioned contexts: context_0, context_1, ... (with context aliasing context_0)
• Versioned histories: history_0, history_1, ... (with history aliasing history_0)
• Runtime capability checking: isinstance(env, SupportsPersistence)
• Clear error messages: Other envs raise NotImplementedError with guidance

For Other Environments (Docker, Modal, , etc.)

The Protocol docstrings explain exactly how to implement persistence. See:

• rlm/environments/base_env.py — Protocol definition
• rlm/environments/local_repl.py — Reference implementation
• tests/test_local_repl_persistent.py — Expected behavior

Tests

• tests/test_local_repl.py — Non-persistent behavior (env resets between calls)
• tests/test_local_repl_persistent.py — Persistence unit tests
• tests/test_multi_turn_integration.py — End-to-end multi-turn tests

Not Included

• Docker/Modal persistence (they have the infrastructure, just need Protocol methods)
• Async acompletion() support

[alexzhang13]

@thoriqakbar0 Can you separate out one test file for testing local repl without persistence (and add an explicit test to show that it's not persistent, so you do 2 fake RLM calls so the env gets reset, but it tries to use a variable that existed before) and one for local_repl_with_persistence to check that persistence is working?

Thanks!

[alexzhang13]

Also one more thing, let's update the abstract class to support "persistent: bool". For Docker, Modal, etc. add the flag, but if the user turns it on, throw an error that says "Persistent REPLs are currently not supported for environment: {env}".

[alexzhang13]

See comments above:

1. Update test_local_repl.py to be no persistence, then add a new test file with persistent test cases.
2. Update base env class, and add persistent flag to all. But for now in Docker, etc. throw an error and say not supported currently.

[thoriqakbar0]

on itt

[thoriqakbar0]

Updated PR scope

Updated the title and description to better reflect what this PR actually delivers.

Before: Focused on LocalREPL persistence implementation

After: Focused on the SupportsPersistence Protocol pattern, with LocalREPL as the reference implementation

Why the change?

While implementing persistence for LocalREPL, I realized the main thing that I was trying to do is protocol pattern itself. it gives other environment authors (Docker, Modal, Cloudflare, Daytona, E2B, etc.) a clear path to add persistence:

1. Check the Protocol in base_env.py for what methods to implement
2. Read the docstrings for expected behavior (versioning, aliasing, deep copy)
3. Look at local_repl.py as a working example
4. Run tests/test_local_repl_persistent.py to see expected behavior

The implementation for persistence already exists in most environments (Docker uses dill, Modal uses sandbox state). They just need to implement the 5 Protocol methods on top.

would love feedback on this. tq!

[alexzhang13]

It looks good! Will merge after linting stuff, but also @thoriqakbar0 feel free to integrate persistence into the other REPLs (e.g. Docker, Modal, etc.)

We will likely also just need to integrate the other sandboxes. I don't have any keys to test them though, which is why I haven't merged these PRs in yet.