Skip to content

refactor: formalize LlmSessionActor state machine for composable lifecycle states #411

@Aaronontheweb

Description

@Aaronontheweb

Problem

LlmSessionActor has an implicit state machine implemented via Become() calls
with Command<> registrations that don't compose cleanly. The current states
(Ready, Processing, Compacting) work but adding new states is fragile:

  • Command<> handlers registered in one Become() scope can conflict with handlers
    in shared methods like CommandSubscriptionMessages()
  • Adding a Passivating state (needed for pre-shutdown memory distillation) requires
    either duplicating shared handler registration or using boolean flags — both are
    brittle
  • The actor is 3000+ lines and its state transitions are scattered across methods
    rather than being explicitly defined

Motivation

This blocks two features:

Proposed approach

  1. Define an explicit state enum: Ready, Processing, Compacting, Passivating
  2. Extract shared command handlers into composable methods that can be mixed into any state
  3. Make state transitions explicit and testable
  4. Extract dependencies (memory observation, compaction, tool execution) into
    independently testable components where possible
  5. Reduce the actor's line count by extracting concerns into child actors or services

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions