feat: stateful sessions and coding agent support for LLM reflections

[lukedhlee]

feat: stateful sessions and coding agents for reflection

Summary

Adds two composable primitives to GEPA's reflection layer:

1. Session — a forkable LLM conversation. Reflection can now remember prior proposals across iterations.
2. CodingAgent — a first-class abstraction for CLI coding tools (Claude Code, OpenCode) that plugs into reflection_lm the same way a regular LM does.

Zero breaking changes. session_strategy=None (default) preserves current stateless behavior.

Why

• Use more context. Instead of rebuilding state from scratch every iteration, the LLM carries forward what it already learned from prior mutations.
• Promote diversity. Forking from different branches of the optimization tree (via ParentLinked, RandomStrategy, or custom strategies) explores distinct lineages rather than collapsing onto one trajectory.
• Prevent context rot. AlwaysReset on a schedule — or RoundRobin — drops stale history before it drags the LLM into its own loops.
• Track quality per session. SessionRecord.val_score lets future strategies ("pick the best lineage") make score-aware decisions.

Usage

Stateless (default, unchanged)

optimize(..., reflection_lm="openai/gpt-4.1")
# session_strategy=None is the default — same as before

Stateful LLM sessions

optimize(
    ...,
    reflection_lm="openai/gpt-4.1",
    session_strategy="fork",  # each mutation forks the most recent conversation
)

Lineage-aware sessions

optimize(
    ...,
    reflection_lm="openai/gpt-4.1",
    session_strategy="parent_linked",  # fork from the parent candidate's session
)

Coding agent as reflection LM

from gepa.agents import CodingAgent

agent = CodingAgent(harness="claude_code", model="sonnet")
optimize(
    ...,
    reflection_lm=agent,             # auto-wires sessions
    session_strategy="fork",
)

Concepts

Session protocol

class Session(Protocol):
    def send(self, content: str) -> str: ...   # call LLM, history grows
    def fork(self) -> Session: ...              # new session, history copied, diverges
    def reset(self) -> Session: ...             # new session, empty history, same config
    @property
    def session_id(self) -> str: ...
    @property
    def history(self) -> list[dict]: ...

fork() and reset() leave the original untouched — both return a new session.

Op	Creates new?	History	Mutates original?
send(content)	No	Grows	Yes
fork()	Yes	Copied	No
reset()	Yes	Empty	No

Implementations: LLMSession (in-memory), NullSession (no-op), ClaudeCodeSession / OpenCodeSession (CLI subprocess with native --resume / --fork-session).

SessionStrategy protocol (one hook)

class SessionStrategy(Protocol):
    def select(self, ctx: SessionContext) -> Session: ...

• select(ctx) — before each mutation: pick the session to use. Called by the proposer right after it picks the parent candidate, so ctx.parent_candidate_idx is always available.

Bookkeeping (storing accepted candidates, tracking scores) is handled by SessionManager.observe() — strategies only decide which session to use.

SessionContext and SessionRecord

@dataclass(frozen=True)
class SessionRecord:
    session: Session
    val_score: float | None = None

@dataclass(frozen=True)
class SessionContext:
    parent_candidate_idx: int | None
    iteration: int
    sessions: Mapping[int | str, SessionRecord]   # read-only store snapshot
    create: Callable[[], Session]                  # factory for new sessions

SessionRecord is what gets stored per accepted candidate — the session and its score. SessionContext is a snapshot rebuilt every select() call so the strategy can see the full store, which candidate is being mutated, and a factory to create fresh sessions.

How session lifecycle works (step by step)

The SessionManager holds a dict[int | str, SessionRecord] — a store that maps candidate indices to their sessions and scores. It starts empty and grows as candidates are accepted.

Each iteration has two phases:

Phase 1: select() — proposer picks a session before the LM calls

# Proposer just picked parent candidate 3. Manager builds a snapshot and asks the strategy:
ctx = SessionContext(
    parent_candidate_idx=3,
    iteration=5,
    sessions={...},       # read-only snapshot of the store (all accepted candidates so far)
    create=factory,       # factory for brand-new sessions when store is empty
)
session = strategy.select(ctx)   # strategy returns a Session to use

# Example: ParentLinked looks up candidate 3's session and forks it
# Example: AlwaysFork ignores the parent and forks the most recent session

Phase 2: observe() — engine records the outcome after evaluation

# Engine evaluated the mutation. It was accepted as candidate 6 with score 0.85.
manager.observe(candidate_idx=6, accepted=True, val_score=0.85)

# Internally: accepted → stored as {6: SessionRecord(session, val_score=0.85)}
# Rejected → nothing stored

The store grows iteration by iteration:

After iter 0 (accepted):  store = {0: SessionRecord(s_root)}
After iter 1 (accepted):  store = {0: ..., 1: SessionRecord(s_1, 0.4)}
After iter 2 (rejected):  store = {0: ..., 1: ...}                      ← unchanged
After iter 3 (accepted):  store = {0: ..., 1: ..., 3: SessionRecord(s_3, 0.7)}
After iter 4 (rejected):  store = {0: ..., 1: ..., 3: ...}              ← unchanged
Iter 5 select():          strategy sees {0, 1, 3} and picks accordingly
After iter 5 (accepted):  store = {0: ..., 1: ..., 3: ..., 6: SessionRecord(s_6, 0.85)}

