coder · jaaydenh · Jul 29, 2026 · Jul 23, 2026 · Jul 27, 2026 · Jul 29, 2026
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/codersdk/deployment.go b/codersdk/deployment.go
@@ -199,6 +199,12 @@ const (
 	FeatureBoundary               FeatureName = "boundary"
 	FeatureServiceAccounts        FeatureName = "service_accounts"
 	FeatureAIGovernanceUserLimit  FeatureName = "ai_governance_user_limit"
+	// FeatureAgentRuntimeHours is a usage period feature. It is never a
+	// license claim itself. It is populated from the
+	// agent_runtime_hours_allocation, agent_runtime_hours_limit_soft and
+	// agent_runtime_hours_limit_hard claims. Refer to
+	// enterprise/coderd/license/license.go for the license format.
+	FeatureAgentRuntimeHours FeatureName = "agent_runtime_hours"
 )
 
 var (
@@ -231,6 +237,7 @@ var (
 		FeatureBoundary,
 		FeatureServiceAccounts,
 		FeatureAIGovernanceUserLimit,
+		FeatureAgentRuntimeHours,
 	}
 
 	// FeatureNamesMap is a map of all feature names for quick lookups.
@@ -300,13 +307,15 @@ func (n FeatureName) UsesLimit() bool {
 		FeatureUserLimit:             true,
 		FeatureManagedAgentLimit:     true,
 		FeatureAIGovernanceUserLimit: true,
+		FeatureAgentRuntimeHours:     true,
 	}[n]
 }
 
 // UsesUsagePeriod returns true if the feature uses period-based usage limits.
 func (n FeatureName) UsesUsagePeriod() bool {
 	return map[FeatureName]bool{
 		FeatureManagedAgentLimit: true,
+		FeatureAgentRuntimeHours: true,
 	}[n]
 }
 
@@ -372,7 +381,18 @@ type Feature struct {
 	Entitlement Entitlement `json:"entitlement"`
 	Enabled     bool        `json:"enabled"`
 	Limit       *int64      `json:"limit,omitempty"`
-	Actual      *int64      `json:"actual,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
+	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"`
 
 	// Below is only for features that use usage periods.
 
@@ -385,6 +405,7 @@ type Feature struct {
 	//
 	// Only certain features set these fields:
 	// - FeatureManagedAgentLimit
+	// - FeatureAgentRuntimeHours
 	UsagePeriod *UsagePeriod `json:"usage_period,omitempty"`
 }
 
@@ -407,6 +428,8 @@ type UsagePeriod struct {
 // 5. The limit is greater
 // 6. Enabled is greater than disabled
 // 7. The actual is greater
+//
+// SoftLimit and HardLimit are not comparison inputs.
 func (f Feature) Compare(b Feature) int {
 	// For features with usage period constraints only, check the issued at and
 	// end dates.

diff --git a/codersdk/deployment_test.go b/codersdk/deployment_test.go
@@ -1002,6 +1002,38 @@ func TestFeatureComparison(t *testing.T) {
 			B:        codersdk.Feature{Entitlement: codersdk.EntitlementEntitled, Limit: nil, Actual: nil},
 			Expected: 1,
 		},
+		{
+			Name:     "SoftHardLimitsIgnored",
+			A:        codersdk.Feature{Entitlement: codersdk.EntitlementEntitled, Limit: ptr.Ref(int64(100)), SoftLimit: ptr.Ref(int64(80)), HardLimit: ptr.Ref(int64(120))},
+			B:        codersdk.Feature{Entitlement: codersdk.EntitlementEntitled, Limit: ptr.Ref(int64(100))},
+			Expected: 0,
+		},
+		{
+			Name: "NewerIssuedAtWinsOverSoftHardLimits",
+			A: codersdk.Feature{
+				Entitlement: codersdk.EntitlementEntitled,
+				Limit:       ptr.Ref(int64(50)),
+				SoftLimit:   ptr.Ref(int64(40)),
+				HardLimit:   ptr.Ref(int64(60)),
+				UsagePeriod: &codersdk.UsagePeriod{
+					IssuedAt: time.Date(2026, 2, 1, 0, 0, 0, 0, time.UTC),
+					Start:    time.Date(2026, 2, 1, 0, 0, 0, 0, time.UTC),
+					End:      time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC),
+				},
+			},
+			B: codersdk.Feature{
+				Entitlement: codersdk.EntitlementEntitled,
+				Limit:       ptr.Ref(int64(100)),
+				SoftLimit:   ptr.Ref(int64(80)),
+				HardLimit:   ptr.Ref(int64(120)),
+				UsagePeriod: &codersdk.UsagePeriod{
+					IssuedAt: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
+					Start:    time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
+					End:      time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC),
+				},
+			},
+			Expected: 1,
+		},
 	}
 
 	for _, tc := range testCases {

diff --git a/docs/reference/api/enterprise.md b/docs/reference/api/enterprise.md
diff --git a/docs/reference/api/schemas.md b/docs/reference/api/schemas.md