Cyrene_v2/internal/runtime/loop/turn.go

package loop

import (
	"context"

	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
)

// This file owns the loop's turn boundary: the point where one user turn has
// settled (a Run produced a Result) and the state that follows the persona —
// emotion and affection, design/01 §2 — is advanced outside the loop. The loop
// itself stays persona- and emotion-agnostic (design/16 §3.3: the engine
// generates text; state and persistence belong to the layers around it), so it
// only reports the turn and records the mood label the hook hands back.

// TurnEnd describes one settled turn to the loop's OnTurnEnd hook. It carries
// everything an observer needs without the loop knowing what the observer does.
type TurnEnd struct {
	// SessionID is the conversation the turn belonged to.
	SessionID string
	// PersonaID is the role the turn speaks as: the session env's resolved role when
	// the caller supplied one, otherwise the loop's configured default
	// (design/22 §4.2). It keeps the observer persona-scoped (design/01 §2): the
	// emotion machine and affection of that role — and only that role — advance.
	PersonaID string
	// UserText is the latest user message of the turn ("" when the turn carried
	// no user text, e.g. a resumed tool round).
	UserText string
	// AssistantText is the turn's final assistant text.
	AssistantText string
	// StopReason classifies how the turn ended.
	StopReason string
	// Steps is the number of model steps the turn took.
	Steps int
	// Env is the conversation's resolved isolation environment (owner / group /
	// stranger), so a hook can keep a restricted conversation read-only.
	Env SessionEnv
}

// TurnEndHook observes a settled turn and returns the persona's mood label for
// it ("" when the caller tracks no emotion). It runs once per settled turn — not
// once per model step — so a multi-step tool turn applies its effect exactly
// once. It must not block: it runs on the Run path after the answer is complete,
// and its return value is carried on Result.Mood to the persistence layer.
type TurnEndHook func(TurnEnd) string

// settleTurn reports a settled turn to the hook (when wired) and records the
// returned mood label on the result, so the persisted assistant message carries
// the turn's mood (design/16 §3.3). The conversation environment travels on ctx,
// so a group/stranger turn reaches the hook as restricted.
func (l *Loop) settleTurn(ctx context.Context, sessionID string, msgs []model.Message, res *Result) {
	if l.onTurnEnd == nil {
		return
	}
	res.Mood = l.onTurnEnd(TurnEnd{
		SessionID:     sessionID,
		PersonaID:     l.personaFor(ctx),
		UserText:      lastUserText(msgs),
		AssistantText: res.Text,
		StopReason:    res.StopReason,
		Steps:         res.Steps,
		Env:           sessionEnvFrom(ctx),
	})
}