Keys are candidate indices (not iteration numbers) — rejected candidates don't appear.

The types:

• SessionRecord(session, val_score) — what's stored per accepted candidate.
• SessionContext — rebuilt every select() call. Gives the strategy a read-only view of the store plus "what's happening now" (parent, iteration).

Built-in strategies

All built-in strategies except ParentLinked operate on the most recent session in the store. They differ only in the action (fork vs reset):

Strategy	Picks	Action	When to use
AlwaysFork	Most recent	Fork	Default — carry forward full history
AlwaysReset	Most recent	Reset	Stateless (current GEPA behavior)
RandomStrategy(p)	Most recent	Fork with prob p, else reset	Balanced exploration
RoundRobin	Most recent	Alternate fork/reset	Predictable diversity schedule
ParentLinked	Parent candidate's session	Fork	Lineage-aware — session tree ≅ candidate tree
BestScore	Highest val_score session	Fork	Exploit the best lineage so far

Custom strategies can combine any selection logic with any action. For example, "pick the best-scoring session and fork it" is a ~10-line class.

Writing a custom strategy is one method:

class PickBest(SessionStrategy):
    def select(self, ctx):
        entries = [e for e in ctx.sessions.values() if e.val_score is not None]
        if not entries:
            return ctx.create()
        return max(entries, key=lambda e: e.val_score).session.fork()

(This is already built-in as BestScore / session_strategy="best_score")

SessionManager (keyed store + strategy delegation)

manager = SessionManager(create=factory, strategy=AlwaysFork())

session = manager.select(parent_candidate_idx=3)   # strategy picks session
response = session.send("Improve the code...")
manager.observe(candidate_idx=7, accepted=True, val_score=0.87)  # stores accepted candidate

The manager holds dict[int | str, SessionRecord]. Accepted candidates are stored by index; rejected candidates are not stored.

CodingAgent

A thin factory that creates a Session for a given CLI backend. Each harness encapsulates its own quirks (JSON output format, CLI flags, cost tracking) behind the Session protocol.

agent = CodingAgent(
    harness="claude_code",        # or "opencode"
    model="sonnet",               # passed through to the CLI
    system_prompt="...",
    timeout=300,
    max_budget_usd=5.0,           # claude_code only
)

Passing a CodingAgent as reflection_lm triggers isinstance detection in api.py and auto-wires the session pipeline — no boilerplate.

Architecture

Session lifecycle is split between the proposer and the engine — each owns the part it has the information for:

• Proposer calls select(parent_candidate_idx) — it knows the parent (it just picked it).
• Engine calls observe(candidate_idx, accepted, val_score) — it knows the outcome (it just evaluated it).
• Users see none of this — they just set session_strategy="fork".

                  ┌─────────────────────────────────────────────────┐
                  │                     ENGINE                      │
                  │          observe() after accept/reject          │
                  └──────────────────┬──────────────────────────────┘
                                     │
                  ┌──────────────────┼──────────────────────────────┐
                  │             SessionManager                      │
                  │   ┌──────────────────────────────────────┐      │
                  │   │         SessionStrategy               │     │
                  │   │  select(ctx) → Session                │     │
                  │   └──────────────────────────────────────┘      │
                  │   dict[int|str, SessionRecord]  (keyed store)   │
                  └──────────────────┬──────────────────────────────┘
                                     │
                  ┌──────────────────┼──────────────────────────────┐
                  │                PROPOSER                         │
                  │  1. Pick parent candidate                       │
                  │  2. select(parent_candidate_idx) ← right here  │
                  │  3. Build reflective dataset                    │
                  │  4. reflection_lm(prompt) → routes via session  │
                  │  5. Return proposal                             │
                  └─────────────────────────────────────────────────┘

The proposer sees reflection_lm as a plain lm(prompt) -> str callable. Under the hood, make_session_lm creates a closure that reads session_manager.current_session(), which select() just set. The proposer never imports or touches any session object.

History preservation: LLMSession.send() passes the full conversation history to the underlying LM callable. For plain LMs (e.g. LM wrapping litellm), the callable receives the full list[dict] message list — no lossy extraction. For CodingAgent, the CLI backend (Claude Code/OpenCode) natively manages its own history via --resume / --fork-session flags.

Custom proposers that don't know about sessions keep working — they just call reflection_lm(prompt) and sessions work transparently via the closure. Advanced custom proposers can inject session_manager and call select() themselves for full control.

Session tree ≅ Candidate tree (with ParentLinked)

Candidate tree          Session store (keyed by candidate idx)

      A                 0 → SessionRecord(s_A)           [root]
     / \                1 → SessionRecord(s_B, 0.6)      [forked from s_A]
    B   F               2 → SessionRecord(s_C, 0.8)      [forked from s_B]
   / \                  3 → SessionRecord(s_D, 0.7)      [forked from s_B — sibling of C]
  C   D                 4 → SessionRecord(s_F, 0.4)      [forked from s_A — sibling of B]

