feat: report agent runtime hours usage in entitlements (#27985)

Populate `FeatureAgentRuntimeHours.Actual` on every entitlements refresh
for licenses that grant the feature. A new
`GetTotalUsageHBAgentRuntimeV1` query sums `runtime_ms` over the
license's usage period, reading `usage_events` directly:
`hb_agent_runtime_v1` is exactly one row per hourly bucket
deployment-wide with `created_at` at the bucket start, enforced by the
unique partial index introduced in #27983.

The measurement reuses the shared `measureUsage` policy from #27984
through a new `AgentRuntimeMsFn` closure (usage publisher subject):
failures publish the stable
`LicenseAgentRuntimeUsageUnavailableErrorText` and log the cause. Usage
is floored to whole hours, matching the unit of the
`agent_runtime_hours_*` claims, and at most one warning is emitted per
refresh: reaching the allocation supersedes the advisory soft limit. The
dashboard renders the soft-limit advisory muted without a sales link and
treats the runtime usage-unavailable text as a diagnostic.

**Precise usage.** `Feature.ActualMs` (JSON `actual_ms`), set only for
`agent_runtime_hours`, carries the exact stored milliseconds backing the
floored `Actual` so clients can render fractional hours (e.g. `10.3`).
It has the same freshness as `Actual`; the whole-hour warning thresholds
are unchanged.

**Unlimited licenses.** A license minted with the unlimited (`-1`)
allocation decodes to an enabled feature with a nil `Limit` (#27984), so
the warning write-back now guards the allocation dereference: no
thresholds can exist for an unlimited license, so no runtime hours
warning is ever emitted, while `Actual` is still measured and published.
`Feature.Compare` is unchanged; for usage-period features the
issued-at/end dates decide first, so a metered feature outranks an
unlimited one only on an exact timestamp tie, an edge pinned by a
`TestFeatureComparison` case and documented on
`decodeAgentRuntimeHours`.

**Grandfathered premium licenses.** Premium licenses without
`agent_runtime_hours_*` claims are now granted the feature disabled with
a zero limit over the license term, identical to an explicit
`allocation: 0`: usage is measured and published for every Premium
deployment, and chatd's pooled admission (#27902) caps concurrent
agentic chats until a license with a positive allocation is added. The
default carries a fixed early `UsagePeriod.IssuedAt` (2026-08-01, the
same mechanism as the managed-agents default) so any license actually
carrying the claims outranks it in the `AddFeature` merge regardless of
the licenses' relative issue dates; the constant must stay earlier than
the earliest legitimately issued claim-bearing license. Zero allocations
(explicit or grandfathered) emit no deployment-wide warning banner:
those deployments are steered by the in-page upgrade CTA and the
concurrency cap. Enterprise licenses are unchanged.

Part 3 of a 3-PR stack splitting up #27796 (see there for review
history). Stack: #27983 → #27984 → this PR.

Closes CODAGT-852.

codersdk/deployment.go

@@ -380,32 +380,42 @@ func (set FeatureSet) Features() []FeatureName {
 type Feature struct {
 	Entitlement Entitlement `json:"entitlement"`
 	Enabled     bool        `json:"enabled"`
-	Limit       *int64      `json:"limit,omitempty"`
+	// Limit is the maximum value the license grants for the feature, in the
+	// feature's own unit. For FeatureAgentRuntimeHours, an enabled feature
+	// with Limit omitted means the license grants unlimited runtime hours.
+	Limit *int64 `json:"limit,omitempty"`
 	// SoftLimit is the advisory warning threshold that accompanies Limit for
 	// features whose license carries it. For these features, Limit carries
-	// the purchased allocation.
-	//
-	// Only certain features set this field:
-	// - FeatureAgentRuntimeHours
+	// the purchased allocation; an unlimited allocation has no thresholds,
+	// so SoftLimit is omitted alongside the omitted Limit. Only
+	// FeatureAgentRuntimeHours sets this field.
 	SoftLimit *int64 `json:"soft_limit,omitempty"`
 	// HardLimit is the enforcement threshold that accompanies Limit for
 	// features whose license carries it. See SoftLimit for the set of
 	// features that use these thresholds.
 	HardLimit *int64 `json:"hard_limit,omitempty"`
-	Actual    *int64 `json:"actual,omitempty"`
+	// Actual is the usage measured against Limit, when known: a
+	// point-in-time count for most features, or usage accumulated over
+	// UsagePeriod for features that set one. Its unit matches Limit's;
+	// FeatureAgentRuntimeHours reports whole hours floored from the
+	// recorded milliseconds, with the precise value available in
+	// ActualMs. FeatureAgentRuntimeHours usage can trail by roughly one
+	// hour because the current hour is not emitted, plus the entitlement
+	// refresh interval.
+	Actual *int64 `json:"actual,omitempty"`
+	// ActualMs is the precise usage backing Actual, in milliseconds, for
+	// features measured in time. It has the same freshness as Actual.
+	// Only FeatureAgentRuntimeHours sets this field.
+	ActualMs *int64 `json:"actual_ms,omitempty"`
 
 	// Below is only for features that use usage periods.
 
 	// UsagePeriod denotes that the usage is a counter that accumulates over
 	// this period (and most likely resets with the issuance of the next
-	// license).
-	//
-	// These dates are determined from the license that this entitlement comes
-	// from, see enterprise/coderd/license/license.go.
-	//
-	// Only certain features set these fields:
-	// - FeatureManagedAgentLimit
-	// - FeatureAgentRuntimeHours
+	// license). These dates are determined from the license that this
+	// entitlement comes from, see enterprise/coderd/license/license.go.
+	// Only FeatureManagedAgentLimit and FeatureAgentRuntimeHours set this
+	// field.
 	UsagePeriod *UsagePeriod `json:"usage_period,omitempty"`
 }
 

codersdk/licenses.go

@@ -12,12 +12,19 @@ import (
 )
 
 const (
-	LicenseExpiryClaim                               = "license_expires"
-	LicenseTelemetryRequiredErrorText                = "License requires telemetry but telemetry is disabled"
-	LicenseManagedAgentLimitExceededWarningText      = "You have built more workspaces with managed agents than your license allows."
-	LicenseAIGovernance90PercentWarningText          = "You have used %d%% of your AI Governance add-on seats."
-	LicenseAIGovernanceOverLimitWarningText          = "Your organization is using %d of %d AI Governance add-on seats (%d over the limit)."
-	LicenseAgentRuntimeHoursClaimsIgnoredWarningText = "A license contains unusable Coder Agent runtime hour claims, which were ignored. The rest of that license is unaffected. Check the coderd logs for the affected license and claims, and contact support to have the license re-issued."
+	LicenseExpiryClaim                          = "license_expires"
+	LicenseTelemetryRequiredErrorText           = "License requires telemetry but telemetry is disabled"
+	LicenseManagedAgentLimitExceededWarningText = "You have built more workspaces with managed agents than your license allows."
+	LicenseAIGovernance90PercentWarningText     = "You have used %d%% of your AI Governance add-on seats."
+	LicenseAIGovernanceOverLimitWarningText     = "Your organization is using %d of %d AI Governance add-on seats (%d over the limit)."
+	// The dashboard's LicenseBanner matches this text's pre-placeholder
+	// prefix to render it muted and without a sales link, so the license
+	// warning texts must stay pairwise distinct before their first
+	// placeholder. See TestLicenseAgentRuntimeHoursWarningTexts.
+	LicenseAgentRuntimeHoursSoftLimitWarningText         = "Your deployment is approaching its Coder Agent runtime hours allocation: %d of the %d hours included in the current license term are used, at or above the advisory soft limit of %d hours."
+	LicenseAgentRuntimeHoursAllocationReachedWarningText = "Your deployment has used %d of the %d Coder Agent runtime hours included in the current license term."
+	LicenseAgentRuntimeUsageUnavailableErrorText         = "Unable to determine Coder Agent runtime usage. Reported runtime hours are unavailable until the next successful refresh; workspaces are unaffected. Check the coderd logs for details."
+	LicenseAgentRuntimeHoursClaimsIgnoredWarningText     = "A license contains unusable Coder Agent runtime hour claims, which were ignored. The rest of that license is unaffected. Check the coderd logs for the affected license and claims, and contact support to have the license re-issued."
 )
 
 type AddLicenseRequest struct {

codersdk/licenses_test.go

@@ -0,0 +1,50 @@
+package codersdk_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/codersdk"
+)
+
+// TestLicenseAgentRuntimeHoursWarningTexts pins the warning-text prefix
+// couplings consumed by the dashboard's LicenseBanner
+// (site/src/modules/dashboard/LicenseBanner).
+func TestLicenseAgentRuntimeHoursWarningTexts(t *testing.T) {
+	t.Parallel()
+
+	// Cut rather than Split so a template losing its placeholder fails the
+	// test instead of silently turning the whole message into the "prefix".
+	templatePrefix := func(text, placeholder string) string {
+		t.Helper()
+		prefix, _, ok := strings.Cut(text, placeholder)
+		require.True(t, ok, "template %q must contain placeholder %q", text, placeholder)
+		return prefix
+	}
+
+	aiGovNearLimitPrefix := templatePrefix(codersdk.LicenseAIGovernance90PercentWarningText, "%d%%")
+	aiGovOverLimitPrefix := templatePrefix(codersdk.LicenseAIGovernanceOverLimitWarningText, "%d")
+	softLimitPrefix := templatePrefix(codersdk.LicenseAgentRuntimeHoursSoftLimitWarningText, "%d")
+
+	runtimeTexts := map[string]string{
+		"SoftLimit":         codersdk.LicenseAgentRuntimeHoursSoftLimitWarningText,
+		"AllocationReached": codersdk.LicenseAgentRuntimeHoursAllocationReachedWarningText,
+	}
+	for name, text := range runtimeTexts {
+		// isMutedWarning renders near-limit matches muted, and
+		// isAIGovernanceWarning matches either AI Governance prefix to
+		// suppress the banner's client-side over-limit fallback.
+		require.False(t, strings.HasPrefix(text, aiGovNearLimitPrefix),
+			"%s warning must not share the AI Governance near-limit prefix %q", name, aiGovNearLimitPrefix)
+		require.False(t, strings.HasPrefix(text, aiGovOverLimitPrefix),
+			"%s warning must not share the AI Governance over-limit prefix %q", name, aiGovOverLimitPrefix)
+	}
+
+	// isMutedWarning renders soft-limit matches muted and messageLink drops
+	// their sales link, so the allocation-reached warning must not match.
+	allocationReachedText := codersdk.LicenseAgentRuntimeHoursAllocationReachedWarningText
+	require.False(t, strings.HasPrefix(allocationReachedText, softLimitPrefix),
+		"the soft-limit prefix must not classify the allocation-reached warning")
+}