goal

type Action struct {
	Kind   ActionKind
	Reason string

	// Status is the target status for a lifecycle-transition decision. It is
	// empty for ActionNone and ActionQueueTurn.
	Status Status
	// PauseReason accompanies ActionPauseGoal.
	PauseReason PauseReason
	// Continuation is set only for ActionQueueTurn and carries the hint that
	// justified continuation.
	Continuation *ContinuationHint
	// WakeDelaySeconds is set only for ActionScheduleWakeup.
	WakeDelaySeconds int
}

type ActionKind string

type AfterTurnInput struct {
	ConversationID string
	TurnStatus     string
	RequestTime    time.Time
	Usage          *usage.Aggregator

	TurnRunning        bool
	QueuedUserTurns    int
	PendingElicitation bool
	PendingApproval    bool
	PendingAsync       bool
	UsageLimited       bool

	ConsecutiveNoProgress int
	AutonomousTurnsUsed   int
	Continuation          *ContinuationHint
	ProgressFingerprint   string
}

type AsyncPolicy string

type ContinuationHint struct {
	// Reason is the human-readable justification for continuing, surfaced to
	// the user (e.g. on the queued turn).
	Reason string
	// Preview is the visible queue preview text for the scheduled turn.
	Preview string
	// Payload is the hidden controller context handed to the continuation
	// turn as internal input. It is not rendered as a user message.
	Payload string
}

type ContinueMode string

type Controller struct{}

type ControllerSpec struct {
	ContinueMode             ContinueMode `json:"continueMode"`
	OnTurnFinished           TurnPolicy   `json:"onTurnFinished"`
	OnAsyncCompleted         AsyncPolicy  `json:"onAsyncCompleted"`
	WakeDelaySeconds         *int         `json:"wakeDelaySeconds,omitempty"`
	MaxAutonomousTurns       *int         `json:"maxAutonomousTurns,omitempty"`
	MaxConsecutiveNoProgress *int         `json:"maxConsecutiveNoProgress,omitempty"`
}

type Goal struct {
	ID                          string
	ConversationID              string
	Objective                   string
	Status                      Status
	StatusReason                string
	PauseReason                 PauseReason
	Controller                  *ControllerSpec
	TokenBudget                 *int64
	TokensUsed                  int64
	TimeUsedSeconds             int64
	AutonomousTurnsUsed         int64
	ConsecutiveNoProgress       int64
	LastContinuationFingerprint string
	CreatedAt                   time.Time
	UpdatedAt                   *time.Time
}

type PauseReason string

type Runtime struct {
	// contains filtered or unexported fields
}

type Snapshot struct {
	Goal *Goal

	// Conversation activity. Continuation requires a fully idle conversation.
	TurnRunning        bool
	QueuedUserTurns    int
	PendingElicitation bool
	PendingApproval    bool
	PendingAsync       bool

	// Externally detected provider/runtime usage limit. The controller reacts
	// to it but does not detect it.
	UsageLimited bool

	// Progress guards, accounted by the runtime across autonomous turns.
	ConsecutiveNoProgress int
	AutonomousTurnsUsed   int

	// Continuation is the explicit next-step signal, or nil when none exists.
	Continuation *ContinuationHint
}

type Status string

type Store interface {
	// Current returns the active goal for a conversation, or nil when none
	// exists.
	Current(ctx context.Context, conversationID string) (*Goal, error)
	// RecordUsage persists absolute usage counters for a goal. The caller is
	// responsible for computing the new totals.
	RecordUsage(ctx context.Context, goalID string, tokensUsed, timeUsedSeconds int64) error
	// Transition persists a status change with an accompanying status reason.
	Transition(ctx context.Context, goalID string, status Status, reason string) error
	// Pause persists a paused status with a dedicated pause reason.
	Pause(ctx context.Context, goalID string, reason PauseReason) error
	// UpdateControllerState persists autonomous controller counters and
	// the latest continuation fingerprint.
	UpdateControllerState(ctx context.Context, goalID string, autonomousTurnsUsed, consecutiveNoProgress int64, fingerprint string) error
}

type TurnPolicy string