-- allium: 3
-- turn-limit.allium

-- Scope: Agent turn limit enforcement per session
-- Includes: Turn counting, limit enforcement, session abort, disable/enable
-- Excludes:
--   - Widget display (UI implementation detail)
--   - Environment variable reading (configuration mechanism)
--   - turn-limit command (configuration mechanism)

------------------------------------------------------------
-- Entities
------------------------------------------------------------

entity Session {
    turn_count: Integer
    status: active | aborted
    user_confirms_continuation: Boolean?

    transitions status {
        active -> aborted
        terminal: aborted
    }
}

------------------------------------------------------------
-- Config
------------------------------------------------------------

config {
    max_turns: Integer | unlimited = 25

    @guidance
        -- When max_turns is unlimited, no boundary check fires.
        -- The turn counter still increments for observability.
        -- Transitioning from unlimited to a positive integer
        -- resets turn_count to 0.
}

------------------------------------------------------------
-- Rules
------------------------------------------------------------

rule TurnLimitReached {
    when: session: Session.turn_count transitions_to config.max_turns
    requires:
        config.max_turns != unlimited
        session.turn_count = config.max_turns

    ensures:
        if session.user_confirms_continuation:
            session.turn_count = 0
        else:
            session.status = aborted

    @guidance
        -- The user_confirms_continuation field is set by the
        -- implementation when presenting a confirmation prompt to
        -- the user at the turn limit boundary. The implementation
        -- may use a widget, dialog, or other mechanism to capture
        -- the user's choice.
        --
        -- When the user confirms, the turn_count resets to zero,
        -- allowing the agent to continue for another round of turns.
        -- When the user declines (field is null or false), the
        -- session is aborted.
        --
        -- Without a UI, the default behaviour is to abort.
}

rule LimitReEnabled {
    when: config.max_turns transitions_to Integer

    ensures:
        session.turn_count = 0

    @guidance
        -- When the user switches from unlimited back to a positive
        -- integer limit, the turn counter resets to zero so the
        -- new limit applies from a clean starting point.
}