Each accepted candidate is bound to the session that produced it. Re-visiting the same parent forks independently, so siblings never interfere.

Tests

• 62 unit + integration tests (tests/test_session.py) — Session protocol, LLMSession, NullSession, make_session_lm, all 5 strategies, SessionManager with keyed store, val_score tracking, resolver, end-to-end mock loops (fork/reset/parent_linked), gepa.optimize() integration with all strategies
• 82 unit + integration tests (tests/test_agents.py) — ClaudeCodeSession, OpenCodeSession, CodingAgent, strategy composition with agents, end-to-end mock loops (fork/parent_linked/CLI flags), auto-wire simulation, real CLI (skipped if not installed)
• ruff check clean on all changed files

TODO (follow-ups)

• Session persistence (codec layer). SessionCodec protocol to serialize/restore sessions to disk alongside gepa_state.bin for checkpoint/resume.

• Performance benchmark. A/B on AIME math comparing session_strategy=None vs "fork" vs "parent_linked".

• Richer state presentation. Human-readable JSON/YAML with all trajectories and scores for agent reflection.

• note.md scratchpad. Persistent file where reflection LLMs can write down insights across iterations.

Files changed

File	What
src/gepa/core/session.py	Session protocol, LLMSession, NullSession — the conversation primitive
src/gepa/core/session_manager.py	SessionStrategy protocol (select only), SessionContext/SessionRecord dataclasses, SessionManager (owns observe bookkeeping), resolve_session_strategy, make_session_lm — the orchestration layer
src/gepa/strategies/session_strategy.py	AlwaysFork, AlwaysReset, RandomStrategy, RoundRobin, ParentLinked, BestScore — all inherit SessionStrategy
src/gepa/agents/__init__.py	CodingAgent factory
src/gepa/agents/claude_code.py	ClaudeCodeSession — wraps claude -p CLI
src/gepa/agents/opencode.py	OpenCodeSession — wraps opencode run CLI
src/gepa/core/engine.py	session_manager.observe() at accept/reject points
src/gepa/proposer/reflective_mutation/reflective_mutation.py	Optional session_manager, select(parent_candidate_idx) after parent pick
src/gepa/api.py	session_strategy param, CodingAgent auto-wire, session wiring to proposer + engine. LM resolution and session setup are colocated — CodingAgent uses native sessions directly, plain LMs are wrapped in LLMSession with full message history passed through.
src/gepa/optimize_anything.py	Same wiring in the second entry point — reflection_lm passed directly as LLMSession.api_call (no lossy bridge)
tests/test_session.py	62 tests
tests/test_agents.py	82 tests

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
src/gepa/optimize_anything.py	19% smaller
src/gepa/api.py	1% smaller
src/gepa/agents/__init__.py	0% smaller
src/gepa/agents/claude_code.py	0% smaller
src/gepa/agents/opencode.py	0% smaller
src/gepa/core/engine.py	0% smaller
src/gepa/core/session.py	0% smaller
src/gepa/core/session_manager.py	0% smaller
src/gepa/proposer/reflective_mutation/reflective_mutation.py	0% smaller
src/gepa/strategies/session_strategy.py	0% smaller
tests/test_agents.py	0% smaller
tests/test_session.py	0% smaller

[LakshyAAAgrawal]

Let's not make this default. Is there a safe option by default, that never uses any file writes, and only performs reads?

[Shangyint]

Reads do not need permission in CC. Removing this flag should suffice

[Shangyint]

Looks good!

I think a core feature is not supported, though. A common way to use Session is to use Session from the parent (probably means we fork every time we generate another child candidate?) If we want to support this, we probably need to track state, or at least candidate index for sessions

Another point is: do we want sessions as a separate concept, or can we just upgrade current proposer with sessions? i.e. all proposers are stateful by default, and backcompitiblility can be provided by resetting sessions every proposer call.

[Shangyint]

Reads do not need permission in CC. Removing this flag should suffice

[Shangyint]

I added several comments regarding how to make session_manager less stateful. For example, I think session_manager._current is not useful and may make the code much harder to maintain later. We only need a map from candidates to sessions IMO.

[Shangyint]

Check if strategy is an instance of SessionStrategy?

[Shangyint]

Not sure if we want this. Is this for backward compatibility? Otherwise LLMSession can just provide everything we need for LanguageModel?

[Shangyint]

By the way, I don't link we need session_manager.current at all. IMO, we can always pass the session around as a return value of session_manager.select.

[Shangyint]

you can add the needed session as part of the context here.

[Shangyint]

What's the reason to allow a lambda instead of a concrete session instance here? Can we just allow session: Session?

[Shangyint]

Similar problem here: this is not good. It works, but it is easier to introduce bugs because we are setting some internal state of session_manager. We should just return select and put it into the proposal context.

[Shangyint]

Ideally this should look like make_session_lm(session_manager.new_session())