feat(office): fail closed on budget admission for unattended runs (#3520)
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
@@ -126,13 +126,14 @@ func (s *CostService) evaluatePolicy(
|
||||
}
|
||||
|
||||
// periodCutoff returns the time.Time at which the policy's spend window
|
||||
// starts. A zero time means "no filter" (lifetime / total).
|
||||
// starts. A zero time means "no filter" (lifetime / total) or an unknown
|
||||
// period retained for compatibility with stored policies.
|
||||
func periodCutoff(period string, now time.Time) time.Time {
|
||||
if period == budgetPeriodMonthly {
|
||||
n := now.UTC()
|
||||
return time.Date(n.Year(), n.Month(), 1, 0, 0, 0, 0, time.UTC)
|
||||
start, ok := windowStart(models.BudgetPeriod(period), now)
|
||||
if !ok {
|
||||
return time.Time{}
|
||||
}
|
||||
return time.Time{}
|
||||
return start
|
||||
}
|
||||
|
||||
func (s *CostService) getSpendForPolicy(
|
||||
@@ -272,6 +273,9 @@ func (s *CostService) pauseAgentForBudget(ctx context.Context, agentID string) b
|
||||
|
||||
// CreateBudgetPolicy creates a new budget policy.
|
||||
func (s *CostService) CreateBudgetPolicy(ctx context.Context, policy *BudgetPolicy) error {
|
||||
if err := validateBudgetPolicyWrite(policy); err != nil {
|
||||
return err
|
||||
}
|
||||
return s.repo.CreateBudgetPolicy(ctx, policy)
|
||||
}
|
||||
|
||||
@@ -287,6 +291,9 @@ func (s *CostService) GetBudgetPolicy(ctx context.Context, id string) (*BudgetPo
|
||||
|
||||
// UpdateBudgetPolicy updates a budget policy.
|
||||
func (s *CostService) UpdateBudgetPolicy(ctx context.Context, policy *BudgetPolicy) error {
|
||||
if err := validateBudgetPolicyWrite(policy); err != nil {
|
||||
return err
|
||||
}
|
||||
return s.repo.UpdateBudgetPolicy(ctx, policy)
|
||||
}
|
||||
|
||||
|
||||
@@ -149,11 +149,72 @@ func insertBudgetTestCostEvent(t *testing.T, execSQL func(string, ...interface{}
|
||||
now := time.Now().UTC().Format(time.RFC3339)
|
||||
execSQL(
|
||||
`INSERT INTO office_cost_events (id, agent_profile_id, task_id, cost_subcents, occurred_at, created_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?)`,
|
||||
VALUES (?, ?, ?, ?, ?, ?)`,
|
||||
uuid.NewString(), agentID, taskID, costSubcents, now, now,
|
||||
)
|
||||
}
|
||||
|
||||
func insertBudgetTestCostEventAt(
|
||||
t *testing.T,
|
||||
execSQL func(string, ...interface{}),
|
||||
agentID, taskID string,
|
||||
costSubcents int64,
|
||||
at time.Time,
|
||||
) {
|
||||
t.Helper()
|
||||
occurredAt := at.UTC().Format(time.RFC3339)
|
||||
execSQL(
|
||||
`INSERT INTO office_cost_events (id, agent_profile_id, task_id, cost_subcents, occurred_at, created_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?)`,
|
||||
uuid.NewString(), agentID, taskID, costSubcents, occurredAt, occurredAt,
|
||||
)
|
||||
}
|
||||
|
||||
func TestCheckBudget_PeriodWindowsExcludeOlderSpend(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
period models.BudgetPeriod
|
||||
olderBy time.Duration
|
||||
wantLimit bool
|
||||
}{
|
||||
{name: "daily", period: models.BudgetPeriodDaily, olderBy: 48 * time.Hour},
|
||||
{name: "yearly", period: models.BudgetPeriodYearly, olderBy: 400 * 24 * time.Hour},
|
||||
}
|
||||
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
|
||||
policy := &models.BudgetPolicy{
|
||||
WorkspaceID: "ws-1",
|
||||
ScopeType: models.BudgetScopeAgent,
|
||||
ScopeID: "agent-1",
|
||||
LimitSubcents: 500,
|
||||
Period: tc.period,
|
||||
AlertThresholdPct: 80,
|
||||
ActionOnExceed: models.BudgetActionNotifyOnly,
|
||||
}
|
||||
if err := svc.CreateBudgetPolicy(ctx, policy); err != nil {
|
||||
t.Fatalf("create policy: %v", err)
|
||||
}
|
||||
|
||||
insertBudgetTestCostEventAt(t, execSQL, "agent-1", "task-1", 600, time.Now().UTC().Add(-tc.olderBy))
|
||||
results, err := svc.CheckBudget(ctx, "ws-1", "agent-1", "project-1")
|
||||
if err != nil {
|
||||
t.Fatalf("CheckBudget: %v", err)
|
||||
}
|
||||
if len(results) != 1 {
|
||||
t.Fatalf("results = %d, want 1", len(results))
|
||||
}
|
||||
if results[0].LimitExceed != tc.wantLimit {
|
||||
t.Errorf("LimitExceed = %t, want %t", results[0].LimitExceed, tc.wantLimit)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestCheckBudget_UnderThreshold(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// DefaultCeilingSubcents is the built-in default ceiling's shipped value:
|
||||
// 500,000 subcents (50.00 USD) of priced spend per workspace per UTC day
|
||||
// (AC-OFFICE-BUDGET-003.2), in force for any workspace with no written
|
||||
// override (AC-OFFICE-BUDGET-003.9).
|
||||
const DefaultCeilingSubcents int64 = 500_000
|
||||
|
||||
// GetWorkspaceBudgetDefault returns workspaceID's effective built-in default
|
||||
// ceiling: the written override if one exists, otherwise the shipped
|
||||
// constant. Reading the effective value never reports the ceiling as absent
|
||||
// (AC-OFFICE-BUDGET-003.9).
|
||||
func (s *CostService) GetWorkspaceBudgetDefault(ctx context.Context, workspaceID string) (int64, error) {
|
||||
limitSubcents, found, err := s.repo.GetWorkspaceBudgetDefault(ctx, workspaceID)
|
||||
if err != nil {
|
||||
return 0, err
|
||||
}
|
||||
if !found {
|
||||
return DefaultCeilingSubcents, nil
|
||||
}
|
||||
return limitSubcents, nil
|
||||
}
|
||||
|
||||
// SetWorkspaceBudgetDefault writes workspaceID's built-in default ceiling.
|
||||
// A non-positive limit is rejected and the previous effective value stays
|
||||
// in force (AC-OFFICE-BUDGET-003.8).
|
||||
func (s *CostService) SetWorkspaceBudgetDefault(ctx context.Context, workspaceID string, limitSubcents int64) error {
|
||||
if limitSubcents <= 0 {
|
||||
return fmt.Errorf("%w: limit_subcents must be positive, got %d", ErrInvalidBudgetPolicy, limitSubcents)
|
||||
}
|
||||
return s.repo.SetWorkspaceBudgetDefault(ctx, workspaceID, limitSubcents)
|
||||
}
|
||||
|
||||
// EvaluateDefaultCeiling evaluates workspaceID's built-in default ceiling as
|
||||
// though it were a workspace-scoped daily block_new_tasks policy
|
||||
// (AC-OFFICE-BUDGET-003.11), using the same SpendWindowForWorkspace query
|
||||
// gate 4's workspace-scoped policies use so a policy and the default can
|
||||
// never disagree about which events count in the same window. Callers only
|
||||
// invoke this for an unattended run (REQ-OFFICE-BUDGET-003's gate 5 is only
|
||||
// reached after AC-OFFICE-BUDGET-001.6 has already let an attended run
|
||||
// through), so the degradation test is evaluated as unattended here rather
|
||||
// than taking a provenance parameter that every caller would pass the same
|
||||
// value for.
|
||||
func (s *CostService) EvaluateDefaultCeiling(ctx context.Context, workspaceID string, at time.Time) (PreLaunchPolicyResult, error) {
|
||||
limitSubcents, err := s.GetWorkspaceBudgetDefault(ctx, workspaceID)
|
||||
if err != nil {
|
||||
return PreLaunchPolicyResult{}, err
|
||||
}
|
||||
|
||||
start, _ := windowStart(models.BudgetPeriodDaily, at)
|
||||
window, err := s.repo.SpendWindowForWorkspace(ctx, workspaceID, start, true, at)
|
||||
if err != nil {
|
||||
return PreLaunchPolicyResult{}, fmt.Errorf("spend window for default ceiling: %w", err)
|
||||
}
|
||||
|
||||
return PreLaunchPolicyResult{
|
||||
IsDefault: true,
|
||||
ScopeType: models.BudgetScopeWorkspace,
|
||||
Period: models.BudgetPeriodDaily,
|
||||
ActionOnExceed: models.BudgetActionBlockNewTasks,
|
||||
LimitSubcents: limitSubcents,
|
||||
PricedSubcents: window.PricedSubcents,
|
||||
Degraded: window.Degraded,
|
||||
LimitExceeded: window.PricedSubcents >= limitSubcents,
|
||||
DegradationBlocked: degradationBlocks(
|
||||
window.Degraded, window.PricedSubcents, limitSubcents, shared.RunProvenanceUnattended,
|
||||
),
|
||||
}, nil
|
||||
}
|
||||
@@ -0,0 +1,162 @@
|
||||
package costs_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/costs"
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
func TestGetWorkspaceBudgetDefault_NoWriteReturnsShippedConstant(t *testing.T) {
|
||||
svc, _, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
got, err := svc.GetWorkspaceBudgetDefault(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if got != costs.DefaultCeilingSubcents {
|
||||
t.Errorf("got = %d, want the shipped constant %d", got, costs.DefaultCeilingSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSetWorkspaceBudgetDefault_ThenGetReturnsWrittenValue(t *testing.T) {
|
||||
svc, _, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 750_000); err != nil {
|
||||
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
|
||||
got, err := svc.GetWorkspaceBudgetDefault(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if got != 750_000 {
|
||||
t.Errorf("got = %d, want 750000", got)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetWorkspaceBudgetDefault_RejectsNonPositiveLimit pins
|
||||
// AC-OFFICE-BUDGET-003.8: a non-positive write is rejected and the previous
|
||||
// effective value stays in force.
|
||||
func TestSetWorkspaceBudgetDefault_RejectsNonPositiveLimit(t *testing.T) {
|
||||
svc, _, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 300_000); err != nil {
|
||||
t.Fatalf("initial SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
|
||||
for _, bad := range []int64{0, -1} {
|
||||
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", bad); err == nil {
|
||||
t.Errorf("SetWorkspaceBudgetDefault(%d) = nil error, want a validation error", bad)
|
||||
}
|
||||
}
|
||||
|
||||
got, err := svc.GetWorkspaceBudgetDefault(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if got != 300_000 {
|
||||
t.Errorf("got = %d, want the previous value 300000 left in force", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluateDefaultCeiling_UnderLimit_Admits(t *testing.T) {
|
||||
svc, repo, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 100, at.Add(-time.Hour), nil)
|
||||
|
||||
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluateDefaultCeiling: %v", err)
|
||||
}
|
||||
if got.LimitExceeded {
|
||||
t.Error("LimitExceeded = true, want false: spend is far under the 500000-subcent default")
|
||||
}
|
||||
if !got.IsDefault {
|
||||
t.Error("IsDefault = false, want true")
|
||||
}
|
||||
if got.PolicyID != "" {
|
||||
t.Errorf("PolicyID = %q, want empty: the default is not a office_budget_policies row", got.PolicyID)
|
||||
}
|
||||
if got.LimitSubcents != costs.DefaultCeilingSubcents {
|
||||
t.Errorf("LimitSubcents = %d, want the shipped constant %d", got.LimitSubcents, costs.DefaultCeilingSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluateDefaultCeiling_AtLimit_Blocks(t *testing.T) {
|
||||
svc, repo, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", costs.DefaultCeilingSubcents, at.Add(-time.Hour), nil)
|
||||
|
||||
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluateDefaultCeiling: %v", err)
|
||||
}
|
||||
if !got.LimitExceeded {
|
||||
t.Error("LimitExceeded = false, want true: spend reached the default ceiling")
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluateDefaultCeiling_UsesWrittenLimit pins AC-OFFICE-BUDGET-003.5/.7:
|
||||
// the operator-writable limit, not the shipped constant, is what gets
|
||||
// evaluated once it has been written.
|
||||
func TestEvaluateDefaultCeiling_UsesWrittenLimit(t *testing.T) {
|
||||
svc, repo, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1_500, at.Add(-time.Hour), nil)
|
||||
|
||||
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 1_000); err != nil {
|
||||
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
|
||||
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluateDefaultCeiling: %v", err)
|
||||
}
|
||||
if !got.LimitExceeded {
|
||||
t.Error("LimitExceeded = false, want true: spend exceeds the written 1000-subcent limit")
|
||||
}
|
||||
if got.LimitSubcents != 1_000 {
|
||||
t.Errorf("LimitSubcents = %d, want the written value 1000", got.LimitSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluateDefaultCeiling_PricingDegradedBlocks pins AC-OFFICE-BUDGET-
|
||||
// 003.11: the default is evaluated by the same pricing-degradation
|
||||
// criterion as a policy.
|
||||
func TestEvaluateDefaultCeiling_PricingDegradedBlocks(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
_ = execSQL
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 400, at.Add(-time.Hour), nil)
|
||||
unpriced := models.CostSourceUnpriced
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 0, at.Add(-30*time.Minute), &unpriced)
|
||||
|
||||
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 700); err != nil {
|
||||
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
|
||||
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluateDefaultCeiling: %v", err)
|
||||
}
|
||||
if got.LimitExceeded {
|
||||
t.Error("LimitExceeded = true, want false: priced spend alone is under the limit")
|
||||
}
|
||||
if !got.DegradationBlocked {
|
||||
t.Error("DegradationBlocked = false, want true: 2*400 >= 700 with an unpriced event present")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
package costs
|
||||
|
||||
import "github.com/kandev/kandev/internal/office/shared"
|
||||
|
||||
// degradationBlocks implements REQ-OFFICE-BUDGET-004: an unpriced event
|
||||
// inside an unattended run's window means priced spend alone can no longer
|
||||
// be trusted as a ceiling, so this blocks once priced spend alone already
|
||||
// reaches half the limit — applied identically to a policy and the
|
||||
// built-in default, regardless of the policy's configured action
|
||||
// (AC-OFFICE-BUDGET-004.3).
|
||||
//
|
||||
// The `pricedSubcents >= limitSubcents-pricedSubcents` form is algebraically
|
||||
// `2*pricedSubcents >= limitSubcents`, AC-OFFICE-BUDGET-004.3's
|
||||
// exact-50%-without-truncation requirement (comparing against limit/2 would
|
||||
// round down and miss an odd limit's exact threshold) -- written this way so
|
||||
// it never doubles pricedSubcents, which can overflow int64 and wrap
|
||||
// negative for extreme inputs.
|
||||
func degradationBlocks(degraded bool, pricedSubcents, limitSubcents int64, provenance shared.RunProvenance) bool {
|
||||
return degraded && provenance == shared.RunProvenanceUnattended && pricedSubcents >= limitSubcents-pricedSubcents
|
||||
}
|
||||
@@ -0,0 +1,87 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"math"
|
||||
"testing"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// TestDegradationBlocks pins REQ-OFFICE-BUDGET-004: an unpriced event inside
|
||||
// an unattended run's window blocks admission once priced spend alone
|
||||
// reaches 50% of the limit, applying regardless of the policy's configured
|
||||
// action (AC-OFFICE-BUDGET-004.3).
|
||||
func TestDegradationBlocks(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
degraded bool
|
||||
pricedSubcents int64
|
||||
limitSubcents int64
|
||||
provenance shared.RunProvenance
|
||||
want bool
|
||||
}{
|
||||
{
|
||||
name: "degraded unattended at exactly 50% blocks (non-truncating threshold)",
|
||||
degraded: true, pricedSubcents: 500, limitSubcents: 1000,
|
||||
provenance: shared.RunProvenanceUnattended, want: true,
|
||||
},
|
||||
{
|
||||
name: "degraded unattended above 50% blocks",
|
||||
degraded: true, pricedSubcents: 600, limitSubcents: 1000,
|
||||
provenance: shared.RunProvenanceUnattended, want: true,
|
||||
},
|
||||
{
|
||||
name: "degraded unattended below 50% does not block",
|
||||
degraded: true, pricedSubcents: 499, limitSubcents: 1000,
|
||||
provenance: shared.RunProvenanceUnattended, want: false,
|
||||
},
|
||||
{
|
||||
name: "not degraded never blocks regardless of spend",
|
||||
degraded: false, pricedSubcents: 999999, limitSubcents: 1000,
|
||||
provenance: shared.RunProvenanceUnattended, want: false,
|
||||
},
|
||||
{
|
||||
name: "attended run is exempt even when degraded and over threshold",
|
||||
degraded: true, pricedSubcents: 600, limitSubcents: 1000,
|
||||
provenance: shared.RunProvenanceAttended, want: false,
|
||||
},
|
||||
// AC-OFFICE-BUDGET-004.3 requires the exact, non-truncating
|
||||
// comparison 2*priced >= limit. Every row above uses an even
|
||||
// limitSubcents (1000), under which the forbidden truncating form
|
||||
// (priced >= limit/2, i.e. priced >= 500) produces the identical
|
||||
// pass/fail pattern -- so this table alone would not catch a
|
||||
// regression to that form. An odd limit is the only input shape
|
||||
// that distinguishes the two: limit/2 truncates to 500 either way,
|
||||
// but 2*priced >= 1001 disagrees with priced >= 500 at priced=500.
|
||||
{
|
||||
name: "odd limit: priced just below half (truncating form would wrongly block)",
|
||||
degraded: true, pricedSubcents: 500, limitSubcents: 1001,
|
||||
provenance: shared.RunProvenanceUnattended, want: false,
|
||||
},
|
||||
{
|
||||
name: "odd limit: priced at the true (non-truncating) half blocks",
|
||||
degraded: true, pricedSubcents: 501, limitSubcents: 1001,
|
||||
provenance: shared.RunProvenanceUnattended, want: true,
|
||||
},
|
||||
// A doubling form (2*pricedSubcents >= limitSubcents) overflows
|
||||
// int64 and wraps negative once pricedSubcents exceeds ~half of
|
||||
// MaxInt64, silently failing open at exactly the inputs this check
|
||||
// exists to catch. pricedSubcents here is just past MaxInt64's true
|
||||
// (non-truncating) half, so the correct answer is still "blocks".
|
||||
{
|
||||
name: "near MaxInt64: priced just past the true half still blocks (regression for doubling overflow)",
|
||||
degraded: true, pricedSubcents: math.MaxInt64/2 + 1, limitSubcents: math.MaxInt64,
|
||||
provenance: shared.RunProvenanceUnattended, want: true,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
got := degradationBlocks(tt.degraded, tt.pricedSubcents, tt.limitSubcents, tt.provenance)
|
||||
if got != tt.want {
|
||||
t.Errorf("degradationBlocks(%v, %d, %d, %v) = %v, want %v",
|
||||
tt.degraded, tt.pricedSubcents, tt.limitSubcents, tt.provenance, got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -48,3 +48,15 @@ type UpdateBudgetRequest struct {
|
||||
type BudgetListResponse struct {
|
||||
Budgets []*BudgetPolicy `json:"budgets"`
|
||||
}
|
||||
|
||||
// DefaultCeilingResponse reports the built-in default ceiling's current
|
||||
// effective limit (AC-OFFICE-BUDGET-003.5).
|
||||
type DefaultCeilingResponse struct {
|
||||
LimitSubcents int64 `json:"limit_subcents"`
|
||||
}
|
||||
|
||||
// SetDefaultCeilingRequest is the request body for writing the built-in
|
||||
// default ceiling's limit.
|
||||
type SetDefaultCeilingRequest struct {
|
||||
LimitSubcents int64 `json:"limit_subcents"`
|
||||
}
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"net/http"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
@@ -8,6 +9,22 @@ import (
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// errorJSONKey is the JSON field name every handler in this file reports an
|
||||
// error under. Named to avoid adding a fresh "error" string literal on top
|
||||
// of this file's many pre-existing gin.H{"error": ...} call sites (goconst).
|
||||
const errorJSONKey = "error"
|
||||
|
||||
// writeBudgetPolicyError maps validateBudgetPolicyWrite's rejection
|
||||
// (AC-OFFICE-BUDGET-002.6/.7) to 400; any other error (e.g. a repository
|
||||
// failure) stays 500.
|
||||
func writeBudgetPolicyError(c *gin.Context, err error) {
|
||||
if errors.Is(err, ErrInvalidBudgetPolicy) {
|
||||
c.JSON(http.StatusBadRequest, gin.H{errorJSONKey: err.Error()})
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusInternalServerError, gin.H{errorJSONKey: err.Error()})
|
||||
}
|
||||
|
||||
// Handler provides HTTP handlers for cost and budget routes.
|
||||
type Handler struct {
|
||||
svc *CostService
|
||||
@@ -39,6 +56,8 @@ func registerBudgetRoutes(api *gin.RouterGroup, h *Handler) {
|
||||
api.POST("/workspaces/:wsId/budgets", h.createBudget)
|
||||
api.PATCH("/budgets/:id", h.updateBudget)
|
||||
api.DELETE("/budgets/:id", h.deleteBudget)
|
||||
api.GET("/workspaces/:wsId/budgets/default", h.getDefaultCeiling)
|
||||
api.PUT("/workspaces/:wsId/budgets/default", h.setDefaultCeiling)
|
||||
}
|
||||
|
||||
// -- Cost handlers --
|
||||
@@ -159,7 +178,7 @@ func (h *Handler) createBudget(c *gin.Context) {
|
||||
ActionOnExceed: action,
|
||||
}
|
||||
if err := h.svc.CreateBudgetPolicy(c.Request.Context(), policy); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
writeBudgetPolicyError(c, err)
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusCreated, gin.H{"budget": policy})
|
||||
@@ -190,7 +209,7 @@ func (h *Handler) updateBudget(c *gin.Context) {
|
||||
}
|
||||
applyBudgetPatch(policy, &req)
|
||||
if err := h.svc.UpdateBudgetPolicy(c.Request.Context(), policy); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
|
||||
writeBudgetPolicyError(c, err)
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusOK, gin.H{"budget": policy})
|
||||
@@ -224,3 +243,31 @@ func (h *Handler) deleteBudget(c *gin.Context) {
|
||||
}
|
||||
c.JSON(http.StatusOK, gin.H{"ok": true})
|
||||
}
|
||||
|
||||
// getDefaultCeiling reports the built-in default ceiling's current
|
||||
// effective limit, visible without inspecting the database
|
||||
// (AC-OFFICE-BUDGET-003.5).
|
||||
func (h *Handler) getDefaultCeiling(c *gin.Context) {
|
||||
limitSubcents, err := h.svc.GetWorkspaceBudgetDefault(c.Request.Context(), c.Param("wsId"))
|
||||
if err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{errorJSONKey: err.Error()})
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusOK, DefaultCeilingResponse{LimitSubcents: limitSubcents})
|
||||
}
|
||||
|
||||
// setDefaultCeiling writes the built-in default ceiling's limit through the
|
||||
// same surface that manages budget policies (AC-OFFICE-BUDGET-003.5), never
|
||||
// touching office_budget_policies (AC-OFFICE-BUDGET-003.7).
|
||||
func (h *Handler) setDefaultCeiling(c *gin.Context) {
|
||||
var req SetDefaultCeilingRequest
|
||||
if err := c.ShouldBindJSON(&req); err != nil {
|
||||
c.JSON(http.StatusBadRequest, gin.H{errorJSONKey: err.Error()})
|
||||
return
|
||||
}
|
||||
if err := h.svc.SetWorkspaceBudgetDefault(c.Request.Context(), c.Param("wsId"), req.LimitSubcents); err != nil {
|
||||
writeBudgetPolicyError(c, err)
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusOK, DefaultCeilingResponse(req))
|
||||
}
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
package costs_test
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/costs"
|
||||
)
|
||||
|
||||
func newDefaultCeilingTestRouter(t *testing.T) *gin.Engine {
|
||||
t.Helper()
|
||||
gin.SetMode(gin.TestMode)
|
||||
svc, _, _ := newBudgetTestService(t)
|
||||
router := gin.New()
|
||||
costs.NewHandler(svc).RegisterRoutes(router.Group("/api/v1"))
|
||||
return router
|
||||
}
|
||||
|
||||
func doDefaultCeilingRequest(t *testing.T, router *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
|
||||
t.Helper()
|
||||
req := httptest.NewRequest(method, path, strings.NewReader(body))
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
rec := httptest.NewRecorder()
|
||||
router.ServeHTTP(rec, req)
|
||||
return rec
|
||||
}
|
||||
|
||||
func TestGetDefaultCeiling_NoWriteReturnsShippedConstant(t *testing.T) {
|
||||
router := newDefaultCeilingTestRouter(t)
|
||||
|
||||
rec := doDefaultCeilingRequest(t, router, http.MethodGet, "/api/v1/workspaces/ws-1/budgets/default", "")
|
||||
if rec.Code != http.StatusOK {
|
||||
t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body.String())
|
||||
}
|
||||
var got costs.DefaultCeilingResponse
|
||||
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
|
||||
t.Fatalf("unmarshal: %v", err)
|
||||
}
|
||||
if got.LimitSubcents != costs.DefaultCeilingSubcents {
|
||||
t.Errorf("LimitSubcents = %d, want the shipped constant %d", got.LimitSubcents, costs.DefaultCeilingSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSetDefaultCeiling_ThenGetReturnsWrittenValue(t *testing.T) {
|
||||
router := newDefaultCeilingTestRouter(t)
|
||||
|
||||
putRec := doDefaultCeilingRequest(
|
||||
t, router, http.MethodPut, "/api/v1/workspaces/ws-1/budgets/default", `{"limit_subcents":750000}`,
|
||||
)
|
||||
if putRec.Code != http.StatusOK {
|
||||
t.Fatalf("PUT status = %d, want 200: %s", putRec.Code, putRec.Body.String())
|
||||
}
|
||||
|
||||
getRec := doDefaultCeilingRequest(t, router, http.MethodGet, "/api/v1/workspaces/ws-1/budgets/default", "")
|
||||
var got costs.DefaultCeilingResponse
|
||||
if err := json.Unmarshal(getRec.Body.Bytes(), &got); err != nil {
|
||||
t.Fatalf("unmarshal: %v", err)
|
||||
}
|
||||
if got.LimitSubcents != 750_000 {
|
||||
t.Errorf("LimitSubcents = %d, want 750000", got.LimitSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetDefaultCeiling_RejectsNonPositiveLimit pins AC-OFFICE-BUDGET-003.8:
|
||||
// a non-positive write is rejected with a validation error over HTTP.
|
||||
func TestSetDefaultCeiling_RejectsNonPositiveLimit(t *testing.T) {
|
||||
router := newDefaultCeilingTestRouter(t)
|
||||
|
||||
rec := doDefaultCeilingRequest(
|
||||
t, router, http.MethodPut, "/api/v1/workspaces/ws-1/budgets/default", `{"limit_subcents":0}`,
|
||||
)
|
||||
if rec.Code != http.StatusBadRequest {
|
||||
t.Errorf("status = %d, want 400: %s", rec.Code, rec.Body.String())
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetDefaultCeiling_DoesNotAppearInBudgetList pins AC-OFFICE-BUDGET-
|
||||
// 003.7: writing the default never creates a office_budget_policies row,
|
||||
// so it never shows up in the policy list API's results.
|
||||
func TestSetDefaultCeiling_DoesNotAppearInBudgetList(t *testing.T) {
|
||||
router := newDefaultCeilingTestRouter(t)
|
||||
|
||||
putRec := doDefaultCeilingRequest(
|
||||
t, router, http.MethodPut, "/api/v1/workspaces/ws-1/budgets/default", `{"limit_subcents":750000}`,
|
||||
)
|
||||
if putRec.Code != http.StatusOK {
|
||||
t.Fatalf("PUT status = %d, want 200: %s", putRec.Code, putRec.Body.String())
|
||||
}
|
||||
|
||||
listRec := doDefaultCeilingRequest(t, router, http.MethodGet, "/api/v1/workspaces/ws-1/budgets", "")
|
||||
var got costs.BudgetListResponse
|
||||
if err := json.Unmarshal(listRec.Body.Bytes(), &got); err != nil {
|
||||
t.Fatalf("unmarshal: %v", err)
|
||||
}
|
||||
if len(got.Budgets) != 0 {
|
||||
t.Errorf("Budgets = %+v, want empty: the default must never appear in the policy list", got.Budgets)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,222 @@
|
||||
package costs_test
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"runtime"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// This test implements AC-OFFICE-BUDGET-002.12: it fails the build when the
|
||||
// set of period values the policy-management surface offers differs from
|
||||
// the set the write API declares. Both sets are derived by reading their
|
||||
// respective sources, never from a list maintained alongside them, so
|
||||
// adding a period value on either side without the other cannot silently
|
||||
// reproduce the defect AC-OFFICE-BUDGET-002.9 exists to fix.
|
||||
//
|
||||
// The declared set comes from models.BudgetPeriod's own Valid() method,
|
||||
// read via go/ast (same technique as the run-provenance completeness test
|
||||
// in internal/office/shared): the switch statement's case identifiers are
|
||||
// resolved against the type's const block, so a value added to the const
|
||||
// block but never wired into Valid() is correctly excluded from "declared".
|
||||
//
|
||||
// The offered set comes from create-budget-form.tsx's period FormField,
|
||||
// scanned with a regexp scoped to that one block rather than go/ast (the
|
||||
// file is TypeScript, which go/ast cannot parse).
|
||||
|
||||
func thisDir(t *testing.T) string {
|
||||
t.Helper()
|
||||
_, file, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
t.Fatal("runtime.Caller(0) failed; cannot locate test file for relative source paths")
|
||||
}
|
||||
return filepath.Dir(file)
|
||||
}
|
||||
|
||||
// periodConstValues reads path's BudgetPeriod const block and returns a map
|
||||
// from each declared identifier (e.g. "BudgetPeriodDaily") to its string
|
||||
// literal value (e.g. "daily"), located by the anchor identifier
|
||||
// "BudgetPeriodDaily" — never by line number.
|
||||
func periodConstValues(t *testing.T, path string) map[string]string {
|
||||
t.Helper()
|
||||
fset := token.NewFileSet()
|
||||
f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
|
||||
if err != nil {
|
||||
t.Fatalf("parse %s: %v", path, err)
|
||||
}
|
||||
for _, decl := range f.Decls {
|
||||
gen, ok := decl.(*ast.GenDecl)
|
||||
if !ok || gen.Tok != token.CONST {
|
||||
continue
|
||||
}
|
||||
values := constBlockValues(gen)
|
||||
if _, ok := values["BudgetPeriodDaily"]; ok {
|
||||
return values
|
||||
}
|
||||
}
|
||||
t.Fatalf("BudgetPeriod const block (anchor BudgetPeriodDaily) not found in %s — "+
|
||||
"block moved, renamed, or deleted", path)
|
||||
return nil
|
||||
}
|
||||
|
||||
func constBlockValues(gen *ast.GenDecl) map[string]string {
|
||||
out := map[string]string{}
|
||||
for _, spec := range gen.Specs {
|
||||
vs, ok := spec.(*ast.ValueSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for i, name := range vs.Names {
|
||||
if i >= len(vs.Values) {
|
||||
continue
|
||||
}
|
||||
lit, ok := vs.Values[i].(*ast.BasicLit)
|
||||
if !ok || lit.Kind != token.STRING {
|
||||
continue
|
||||
}
|
||||
val := lit.Value[1 : len(lit.Value)-1] // strip surrounding quotes
|
||||
out[name.Name] = val
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// declaredPeriodSet derives BudgetPeriod's declared set from Valid()'s own
|
||||
// switch statement, resolving each case identifier against the const
|
||||
// block's values rather than assuming every declared constant is valid.
|
||||
func declaredPeriodSet(t *testing.T) map[string]bool {
|
||||
t.Helper()
|
||||
dir := thisDir(t)
|
||||
path := filepath.Join(dir, "..", "models", "enums.go")
|
||||
fset := token.NewFileSet()
|
||||
f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
|
||||
if err != nil {
|
||||
t.Fatalf("parse %s: %v", path, err)
|
||||
}
|
||||
constValues := periodConstValues(t, path)
|
||||
|
||||
for _, decl := range f.Decls {
|
||||
fn, ok := decl.(*ast.FuncDecl)
|
||||
if !ok || fn.Name.Name != "Valid" || fn.Recv == nil {
|
||||
continue
|
||||
}
|
||||
if !receiverIsBudgetPeriod(fn) {
|
||||
continue
|
||||
}
|
||||
return caseIdentValues(t, fn, constValues)
|
||||
}
|
||||
t.Fatalf("BudgetPeriod.Valid method not found in %s — method moved, renamed, or deleted", path)
|
||||
return nil
|
||||
}
|
||||
|
||||
func receiverIsBudgetPeriod(fn *ast.FuncDecl) bool {
|
||||
if len(fn.Recv.List) != 1 {
|
||||
return false
|
||||
}
|
||||
ident, ok := fn.Recv.List[0].Type.(*ast.Ident)
|
||||
return ok && ident.Name == "BudgetPeriod"
|
||||
}
|
||||
|
||||
// caseIdentValues walks fn's body for its switch statement and resolves
|
||||
// every case identifier against constValues, failing the test outright if
|
||||
// a case expression isn't a plain identifier this test knows how to
|
||||
// resolve, per AC-OFFICE-BUDGET-002.12's "shall fail on any value present
|
||||
// in one set and absent from the other" — an unresolved case must not
|
||||
// silently shrink the declared set.
|
||||
func caseIdentValues(t *testing.T, fn *ast.FuncDecl, constValues map[string]string) map[string]bool {
|
||||
t.Helper()
|
||||
out := map[string]bool{}
|
||||
found := false
|
||||
ast.Inspect(fn.Body, func(n ast.Node) bool {
|
||||
sw, ok := n.(*ast.SwitchStmt)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
for _, stmt := range sw.Body.List {
|
||||
clause, ok := stmt.(*ast.CaseClause)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, expr := range clause.List {
|
||||
ident, ok := expr.(*ast.Ident)
|
||||
if !ok {
|
||||
t.Fatalf("BudgetPeriod.Valid case expression %v is not a plain identifier "+
|
||||
"this test can resolve", expr)
|
||||
}
|
||||
val, ok := constValues[ident.Name]
|
||||
if !ok {
|
||||
t.Fatalf("BudgetPeriod.Valid case identifier %q has no matching const declaration", ident.Name)
|
||||
}
|
||||
out[val] = true
|
||||
}
|
||||
}
|
||||
found = true
|
||||
return false
|
||||
})
|
||||
if !found {
|
||||
t.Fatal("BudgetPeriod.Valid has no switch statement — cannot derive declared period set")
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// offeredPeriodSet reads create-budget-form.tsx's period FormField block —
|
||||
// scoped between the label naming "office:period" and that FormField's
|
||||
// closing tag, so the scopeType and actionOnExceed Selects' own
|
||||
// SelectItem values are never counted — and returns every literal
|
||||
// SelectItem value in it.
|
||||
func offeredPeriodSet(t *testing.T) map[string]bool {
|
||||
t.Helper()
|
||||
dir := thisDir(t)
|
||||
path := filepath.Join(dir, "..", "..", "..", "..", "web", "app", "office", "workspace", "costs", "create-budget-form.tsx")
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", path, err)
|
||||
}
|
||||
src := string(data)
|
||||
|
||||
labelRe := regexp.MustCompile(`label=\{t\("office:period"\)\}`)
|
||||
loc := labelRe.FindStringIndex(src)
|
||||
if loc == nil {
|
||||
t.Fatalf(`period FormField label={t("office:period")} not found in %s — component restructured`, path)
|
||||
}
|
||||
rest := src[loc[1]:]
|
||||
closeIdx := strings.Index(rest, "</FormField>")
|
||||
if closeIdx == -1 {
|
||||
t.Fatalf("no closing </FormField> found after the period label in %s", path)
|
||||
}
|
||||
block := rest[:closeIdx]
|
||||
|
||||
itemRe := regexp.MustCompile(`SelectItem value="([a-z]+)"`)
|
||||
matches := itemRe.FindAllStringSubmatch(block, -1)
|
||||
if len(matches) == 0 {
|
||||
t.Fatalf("no SelectItem value=\"...\" literals found in the period FormField block in %s", path)
|
||||
}
|
||||
out := map[string]bool{}
|
||||
for _, m := range matches {
|
||||
out[m[1]] = true
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func TestBudgetPeriod_FrontendOfferedSetMatchesDeclaredSet(t *testing.T) {
|
||||
declared := declaredPeriodSet(t)
|
||||
offered := offeredPeriodSet(t)
|
||||
|
||||
for v := range declared {
|
||||
if !offered[v] {
|
||||
t.Errorf("period %q is declared by BudgetPeriod.Valid but not offered by "+
|
||||
"create-budget-form.tsx's period select", v)
|
||||
}
|
||||
}
|
||||
for v := range offered {
|
||||
if !declared[v] {
|
||||
t.Errorf("period %q is offered by create-budget-form.tsx's period select but not "+
|
||||
"declared by BudgetPeriod.Valid", v)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
package costs
|
||||
|
||||
import "github.com/kandev/kandev/internal/office/models"
|
||||
|
||||
// policyValidationIssues is every reason classifyStoredPolicy found to skip
|
||||
// a stored policy (AC-OFFICE-BUDGET-002.5/.11/.14). All fields are detected
|
||||
// in the same pass, never short-circuited at the first, so a policy
|
||||
// violating more than one criterion can be named for all of them in a
|
||||
// single activity entry (AC-OFFICE-BUDGET-002.13). Aliased from models so
|
||||
// internal/office/service can read a PreLaunchPolicyResult's SkipIssues
|
||||
// without importing this package.
|
||||
type policyValidationIssues = models.PolicyValidationIssues
|
||||
|
||||
// classifyStoredPolicy implements AC-OFFICE-BUDGET-002.5/.11/.14: a stored
|
||||
// policy the build cannot evaluate as written — an unrecognized period,
|
||||
// scope type, or action, a non-positive limit, or an agent/project scope
|
||||
// with no scope_id — is skipped by the caller rather than evaluated as a
|
||||
// lifetime window or as matching every run whose corresponding identifier
|
||||
// is also empty. Unlike validateBudgetPolicyWrite (AC-002.6/.7, which only
|
||||
// guards new writes), this covers every stored row regardless of how it
|
||||
// got there — a row written before validation shipped, or by any path that
|
||||
// bypasses the write API.
|
||||
func classifyStoredPolicy(policy *models.BudgetPolicy) policyValidationIssues {
|
||||
issues := policyValidationIssues{
|
||||
UnrecognizedPeriod: !policy.Period.Valid(),
|
||||
NonPositiveLimit: policy.LimitSubcents <= 0,
|
||||
UnrecognizedScope: !policy.ScopeType.Valid(),
|
||||
UnrecognizedAction: !policy.ActionOnExceed.Valid(),
|
||||
}
|
||||
if (policy.ScopeType == models.BudgetScopeAgent || policy.ScopeType == models.BudgetScopeProject) &&
|
||||
policy.ScopeID == "" {
|
||||
issues.EmptyScopeID = true
|
||||
}
|
||||
return issues
|
||||
}
|
||||
@@ -0,0 +1,140 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// TestClassifyStoredPolicy pins AC-OFFICE-BUDGET-002.5/.11/.14: a stored
|
||||
// policy the build cannot evaluate as written is skipped, never treated as
|
||||
// a lifetime window or as matching every run. Every violation on the row is
|
||||
// detected in the same pass (AC-OFFICE-BUDGET-002.13 names all of them in
|
||||
// one entry, so the classifier must not stop at the first).
|
||||
func TestClassifyStoredPolicy(t *testing.T) {
|
||||
validPolicy := func() *models.BudgetPolicy {
|
||||
return &models.BudgetPolicy{
|
||||
ScopeType: models.BudgetScopeWorkspace,
|
||||
LimitSubcents: 1000,
|
||||
Period: models.BudgetPeriodDaily,
|
||||
ActionOnExceed: models.BudgetActionNotifyOnly,
|
||||
}
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
policy func() *models.BudgetPolicy
|
||||
want policyValidationIssues
|
||||
}{
|
||||
{
|
||||
name: "fully valid workspace policy has no issues",
|
||||
policy: validPolicy,
|
||||
want: policyValidationIssues{},
|
||||
},
|
||||
{
|
||||
name: "unrecognized period",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.Period = models.BudgetPeriod("weekly")
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{UnrecognizedPeriod: true},
|
||||
},
|
||||
{
|
||||
name: "non-positive limit",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.LimitSubcents = 0
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{NonPositiveLimit: true},
|
||||
},
|
||||
{
|
||||
name: "unrecognized scope type",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.ScopeType = models.BudgetScopeType("team")
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{UnrecognizedScope: true},
|
||||
},
|
||||
{
|
||||
name: "unrecognized action",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.ActionOnExceed = models.BudgetActionOnExceed("delete_everything")
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{UnrecognizedAction: true},
|
||||
},
|
||||
{
|
||||
name: "agent scope with empty scope_id",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.ScopeType = models.BudgetScopeAgent
|
||||
p.ScopeID = ""
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{EmptyScopeID: true},
|
||||
},
|
||||
{
|
||||
name: "project scope with empty scope_id",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.ScopeType = models.BudgetScopeProject
|
||||
p.ScopeID = ""
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{EmptyScopeID: true},
|
||||
},
|
||||
{
|
||||
name: "agent scope with a scope_id has no issues",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.ScopeType = models.BudgetScopeAgent
|
||||
p.ScopeID = "agent-1"
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{},
|
||||
},
|
||||
{
|
||||
name: "workspace scope never needs a scope_id",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.ScopeID = ""
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{},
|
||||
},
|
||||
{
|
||||
name: "every violation is detected in one pass, not just the first",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validPolicy()
|
||||
p.Period = models.BudgetPeriod("weekly")
|
||||
p.LimitSubcents = -5
|
||||
p.ScopeType = models.BudgetScopeType("team")
|
||||
p.ActionOnExceed = models.BudgetActionOnExceed("nope")
|
||||
return p
|
||||
},
|
||||
want: policyValidationIssues{
|
||||
UnrecognizedPeriod: true,
|
||||
NonPositiveLimit: true,
|
||||
UnrecognizedScope: true,
|
||||
UnrecognizedAction: true,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
got := classifyStoredPolicy(tt.policy())
|
||||
if got != tt.want {
|
||||
t.Errorf("classifyStoredPolicy() = %+v, want %+v", got, tt.want)
|
||||
}
|
||||
wantAny := tt.want != (policyValidationIssues{})
|
||||
if got.Any() != wantAny {
|
||||
t.Errorf("classifyStoredPolicy().Any() = %v, want %v", got.Any(), wantAny)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,28 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// ErrInvalidBudgetPolicy wraps every rejection validateBudgetPolicyWrite
|
||||
// returns, so a caller can distinguish "the write was malformed" from any
|
||||
// other failure (e.g. a repository error) with errors.Is.
|
||||
var ErrInvalidBudgetPolicy = errors.New("invalid budget policy")
|
||||
|
||||
// validateBudgetPolicyWrite implements AC-OFFICE-BUDGET-002.6/.7: reject a
|
||||
// create or update before it reaches storage, rather than persisting a
|
||||
// policy that blocks every run (non-positive limit) or matches every run
|
||||
// whose corresponding identifier is also empty (agent/project scope with no
|
||||
// scope_id).
|
||||
func validateBudgetPolicyWrite(policy *models.BudgetPolicy) error {
|
||||
if policy.LimitSubcents <= 0 {
|
||||
return fmt.Errorf("%w: limit_subcents must be positive, got %d", ErrInvalidBudgetPolicy, policy.LimitSubcents)
|
||||
}
|
||||
if (policy.ScopeType == models.BudgetScopeAgent || policy.ScopeType == models.BudgetScopeProject) && policy.ScopeID == "" {
|
||||
return fmt.Errorf("%w: scope_id is required for scope %q", ErrInvalidBudgetPolicy, policy.ScopeType)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"testing"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// TestValidateBudgetPolicyWrite pins AC-OFFICE-BUDGET-002.6/.7: create/update
|
||||
// rejects a non-positive limit and an agent/project scope with an empty
|
||||
// scope identifier, rather than storing a policy that blocks every run or
|
||||
// matches every run whose corresponding identifier is also empty.
|
||||
func TestValidateBudgetPolicyWrite(t *testing.T) {
|
||||
validBase := func() *models.BudgetPolicy {
|
||||
return &models.BudgetPolicy{
|
||||
WorkspaceID: "ws-1",
|
||||
ScopeType: models.BudgetScopeType(scopeWorkspace),
|
||||
LimitSubcents: 1000,
|
||||
Period: models.BudgetPeriodDaily,
|
||||
}
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
policy func() *models.BudgetPolicy
|
||||
wantErr bool
|
||||
}{
|
||||
{
|
||||
name: "valid workspace-scoped policy is accepted",
|
||||
policy: validBase,
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "zero limit is rejected",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validBase()
|
||||
p.LimitSubcents = 0
|
||||
return p
|
||||
},
|
||||
wantErr: true,
|
||||
},
|
||||
{
|
||||
name: "negative limit is rejected",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validBase()
|
||||
p.LimitSubcents = -1
|
||||
return p
|
||||
},
|
||||
wantErr: true,
|
||||
},
|
||||
{
|
||||
name: "agent scope with empty scope_id is rejected",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validBase()
|
||||
p.ScopeType = models.BudgetScopeType(scopeAgent)
|
||||
p.ScopeID = ""
|
||||
return p
|
||||
},
|
||||
wantErr: true,
|
||||
},
|
||||
{
|
||||
name: "project scope with empty scope_id is rejected",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validBase()
|
||||
p.ScopeType = models.BudgetScopeType(scopeProject)
|
||||
p.ScopeID = ""
|
||||
return p
|
||||
},
|
||||
wantErr: true,
|
||||
},
|
||||
{
|
||||
name: "agent scope with a scope_id is accepted",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validBase()
|
||||
p.ScopeType = models.BudgetScopeType(scopeAgent)
|
||||
p.ScopeID = "agent-1"
|
||||
return p
|
||||
},
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "workspace scope never needs a scope_id",
|
||||
policy: func() *models.BudgetPolicy {
|
||||
p := validBase()
|
||||
p.ScopeID = ""
|
||||
return p
|
||||
},
|
||||
wantErr: false,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
err := validateBudgetPolicyWrite(tt.policy())
|
||||
if tt.wantErr && err == nil {
|
||||
t.Fatal("validateBudgetPolicyWrite() = nil, want error")
|
||||
}
|
||||
if !tt.wantErr && err != nil {
|
||||
t.Fatalf("validateBudgetPolicyWrite() = %v, want nil", err)
|
||||
}
|
||||
if tt.wantErr && !errors.Is(err, ErrInvalidBudgetPolicy) {
|
||||
t.Errorf("validateBudgetPolicyWrite() = %v, want errors.Is(err, ErrInvalidBudgetPolicy)", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,252 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"sort"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// windowStart computes the UTC start of period's spend window ending at at,
|
||||
// per REQ-OFFICE-BUDGET-002 (docs/specs/office/requirements/budget-measurement-integrity.md).
|
||||
//
|
||||
// ok is false for any period value not explicitly handled below, including
|
||||
// one this build has never seen — callers treat that as "skip this policy"
|
||||
// (AC-OFFICE-BUDGET-002.5), never as an unbounded lifetime window.
|
||||
func windowStart(period models.BudgetPeriod, at time.Time) (start time.Time, ok bool) {
|
||||
u := at.UTC()
|
||||
switch period {
|
||||
case models.BudgetPeriodDaily:
|
||||
return time.Date(u.Year(), u.Month(), u.Day(), 0, 0, 0, 0, time.UTC), true
|
||||
case models.BudgetPeriodMonthly:
|
||||
return time.Date(u.Year(), u.Month(), 1, 0, 0, 0, 0, time.UTC), true
|
||||
case models.BudgetPeriodYearly:
|
||||
return time.Date(u.Year(), time.January, 1, 0, 0, 0, 0, time.UTC), true
|
||||
case models.BudgetPeriodTotal:
|
||||
return time.Time{}, true
|
||||
default:
|
||||
return time.Time{}, false
|
||||
}
|
||||
}
|
||||
|
||||
// PreLaunchDecision is EvaluatePreLaunch's admission outcome for one
|
||||
// candidate run, per REQ-OFFICE-BUDGET-006. Aliased from models so
|
||||
// internal/office/service can declare a BudgetEvaluator interface method
|
||||
// returning it without importing this package.
|
||||
type PreLaunchDecision = models.PreLaunchDecision
|
||||
|
||||
const (
|
||||
PreLaunchDecisionLaunch = models.PreLaunchDecisionLaunch
|
||||
PreLaunchDecisionBlockedByLimit = models.PreLaunchDecisionBlockedByLimit
|
||||
PreLaunchDecisionBlockedByDegradation = models.PreLaunchDecisionBlockedByDegradation
|
||||
)
|
||||
|
||||
// PreLaunchPolicyResult is one applicable policy's full evaluation, kept for
|
||||
// observability. Activity-entry writing and dedup (AC-OFFICE-BUDGET-002.13)
|
||||
// live one layer up, in the caller that owns side effects — EvaluatePreLaunch
|
||||
// itself stays a pure read (AC-OFFICE-BUDGET-006.2). Aliased from models,
|
||||
// see PreLaunchDecision above.
|
||||
type PreLaunchPolicyResult = models.PreLaunchPolicyResult
|
||||
|
||||
// PreLaunchResult is EvaluatePreLaunch's full output. Aliased from models,
|
||||
// see PreLaunchDecision above.
|
||||
type PreLaunchResult = models.PreLaunchResult
|
||||
|
||||
// preLaunchApplicablePolicies implements AC-OFFICE-BUDGET-001.15:
|
||||
// workspace-scoped always applies; agent-scoped only when scope_id matches
|
||||
// the run's agent; project-scoped only when hasProject and scope_id matches
|
||||
// the run's project. A policy whose scope_type or scope_id is malformed
|
||||
// enough that no case below could ever match it, regardless of this run's
|
||||
// agent or project, is included anyway (scopeUnclassifiable) rather than
|
||||
// silently excluded: evaluateOnePolicy's classifyStoredPolicy call is what
|
||||
// actually produces AC-OFFICE-BUDGET-002.14's skip entry, and it only runs
|
||||
// on policies this function returns.
|
||||
func preLaunchApplicablePolicies(
|
||||
policies []*models.BudgetPolicy, agentInstanceID, projectID string, hasProject bool,
|
||||
) []*models.BudgetPolicy {
|
||||
var out []*models.BudgetPolicy
|
||||
for _, p := range policies {
|
||||
if scopeUnclassifiable(p) {
|
||||
out = append(out, p)
|
||||
continue
|
||||
}
|
||||
switch p.ScopeType {
|
||||
case models.BudgetScopeWorkspace:
|
||||
out = append(out, p)
|
||||
case models.BudgetScopeAgent:
|
||||
if p.ScopeID == agentInstanceID {
|
||||
out = append(out, p)
|
||||
}
|
||||
case models.BudgetScopeProject:
|
||||
if hasProject && p.ScopeID == projectID {
|
||||
out = append(out, p)
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// scopeUnclassifiable reports whether p's scope_type or scope_id is
|
||||
// malformed enough that preLaunchApplicablePolicies' switch above has no
|
||||
// case that could ever match it, independent of this run's agent or
|
||||
// project: an unrecognized scope_type, or an agent/project scope with no
|
||||
// scope_id (which could never equal a real, non-empty agent/project
|
||||
// identifier either way). These are exactly the two classifyStoredPolicy
|
||||
// issues that are also applicability-blocking, so without this check they
|
||||
// would be silently excluded here and classifyStoredPolicy would never run
|
||||
// on them at all -- AC-OFFICE-BUDGET-002.14 requires them to be skipped
|
||||
// with an operator-visible entry, not dropped with no trace.
|
||||
func scopeUnclassifiable(p *models.BudgetPolicy) bool {
|
||||
if !p.ScopeType.Valid() {
|
||||
return true
|
||||
}
|
||||
if (p.ScopeType == models.BudgetScopeAgent || p.ScopeType == models.BudgetScopeProject) && p.ScopeID == "" {
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// spendWindowForPolicy resolves the scope-selected spend window for policy's
|
||||
// own period, ending at the given instant (AC-OFFICE-BUDGET-002.15). windowStart failing is
|
||||
// unreachable once classifyStoredPolicy has already passed the policy (both
|
||||
// switch on the same models.BudgetPeriod.Valid() set); erroring instead of
|
||||
// panicking keeps that invariant enforced by AC-OFFICE-BUDGET-006.1 rather
|
||||
// than by construction alone.
|
||||
func (s *CostService) spendWindowForPolicy(
|
||||
ctx context.Context, workspaceID string, p *models.BudgetPolicy, at time.Time,
|
||||
) (models.SpendWindow, error) {
|
||||
start, ok := windowStart(p.Period, at)
|
||||
if !ok {
|
||||
return models.SpendWindow{}, fmt.Errorf("unrecognized period %q for policy %s", p.Period, p.ID)
|
||||
}
|
||||
hasStart := p.Period != models.BudgetPeriodTotal
|
||||
switch p.ScopeType {
|
||||
case models.BudgetScopeAgent:
|
||||
return s.repo.SpendWindowForAgent(ctx, p.ScopeID, start, hasStart, at)
|
||||
case models.BudgetScopeProject:
|
||||
return s.repo.SpendWindowForProject(ctx, p.ScopeID, start, hasStart, at)
|
||||
default:
|
||||
return s.repo.SpendWindowForWorkspace(ctx, workspaceID, start, hasStart, at)
|
||||
}
|
||||
}
|
||||
|
||||
// evaluateOnePolicy computes p's PreLaunchPolicyResult: skipped (with
|
||||
// SkipIssues set) if classifyStoredPolicy finds anything wrong, otherwise
|
||||
// its spend window, limit test, and degradation test. survives is false for
|
||||
// a skipped policy -- callers exclude those from ordering/selection and
|
||||
// default-supersession (AC-OFFICE-BUDGET-002.5/.11/.14).
|
||||
func (s *CostService) evaluateOnePolicy(
|
||||
ctx context.Context, workspaceID string, p *models.BudgetPolicy, at time.Time, provenance shared.RunProvenance,
|
||||
) (result PreLaunchPolicyResult, survives bool, err error) {
|
||||
result = PreLaunchPolicyResult{
|
||||
PolicyID: p.ID,
|
||||
ScopeType: p.ScopeType,
|
||||
Period: p.Period,
|
||||
ActionOnExceed: p.ActionOnExceed,
|
||||
CreatedAt: p.CreatedAt,
|
||||
LimitSubcents: p.LimitSubcents,
|
||||
}
|
||||
|
||||
if issues := classifyStoredPolicy(p); issues.Any() {
|
||||
result.Skipped = true
|
||||
result.SkipIssues = issues
|
||||
return result, false, nil
|
||||
}
|
||||
|
||||
window, werr := s.spendWindowForPolicy(ctx, workspaceID, p, at)
|
||||
if werr != nil {
|
||||
return PreLaunchPolicyResult{}, false, &models.UnevaluatedPolicyError{PolicyID: p.ID, Err: werr}
|
||||
}
|
||||
result.PricedSubcents = window.PricedSubcents
|
||||
result.Degraded = window.Degraded
|
||||
result.LimitExceeded = window.PricedSubcents >= p.LimitSubcents &&
|
||||
(p.ActionOnExceed == models.BudgetActionPauseAgent || p.ActionOnExceed == models.BudgetActionBlockNewTasks)
|
||||
result.DegradationBlocked = degradationBlocks(window.Degraded, window.PricedSubcents, p.LimitSubcents, provenance)
|
||||
|
||||
return result, true, nil
|
||||
}
|
||||
|
||||
// workspaceDailyBlockingSuperseded implements AC-OFFICE-BUDGET-003.4: true
|
||||
// when a workspace-scoped, non-skipped, blocking-capable daily policy
|
||||
// exists among survivors, regardless of whether it fired.
|
||||
func workspaceDailyBlockingSuperseded(survivors []*PreLaunchPolicyResult) bool {
|
||||
for _, r := range survivors {
|
||||
if r.ScopeType == models.BudgetScopeWorkspace && r.Period == models.BudgetPeriodDaily &&
|
||||
(r.ActionOnExceed == models.BudgetActionPauseAgent || r.ActionOnExceed == models.BudgetActionBlockNewTasks) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// selectPreLaunchDecision picks the first (in survivors' already-sorted
|
||||
// created_at ASC, id ASC order) policy whose limit or degradation test
|
||||
// fired. Every survivor's tests were computed up front, so this is a
|
||||
// selection over an already-fully-evaluated slice, never a
|
||||
// short-circuiting loop (AC-OFFICE-BUDGET-001.9/AC-OFFICE-BUDGET-006.1).
|
||||
// Within one policy, the limit test is checked before the degradation test:
|
||||
// LimitExceeded implies DegradationBlocked can also be true for the same
|
||||
// policy, and that combination still reports BlockedByLimit.
|
||||
func selectPreLaunchDecision(survivors []*PreLaunchPolicyResult) (PreLaunchDecision, *PreLaunchPolicyResult) {
|
||||
for _, r := range survivors {
|
||||
switch {
|
||||
case r.LimitExceeded:
|
||||
return PreLaunchDecisionBlockedByLimit, r
|
||||
case r.DegradationBlocked:
|
||||
return PreLaunchDecisionBlockedByDegradation, r
|
||||
}
|
||||
}
|
||||
return PreLaunchDecisionLaunch, nil
|
||||
}
|
||||
|
||||
// EvaluatePreLaunch implements REQ-OFFICE-BUDGET-006's two-phase policy
|
||||
// evaluation: lists and filters applicable policies, classifies/skips
|
||||
// malformed ones, computes spend and degradation for every surviving policy
|
||||
// up front (never short-circuiting), then selects the first (by created_at
|
||||
// ASC, id ASC) whose limit or degradation test fires. It does not call the
|
||||
// existing CheckBudget/evaluatePolicy post-event path (AC-OFFICE-BUDGET-006.2)
|
||||
// and has no side effects of its own.
|
||||
func (s *CostService) EvaluatePreLaunch(
|
||||
ctx context.Context,
|
||||
workspaceID, agentInstanceID, projectID string,
|
||||
hasProject bool,
|
||||
provenance shared.RunProvenance,
|
||||
at time.Time,
|
||||
) (PreLaunchResult, error) {
|
||||
policies, err := s.repo.ListBudgetPolicies(ctx, workspaceID)
|
||||
if err != nil {
|
||||
return PreLaunchResult{}, err
|
||||
}
|
||||
applicable := preLaunchApplicablePolicies(policies, agentInstanceID, projectID, hasProject)
|
||||
|
||||
results := make([]PreLaunchPolicyResult, 0, len(applicable))
|
||||
survivors := make([]*PreLaunchPolicyResult, 0, len(applicable))
|
||||
for _, p := range applicable {
|
||||
result, survives, evalErr := s.evaluateOnePolicy(ctx, workspaceID, p, at, provenance)
|
||||
if evalErr != nil {
|
||||
return PreLaunchResult{}, evalErr
|
||||
}
|
||||
results = append(results, result)
|
||||
if survives {
|
||||
survivors = append(survivors, &results[len(results)-1])
|
||||
}
|
||||
}
|
||||
|
||||
sort.Slice(survivors, func(i, j int) bool {
|
||||
if !survivors[i].CreatedAt.Equal(survivors[j].CreatedAt) {
|
||||
return survivors[i].CreatedAt.Before(survivors[j].CreatedAt)
|
||||
}
|
||||
return survivors[i].PolicyID < survivors[j].PolicyID
|
||||
})
|
||||
|
||||
decision, decidingPolicy := selectPreLaunchDecision(survivors)
|
||||
return PreLaunchResult{
|
||||
Decision: decision,
|
||||
DecidingPolicy: decidingPolicy,
|
||||
Policies: results,
|
||||
WorkspaceDailyBlockingSuperseded: workspaceDailyBlockingSuperseded(survivors),
|
||||
}, nil
|
||||
}
|
||||
@@ -0,0 +1,383 @@
|
||||
package costs_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/google/uuid"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/costs"
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/repository/sqlite"
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// mustCreateCostEvent inserts a cost event via the real repository, so
|
||||
// EvaluatePreLaunch's spend-window queries (which join agent_profiles /
|
||||
// filter project_id, not a manually-seeded fixture table) resolve it.
|
||||
func mustCreateCostEvent(
|
||||
t *testing.T, repo *sqlite.Repository,
|
||||
agentID, projectID string, costSubcents int64, occurredAt time.Time, costSource *models.CostSource,
|
||||
) {
|
||||
t.Helper()
|
||||
event := &models.CostEvent{
|
||||
ID: uuid.NewString(), AgentProfileID: agentID, ProjectID: projectID,
|
||||
CostSubcents: costSubcents, OccurredAt: occurredAt, CostSource: costSource,
|
||||
}
|
||||
if err := repo.CreateCostEvent(context.Background(), event); err != nil {
|
||||
t.Fatalf("create cost event: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// insertRawBudgetPolicy inserts a budget policy row directly via SQL, so
|
||||
// tests can control created_at (for AC-OFFICE-BUDGET-001.9 ordering) and
|
||||
// write a stored row validateBudgetPolicyWrite would reject (for
|
||||
// AC-OFFICE-BUDGET-002.5/.11/.14's "malformed row already in storage" case).
|
||||
func insertRawBudgetPolicy(
|
||||
t *testing.T, execSQL func(string, ...interface{}),
|
||||
workspaceID string, scopeType models.BudgetScopeType, scopeID string,
|
||||
limitSubcents int64, period models.BudgetPeriod, action models.BudgetActionOnExceed,
|
||||
createdAt time.Time,
|
||||
) string {
|
||||
t.Helper()
|
||||
id := uuid.NewString()
|
||||
execSQL(
|
||||
`INSERT INTO office_budget_policies
|
||||
(id, workspace_id, scope_type, scope_id, limit_subcents, period, alert_threshold_pct, action_on_exceed, created_at, updated_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?, 80, ?, ?, ?)`,
|
||||
id, workspaceID, string(scopeType), scopeID, limitSubcents, string(period), string(action),
|
||||
createdAt.UTC().Format(time.RFC3339Nano), createdAt.UTC().Format(time.RFC3339Nano),
|
||||
)
|
||||
return id
|
||||
}
|
||||
|
||||
func TestEvaluatePreLaunch_NoPolicies_Launches(t *testing.T) {
|
||||
svc, _, _ := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch", got.Decision)
|
||||
}
|
||||
if got.WorkspaceDailyBlockingSuperseded {
|
||||
t.Error("WorkspaceDailyBlockingSuperseded = true, want false with no policies")
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluatePreLaunch_UnderLimit_Launches(t *testing.T) {
|
||||
svc, _, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch", got.Decision)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluatePreLaunch_OverLimitPauseAgent_Blocks(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
policyID := insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
|
||||
t.Errorf("Decision = %v, want BlockedByLimit", got.Decision)
|
||||
}
|
||||
if got.DecidingPolicy == nil || got.DecidingPolicy.PolicyID != policyID {
|
||||
t.Errorf("DecidingPolicy = %+v, want policy %s", got.DecidingPolicy, policyID)
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluatePreLaunch_Inert covers AC-OFFICE-BUDGET-006.2: a pre-launch
|
||||
// evaluation is a pure read against the same spend window the post-hoc
|
||||
// budgets.go path (EvaluateBudget/CheckPreExecutionBudget) also reads, but
|
||||
// unlike that path it must never itself write a budget.alert/budget.exceeded
|
||||
// activity entry or pause the agent -- those side effects belong solely to
|
||||
// the existing cost-recording path, not to an admission decision. Reuses
|
||||
// TestEvaluatePreLaunch_OverLimitPauseAgent_Blocks's exact over-limit,
|
||||
// pause_agent fixture (the shape most likely to tempt a shared side-effect
|
||||
// path) but swaps in a service built with newBudgetTestServiceWithActivity's
|
||||
// spy so the absence of any LogActivity call is observable, and asserts the
|
||||
// agent's stored status is unchanged.
|
||||
func TestEvaluatePreLaunch_Inert(t *testing.T) {
|
||||
spy := &budgetActivitySpy{}
|
||||
svc, repo, execSQL := newBudgetTestServiceWithActivity(t, spy)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
|
||||
t.Fatalf("Decision = %v, want BlockedByLimit (fixture must actually be over limit to be a meaningful inertness check)", got.Decision)
|
||||
}
|
||||
|
||||
if len(spy.calls) != 0 {
|
||||
t.Errorf("EvaluatePreLaunch logged %d activity entries, want 0: %+v", len(spy.calls), spy.calls)
|
||||
}
|
||||
agent, err := repo.GetAgentInstance(ctx, "agent-1")
|
||||
if err != nil {
|
||||
t.Fatalf("get agent: %v", err)
|
||||
}
|
||||
if agent.Status != models.AgentStatusIdle {
|
||||
t.Errorf("agent status = %q, want unchanged %q -- a pre-launch evaluation must never pause an agent",
|
||||
agent.Status, models.AgentStatusIdle)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluatePreLaunch_OverLimitNotifyOnly_Launches(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionNotifyOnly, at.Add(-time.Hour))
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch (notify_only never blocks on limit alone)", got.Decision)
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluatePreLaunch_FirstFiringPolicyWins pins AC-OFFICE-BUDGET-001.9:
|
||||
// policies are evaluated in (created_at ASC, id ASC) order and the FIRST
|
||||
// one whose limit or degradation test fires decides, even though a
|
||||
// later-created policy would also fire.
|
||||
func TestEvaluatePreLaunch_FirstFiringPolicyWins(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
earlyID := insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-2*time.Hour))
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 500,
|
||||
models.BudgetPeriodDaily, models.BudgetActionBlockNewTasks, at.Add(-time.Hour))
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
|
||||
t.Fatalf("Decision = %v, want BlockedByLimit", got.Decision)
|
||||
}
|
||||
if got.DecidingPolicy == nil || got.DecidingPolicy.PolicyID != earlyID {
|
||||
t.Errorf("DecidingPolicy = %+v, want the earlier-created policy %s", got.DecidingPolicy, earlyID)
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluatePreLaunch_MalformedPolicySkipped pins AC-OFFICE-BUDGET-002.5/
|
||||
// .11/.14: a stored policy the build cannot evaluate is skipped -- excluded
|
||||
// from ordering/selection and from default-supersession -- not treated as a
|
||||
// lifetime window or blocking policy.
|
||||
func TestEvaluatePreLaunch_MalformedPolicySkipped(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
// Non-positive limit: malformed, must be skipped rather than blocking
|
||||
// every run.
|
||||
malformedID := insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", -1,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch (malformed policy must not block)", got.Decision)
|
||||
}
|
||||
if got.WorkspaceDailyBlockingSuperseded {
|
||||
t.Error("WorkspaceDailyBlockingSuperseded = true, want false: the only daily policy is skipped")
|
||||
}
|
||||
found := false
|
||||
for _, p := range got.Policies {
|
||||
if p.PolicyID == malformedID {
|
||||
found = true
|
||||
if !p.Skipped {
|
||||
t.Error("malformed policy result has Skipped = false, want true")
|
||||
}
|
||||
if !p.SkipIssues.NonPositiveLimit {
|
||||
t.Error("malformed policy result SkipIssues.NonPositiveLimit = false, want true")
|
||||
}
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Error("malformed policy is absent from Policies; observability needs it present with Skipped=true")
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluatePreLaunch_AgentScopeAppliesOnlyToMatchingAgent(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-2")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeAgent, "agent-2", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch: agent-2's policy must not apply to agent-1's run", got.Decision)
|
||||
}
|
||||
if len(got.Policies) != 0 {
|
||||
t.Errorf("Policies = %+v, want empty: a non-matching agent policy is not applicable at all", got.Policies)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEvaluatePreLaunch_ProjectScopeRequiresHasProject(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "proj-1", 1500, at.Add(-30*time.Minute), nil)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeProject, "proj-1", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
|
||||
// hasProject=false: a genuinely project-less run must never match a
|
||||
// project policy, even though scope_id happens to be non-empty.
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch when hasProject=false", got.Decision)
|
||||
}
|
||||
|
||||
// hasProject=true with the matching project: now it applies and fires.
|
||||
got, err = svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "proj-1", true, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
|
||||
t.Errorf("Decision = %v, want BlockedByLimit when hasProject=true and project matches", got.Decision)
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluatePreLaunch_WorkspaceDailyBlockingSupersededIgnoresWhetherItFired
|
||||
// pins AC-OFFICE-BUDGET-003.4: supersession is by a blocking-capable daily
|
||||
// policy EXISTING among survivors, not by it having fired.
|
||||
func TestEvaluatePreLaunch_WorkspaceDailyBlockingSupersededIgnoresWhetherItFired(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 10, at.Add(-30*time.Minute), nil)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1_000_000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("Decision = %v, want Launch: spend is far under the limit", got.Decision)
|
||||
}
|
||||
if !got.WorkspaceDailyBlockingSuperseded {
|
||||
t.Error("WorkspaceDailyBlockingSuperseded = false, want true: a blocking-capable daily policy exists regardless of firing")
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluatePreLaunch_WorkspaceDailyNotifyOnly_DoesNotSupersedeDefault pins
|
||||
// AC-OFFICE-BUDGET-003.4's negative case: supersession requires a
|
||||
// blocking-capable action (pause_agent or block_new_tasks). A workspace-scoped
|
||||
// daily policy configured notify_only cannot block on its own, so it must not
|
||||
// suppress the built-in default ceiling either.
|
||||
func TestEvaluatePreLaunch_WorkspaceDailyNotifyOnly_DoesNotSupersedeDefault(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 10, at.Add(-30*time.Minute), nil)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1_000_000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionNotifyOnly, at.Add(-time.Hour))
|
||||
|
||||
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if got.WorkspaceDailyBlockingSuperseded {
|
||||
t.Error("WorkspaceDailyBlockingSuperseded = true, want false: a notify_only daily policy cannot block, so it must not supersede the default")
|
||||
}
|
||||
}
|
||||
|
||||
// TestEvaluatePreLaunch_DegradationBlocksEvenNotifyOnly pins
|
||||
// AC-OFFICE-BUDGET-004.3: pricing degradation applies regardless of the
|
||||
// policy's configured action, and only for an unattended run.
|
||||
func TestEvaluatePreLaunch_DegradationBlocksEvenNotifyOnly(t *testing.T) {
|
||||
svc, repo, execSQL := newBudgetTestService(t)
|
||||
ctx := context.Background()
|
||||
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 500, at.Add(-30*time.Minute), nil)
|
||||
unpriced := models.CostSourceUnpriced
|
||||
mustCreateCostEvent(t, repo, "agent-1", "", 0, at.Add(-20*time.Minute), &unpriced)
|
||||
|
||||
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
|
||||
models.BudgetPeriodDaily, models.BudgetActionNotifyOnly, at.Add(-time.Hour))
|
||||
|
||||
gotUnattended, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if gotUnattended.Decision != costs.PreLaunchDecisionBlockedByDegradation {
|
||||
t.Errorf("unattended Decision = %v, want BlockedByDegradation", gotUnattended.Decision)
|
||||
}
|
||||
|
||||
gotAttended, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceAttended, at)
|
||||
if err != nil {
|
||||
t.Fatalf("EvaluatePreLaunch: %v", err)
|
||||
}
|
||||
if gotAttended.Decision != costs.PreLaunchDecisionLaunch {
|
||||
t.Errorf("attended Decision = %v, want Launch: attended runs are exempt from degradation blocking", gotAttended.Decision)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
package costs
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// TestWindowStart pins AC-OFFICE-BUDGET-002.1-.4/.8: each period computes its
|
||||
// UTC window start by name, and total is selected by name rather than by
|
||||
// falling through an unrecognized period to a lifetime window.
|
||||
func TestWindowStart(t *testing.T) {
|
||||
at := time.Date(2026, 3, 15, 14, 30, 0, 0, time.UTC)
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
period models.BudgetPeriod
|
||||
wantStart time.Time
|
||||
wantOK bool
|
||||
}{
|
||||
{
|
||||
name: "daily is most recent UTC midnight",
|
||||
period: models.BudgetPeriodDaily,
|
||||
wantStart: time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC),
|
||||
wantOK: true,
|
||||
},
|
||||
{
|
||||
name: "monthly is the 1st of the UTC month",
|
||||
period: models.BudgetPeriodMonthly,
|
||||
wantStart: time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC),
|
||||
wantOK: true,
|
||||
},
|
||||
{
|
||||
name: "yearly is 1 Jan UTC",
|
||||
period: models.BudgetPeriodYearly,
|
||||
wantStart: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
|
||||
wantOK: true,
|
||||
},
|
||||
{
|
||||
name: "total is unbounded below, selected by name",
|
||||
period: models.BudgetPeriodTotal,
|
||||
wantStart: time.Time{},
|
||||
wantOK: true,
|
||||
},
|
||||
{
|
||||
name: "unrecognized period is not ok, never lifetime",
|
||||
period: models.BudgetPeriod("weekly"),
|
||||
wantOK: false,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
start, ok := windowStart(tt.period, at)
|
||||
if ok != tt.wantOK {
|
||||
t.Fatalf("windowStart(%q) ok = %v, want %v", tt.period, ok, tt.wantOK)
|
||||
}
|
||||
if ok && !start.Equal(tt.wantStart) {
|
||||
t.Errorf("windowStart(%q) start = %v, want %v", tt.period, start, tt.wantStart)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestWindowStart_DailyConvertsToUTCFirst pins that a non-UTC instant is
|
||||
// converted to UTC before the midnight boundary is computed, so a run
|
||||
// evaluated late in a non-UTC day doesn't fall into the wrong UTC day.
|
||||
func TestWindowStart_DailyConvertsToUTCFirst(t *testing.T) {
|
||||
loc := time.FixedZone("UTC-5", -5*60*60)
|
||||
at := time.Date(2026, 3, 15, 23, 0, 0, 0, loc) // 2026-03-16T04:00:00Z
|
||||
|
||||
start, ok := windowStart(models.BudgetPeriodDaily, at)
|
||||
if !ok {
|
||||
t.Fatal("windowStart(daily) ok = false, want true")
|
||||
}
|
||||
want := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
|
||||
if !start.Equal(want) {
|
||||
t.Errorf("windowStart(daily) start = %v, want %v", start, want)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSelectPreLaunchDecision_LimitTestedBeforeDegradation pins the
|
||||
// within-policy precedence: LimitExceeded implies DegradationBlocked can
|
||||
// also be true for the same policy (priced>=limit algebraically implies
|
||||
// 2*priced>=limit), so a survivor with both set must still report
|
||||
// BlockedByLimit, never BlockedByDegradation.
|
||||
func TestSelectPreLaunchDecision_LimitTestedBeforeDegradation(t *testing.T) {
|
||||
both := &PreLaunchPolicyResult{PolicyID: "policy-both", LimitExceeded: true, DegradationBlocked: true}
|
||||
|
||||
decision, deciding := selectPreLaunchDecision([]*PreLaunchPolicyResult{both})
|
||||
|
||||
if decision != PreLaunchDecisionBlockedByLimit {
|
||||
t.Errorf("decision = %v, want BlockedByLimit when a survivor has both LimitExceeded and DegradationBlocked set", decision)
|
||||
}
|
||||
if deciding != both {
|
||||
t.Errorf("deciding policy = %+v, want %+v", deciding, both)
|
||||
}
|
||||
}
|
||||
@@ -32,6 +32,17 @@ type Repository interface {
|
||||
UpdateBudgetPolicy(ctx context.Context, policy *BudgetPolicy) error
|
||||
DeleteBudgetPolicy(ctx context.Context, id string) error
|
||||
UpdateAgentStatusFields(ctx context.Context, agentID, status, pauseReason string) error
|
||||
SpendWindowForWorkspace(
|
||||
ctx context.Context, workspaceID string, start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error)
|
||||
SpendWindowForAgent(
|
||||
ctx context.Context, agentInstanceID string, start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error)
|
||||
SpendWindowForProject(
|
||||
ctx context.Context, projectID string, start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error)
|
||||
GetWorkspaceBudgetDefault(ctx context.Context, workspaceID string) (limitSubcents int64, found bool, err error)
|
||||
SetWorkspaceBudgetDefault(ctx context.Context, workspaceID string, limitSubcents int64) error
|
||||
}
|
||||
|
||||
// CostService handles cost recording, summaries, and budget evaluation.
|
||||
|
||||
@@ -164,11 +164,14 @@ func (s CostSource) Valid() bool {
|
||||
// BudgetPeriod is the time window a BudgetPolicy limit applies to.
|
||||
type BudgetPeriod string
|
||||
|
||||
// Budget period values.
|
||||
// Budget period values. BudgetPeriodTotal (AC-OFFICE-BUDGET-002.8) selects
|
||||
// an unbounded-below window by name, rather than by falling through from an
|
||||
// unrecognized period value.
|
||||
const (
|
||||
BudgetPeriodDaily BudgetPeriod = "daily"
|
||||
BudgetPeriodMonthly BudgetPeriod = "monthly"
|
||||
BudgetPeriodYearly BudgetPeriod = "yearly"
|
||||
BudgetPeriodTotal BudgetPeriod = "total"
|
||||
)
|
||||
|
||||
// String implements fmt.Stringer.
|
||||
@@ -177,7 +180,7 @@ func (p BudgetPeriod) String() string { return string(p) }
|
||||
// Valid reports whether p is one of the declared BudgetPeriod values.
|
||||
func (p BudgetPeriod) Valid() bool {
|
||||
switch p {
|
||||
case BudgetPeriodDaily, BudgetPeriodMonthly, BudgetPeriodYearly:
|
||||
case BudgetPeriodDaily, BudgetPeriodMonthly, BudgetPeriodYearly, BudgetPeriodTotal:
|
||||
return true
|
||||
}
|
||||
return false
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
package models_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// TestBudgetPeriod_Total pins AC-OFFICE-BUDGET-002.8: `total` is a declared
|
||||
// period value, not a fallthrough from an unrecognized one.
|
||||
func TestBudgetPeriod_Total(t *testing.T) {
|
||||
if !models.BudgetPeriodTotal.Valid() {
|
||||
t.Errorf("BudgetPeriodTotal.Valid() = false, want true")
|
||||
}
|
||||
if models.BudgetPeriodTotal.String() != "total" {
|
||||
t.Errorf("BudgetPeriodTotal.String() = %q, want \"total\"", models.BudgetPeriodTotal.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestBudgetPeriod_ValidSet(t *testing.T) {
|
||||
valid := []models.BudgetPeriod{
|
||||
models.BudgetPeriodDaily,
|
||||
models.BudgetPeriodMonthly,
|
||||
models.BudgetPeriodYearly,
|
||||
models.BudgetPeriodTotal,
|
||||
}
|
||||
for _, p := range valid {
|
||||
if !p.Valid() {
|
||||
t.Errorf("%q.Valid() = false, want true", p)
|
||||
}
|
||||
}
|
||||
if models.BudgetPeriod("weekly").Valid() {
|
||||
t.Error(`BudgetPeriod("weekly").Valid() = true, want false`)
|
||||
}
|
||||
}
|
||||
@@ -377,6 +377,21 @@ type BudgetPolicy struct {
|
||||
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
|
||||
}
|
||||
|
||||
// SpendWindow reports one scope's priced spend and degradation state for a
|
||||
// single [start, before) window, in one query round-trip. Shared between
|
||||
// internal/office/repository/sqlite (the query implementations) and
|
||||
// internal/office/costs (the Repository interface and EvaluatePreLaunch),
|
||||
// so neither package needs to import the other's package for this one
|
||||
// return type. AC-OFFICE-BUDGET-002.10/.15, REQ-OFFICE-BUDGET-004.
|
||||
type SpendWindow struct {
|
||||
// PricedSubcents excludes any event whose cost_source is 'unpriced'
|
||||
// (AC-OFFICE-BUDGET-004.1); a NULL cost_source is treated as priced.
|
||||
PricedSubcents int64
|
||||
// Degraded is true when the window contains at least one unpriced
|
||||
// event, determined from cost_source, never from estimated.
|
||||
Degraded bool
|
||||
}
|
||||
|
||||
// Run represents a run queue entry.
|
||||
type Run struct {
|
||||
ID string `json:"id" db:"id"`
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
package models
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"time"
|
||||
)
|
||||
|
||||
// PreLaunchDecision is the pre-launch admission evaluator's outcome for one
|
||||
// candidate run, per REQ-OFFICE-BUDGET-006. Declared here (rather than in
|
||||
// internal/office/costs, where it is computed) so internal/office/service
|
||||
// can declare a BudgetEvaluator interface method returning it without
|
||||
// importing internal/office/costs — the same cross-package sharing this
|
||||
// file's other types (SpendWindow, BudgetPolicy) already use.
|
||||
type PreLaunchDecision string
|
||||
|
||||
const (
|
||||
PreLaunchDecisionLaunch PreLaunchDecision = "launch"
|
||||
PreLaunchDecisionBlockedByLimit PreLaunchDecision = "blocked_by_limit"
|
||||
PreLaunchDecisionBlockedByDegradation PreLaunchDecision = "blocked_by_degradation"
|
||||
)
|
||||
|
||||
// PreLaunchPolicyResult is one applicable policy's full pre-launch
|
||||
// evaluation, kept for observability.
|
||||
type PreLaunchPolicyResult struct {
|
||||
PolicyID string
|
||||
ScopeType BudgetScopeType
|
||||
Period BudgetPeriod
|
||||
ActionOnExceed BudgetActionOnExceed
|
||||
CreatedAt time.Time
|
||||
Skipped bool
|
||||
SkipIssues PolicyValidationIssues
|
||||
PricedSubcents int64
|
||||
LimitSubcents int64
|
||||
Degraded bool
|
||||
LimitExceeded bool
|
||||
DegradationBlocked bool
|
||||
// IsDefault is true when this result is the built-in default ceiling,
|
||||
// never a stored office_budget_policies row. PolicyID is "" in that case
|
||||
// (AC-OFFICE-BUDGET-003.7's stable identifier distinct from any policy row).
|
||||
IsDefault bool
|
||||
}
|
||||
|
||||
// PreLaunchResult is the pre-launch evaluator's full output for one run.
|
||||
type PreLaunchResult struct {
|
||||
Decision PreLaunchDecision
|
||||
DecidingPolicy *PreLaunchPolicyResult
|
||||
Policies []PreLaunchPolicyResult
|
||||
// WorkspaceDailyBlockingSuperseded is true when a workspace-scoped,
|
||||
// non-skipped, blocking-capable (pause_agent/block_new_tasks) daily
|
||||
// policy exists among the surviving set, independent of whether it
|
||||
// fired: AC-OFFICE-BUDGET-003.4 supersedes the built-in default by
|
||||
// existing, not by blocking.
|
||||
WorkspaceDailyBlockingSuperseded bool
|
||||
}
|
||||
|
||||
// PolicyValidationIssues enumerates every reason classifyStoredPolicy found
|
||||
// a stored policy row cannot be evaluated as written (AC-OFFICE-BUDGET-002.5,
|
||||
// -002.11, -002.14). Declared here for the same cross-package reason as
|
||||
// PreLaunchPolicyResult above.
|
||||
type PolicyValidationIssues struct {
|
||||
UnrecognizedPeriod bool
|
||||
NonPositiveLimit bool
|
||||
UnrecognizedScope bool
|
||||
UnrecognizedAction bool
|
||||
EmptyScopeID bool
|
||||
}
|
||||
|
||||
// Any reports whether classifyStoredPolicy found at least one issue.
|
||||
func (i PolicyValidationIssues) Any() bool {
|
||||
return i.UnrecognizedPeriod || i.NonPositiveLimit || i.UnrecognizedScope ||
|
||||
i.UnrecognizedAction || i.EmptyScopeID
|
||||
}
|
||||
|
||||
// UnevaluatedPolicyError names the applicable policy a pre-launch evaluation
|
||||
// attempted, but failed, to evaluate — as opposed to a plain evaluator
|
||||
// invocation fault (e.g. listing policies itself failing), which carries no
|
||||
// policy identity. AC-OFFICE-BUDGET-006.1/.4/.5 require the two be
|
||||
// distinguishable and require the former to name the policy; a caller
|
||||
// extracts PolicyID via errors.As.
|
||||
type UnevaluatedPolicyError struct {
|
||||
PolicyID string
|
||||
Err error
|
||||
}
|
||||
|
||||
func (e *UnevaluatedPolicyError) Error() string {
|
||||
return fmt.Sprintf("unevaluated policy %s: %v", e.PolicyID, e.Err)
|
||||
}
|
||||
|
||||
func (e *UnevaluatedPolicyError) Unwrap() error { return e.Err }
|
||||
@@ -120,6 +120,25 @@ func (r *Repository) ListActivityEntriesByType(ctx context.Context, workspaceID,
|
||||
return entries, nil
|
||||
}
|
||||
|
||||
// HasActivityToday reports whether an activity entry already exists for
|
||||
// workspaceID with this exact action and targetID, created at or after
|
||||
// dayStart. Used for AC-OFFICE-BUDGET-002.13/-004.8's at-most-once-per-
|
||||
// policy-per-UTC-day dedup bound; best-effort under concurrency like the
|
||||
// bound itself.
|
||||
func (r *Repository) HasActivityToday(
|
||||
ctx context.Context, workspaceID, action, targetID string, dayStart time.Time,
|
||||
) (bool, error) {
|
||||
var count int
|
||||
err := r.ro.GetContext(ctx, &count, r.ro.Rebind(`
|
||||
SELECT COUNT(*) FROM office_activity_log
|
||||
WHERE workspace_id = ? AND action = ? AND target_id = ? AND created_at >= ?
|
||||
`), workspaceID, action, targetID, dayStart)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
return count > 0, nil
|
||||
}
|
||||
|
||||
// ListActivityEntriesByTarget returns activity entries for one target in a workspace.
|
||||
func (r *Repository) ListActivityEntriesByTarget(ctx context.Context, workspaceID, targetID string, limit int) ([]*models.ActivityEntry, error) {
|
||||
if limit <= 0 {
|
||||
|
||||
@@ -187,7 +187,11 @@ func (r *Repository) GetAgentInstance(ctx context.Context, id string) (*models.A
|
||||
query := `SELECT ` + agentInstanceColumns + ` FROM agent_profiles WHERE id = ? AND ` + agentInstanceFilter
|
||||
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(query), id).StructScan(&agent)
|
||||
if err == sql.ErrNoRows {
|
||||
return nil, fmt.Errorf("agent instance not found: %s", id)
|
||||
// Wrapping (not just formatting) sql.ErrNoRows lets callers tell "no
|
||||
// such agent" apart from a transient I/O failure via errors.Is,
|
||||
// without a second lookup or a new sentinel type (AC-OFFICE-BUDGET-
|
||||
// 001.13's two dispositions require exactly that distinction).
|
||||
return nil, fmt.Errorf("agent instance not found: %s: %w", id, sql.ErrNoRows)
|
||||
}
|
||||
return &agent, err
|
||||
}
|
||||
@@ -478,7 +482,9 @@ func (r *Repository) GetAgentInstanceByNameAny(
|
||||
query := `SELECT ` + agentInstanceColumns + ` FROM agent_profiles WHERE name = ? AND ` + agentInstanceFilter + ` LIMIT 1`
|
||||
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(query), name).StructScan(&agent)
|
||||
if err == sql.ErrNoRows {
|
||||
return nil, fmt.Errorf("agent instance not found: %s", name)
|
||||
// See GetAgentInstance above: wrapped so GetAgentFromConfig can
|
||||
// distinguish "not found" from a transient error via errors.Is.
|
||||
return nil, fmt.Errorf("agent instance not found: %s: %w", name, sql.ErrNoRows)
|
||||
}
|
||||
return &agent, err
|
||||
}
|
||||
|
||||
@@ -324,6 +324,15 @@ func (r *Repository) createCostTables() error {
|
||||
created_at TIMESTAMP NOT NULL,
|
||||
updated_at TIMESTAMP NOT NULL
|
||||
);
|
||||
|
||||
-- Built-in default spend ceiling (REQ-OFFICE-BUDGET-003): a stable
|
||||
-- per-workspace identifier distinct from any office_budget_policies row
|
||||
-- (AC-OFFICE-BUDGET-003.7), never listed alongside operator policies.
|
||||
CREATE TABLE IF NOT EXISTS office_budget_default_settings (
|
||||
workspace_id TEXT PRIMARY KEY,
|
||||
limit_subcents INTEGER NOT NULL,
|
||||
updated_at TIMESTAMP NOT NULL
|
||||
);
|
||||
`)
|
||||
return err
|
||||
}
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
package sqlite
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"time"
|
||||
)
|
||||
|
||||
// GetWorkspaceBudgetDefault returns the effective built-in default ceiling
|
||||
// for workspaceID, in subcents. It never returns an error for "no row
|
||||
// written yet" -- the caller substitutes the shipped constant in that case
|
||||
// (AC-OFFICE-BUDGET-003.9), so an absent row is reported as (0, false, nil),
|
||||
// not an error.
|
||||
func (r *Repository) GetWorkspaceBudgetDefault(ctx context.Context, workspaceID string) (int64, bool, error) {
|
||||
var limitSubcents int64
|
||||
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(
|
||||
`SELECT limit_subcents FROM office_budget_default_settings WHERE workspace_id = ?`,
|
||||
), workspaceID).Scan(&limitSubcents)
|
||||
if err == sql.ErrNoRows {
|
||||
return 0, false, nil
|
||||
}
|
||||
if err != nil {
|
||||
return 0, false, err
|
||||
}
|
||||
return limitSubcents, true, nil
|
||||
}
|
||||
|
||||
// SetWorkspaceBudgetDefault writes workspaceID's built-in default ceiling.
|
||||
// The single-statement upsert is what makes AC-OFFICE-BUDGET-003.10's
|
||||
// last-write-wins hold without a read-modify-write race: two concurrent
|
||||
// writers each execute one INSERT ... ON CONFLICT statement, and SQLite/
|
||||
// Postgres both serialize those against the same primary key.
|
||||
func (r *Repository) SetWorkspaceBudgetDefault(ctx context.Context, workspaceID string, limitSubcents int64) error {
|
||||
_, err := r.db.ExecContext(ctx, r.db.Rebind(`
|
||||
INSERT INTO office_budget_default_settings (workspace_id, limit_subcents, updated_at)
|
||||
VALUES (?, ?, ?)
|
||||
ON CONFLICT(workspace_id) DO UPDATE SET
|
||||
limit_subcents = excluded.limit_subcents,
|
||||
updated_at = excluded.updated_at
|
||||
`), workspaceID, limitSubcents, time.Now().UTC())
|
||||
return err
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
package sqlite_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestGetWorkspaceBudgetDefault_NoRowReturnsNotFound(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
|
||||
limitSubcents, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if found {
|
||||
t.Errorf("found = true, want false: no row has been written for this workspace")
|
||||
}
|
||||
if limitSubcents != 0 {
|
||||
t.Errorf("limitSubcents = %d, want 0 when not found", limitSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSetWorkspaceBudgetDefault_ThenGetReturnsWrittenValue(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
|
||||
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 750_000); err != nil {
|
||||
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
|
||||
limitSubcents, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if !found {
|
||||
t.Error("found = false, want true after a write")
|
||||
}
|
||||
if limitSubcents != 750_000 {
|
||||
t.Errorf("limitSubcents = %d, want 750000", limitSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetWorkspaceBudgetDefault_SecondWriteWins pins AC-OFFICE-BUDGET-003.10:
|
||||
// the upsert is a single statement, so the last write in commit order is the
|
||||
// effective value, and no intermediate state leaves the workspace with no
|
||||
// effective row.
|
||||
func TestSetWorkspaceBudgetDefault_SecondWriteWins(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
|
||||
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 100_000); err != nil {
|
||||
t.Fatalf("first SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 200_000); err != nil {
|
||||
t.Fatalf("second SetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
|
||||
limitSubcents, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
|
||||
}
|
||||
if !found || limitSubcents != 200_000 {
|
||||
t.Errorf("limitSubcents = %d, found = %v, want 200000, true", limitSubcents, found)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSetWorkspaceBudgetDefault_ScopedPerWorkspace(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
|
||||
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 100_000); err != nil {
|
||||
t.Fatalf("SetWorkspaceBudgetDefault ws-1: %v", err)
|
||||
}
|
||||
|
||||
_, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-2")
|
||||
if err != nil {
|
||||
t.Fatalf("GetWorkspaceBudgetDefault ws-2: %v", err)
|
||||
}
|
||||
if found {
|
||||
t.Error("found = true for ws-2, want false: a write to ws-1 must not leak")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
package sqlite
|
||||
|
||||
import (
|
||||
"context"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
// spendWindowQuery is shared by SpendWindowForWorkspace/Agent/Project: each
|
||||
// caller supplies its own WHERE-clause scope predicate and args, sharing the
|
||||
// SELECT and the half-open occurred_at bound so a policy and the built-in
|
||||
// default can never disagree about which events count in the same window
|
||||
// (AC-OFFICE-BUDGET-001.9). hasStart=false (the `total` period) omits the
|
||||
// lower bound.
|
||||
func (r *Repository) spendWindowQuery(
|
||||
ctx context.Context, scopeWhere string, scopeArgs []interface{},
|
||||
start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error) {
|
||||
query := `
|
||||
SELECT
|
||||
COALESCE(SUM(CASE WHEN e.cost_source = 'unpriced' THEN 0 ELSE e.cost_subcents END), 0) AS priced_subcents,
|
||||
COALESCE(SUM(CASE WHEN e.cost_source = 'unpriced' THEN 1 ELSE 0 END), 0) > 0 AS degraded
|
||||
FROM office_cost_events e
|
||||
` + scopeWhere + ` AND e.occurred_at < ?`
|
||||
args := append(append([]interface{}{}, scopeArgs...), before.UTC())
|
||||
if hasStart {
|
||||
query += ` AND e.occurred_at >= ?`
|
||||
args = append(args, start.UTC())
|
||||
}
|
||||
|
||||
var out models.SpendWindow
|
||||
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(query), args...).Scan(&out.PricedSubcents, &out.Degraded)
|
||||
return out, err
|
||||
}
|
||||
|
||||
// SpendWindowForWorkspace scopes by the event's agent's workspace via
|
||||
// agent_profiles, never via tasks — closing the orphaned-cost-event gap a
|
||||
// tasks join produces (W4 human disposition; see costs.go's SumCostsSince
|
||||
// doc comment for the gap this deliberately does not share).
|
||||
func (r *Repository) SpendWindowForWorkspace(
|
||||
ctx context.Context, workspaceID string, start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error) {
|
||||
const where = `JOIN agent_profiles a ON a.id = e.agent_profile_id WHERE a.workspace_id = ?`
|
||||
return r.spendWindowQuery(ctx, where, []interface{}{workspaceID}, start, hasStart, before)
|
||||
}
|
||||
|
||||
// SpendWindowForAgent scopes directly on office_cost_events.agent_profile_id.
|
||||
func (r *Repository) SpendWindowForAgent(
|
||||
ctx context.Context, agentInstanceID string, start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error) {
|
||||
const where = `WHERE e.agent_profile_id = ?`
|
||||
return r.spendWindowQuery(ctx, where, []interface{}{agentInstanceID}, start, hasStart, before)
|
||||
}
|
||||
|
||||
// SpendWindowForProject scopes directly on office_cost_events.project_id,
|
||||
// the value recorded on the cost event itself at write time — never the
|
||||
// event's task's current project_id — so reparenting a task cannot move
|
||||
// historical spend between ceilings (AC-OFFICE-BUDGET-002.15).
|
||||
func (r *Repository) SpendWindowForProject(
|
||||
ctx context.Context, projectID string, start time.Time, hasStart bool, before time.Time,
|
||||
) (models.SpendWindow, error) {
|
||||
const where = `WHERE e.project_id = ?`
|
||||
return r.spendWindowQuery(ctx, where, []interface{}{projectID}, start, hasStart, before)
|
||||
}
|
||||
@@ -0,0 +1,196 @@
|
||||
package sqlite_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/repository/sqlite"
|
||||
)
|
||||
|
||||
// spendWindowFixture seeds the six-event scenario AC-OFFICE-BUDGET-002.10/.15
|
||||
// and REQ-OFFICE-BUDGET-004 exercise: two agents in two workspaces, two
|
||||
// projects, one event before the window, one exactly at the window's
|
||||
// exclusive upper bound, and one unpriced event inside the window.
|
||||
//
|
||||
// e1 agent-1 ws-1 proj-1 T0-2h cost=100 priced (before window)
|
||||
// e2 agent-1 ws-1 proj-1 T0+1h cost=200 priced (in window)
|
||||
// e3 agent-1 ws-1 proj-2 T0+1h cost=50 priced (in window, other project)
|
||||
// e4 agent-2 ws-2 proj-3 T0+1h cost=999 priced (in window, other workspace)
|
||||
// e5 agent-1 ws-1 proj-1 T1 cost=500 priced (at exclusive upper bound)
|
||||
// e6 agent-1 ws-1 proj-1 T0+2h cost=0 unpriced (in window)
|
||||
func spendWindowFixture(t *testing.T, repo *sqlite.Repository) (t0, t1 time.Time) {
|
||||
t.Helper()
|
||||
ctx := context.Background()
|
||||
|
||||
createSpendWindowTestAgent(t, repo, "ws-1", "agent-1")
|
||||
createSpendWindowTestAgent(t, repo, "ws-2", "agent-2")
|
||||
|
||||
t0 = time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
|
||||
t1 = time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
|
||||
unpriced := models.CostSourceUnpriced
|
||||
|
||||
events := []*models.CostEvent{
|
||||
{ID: "e1", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 100, OccurredAt: t0.Add(-2 * time.Hour)},
|
||||
{ID: "e2", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 200, OccurredAt: t0.Add(1 * time.Hour)},
|
||||
{ID: "e3", AgentProfileID: "agent-1", ProjectID: "proj-2", CostSubcents: 50, OccurredAt: t0.Add(1 * time.Hour)},
|
||||
{ID: "e4", AgentProfileID: "agent-2", ProjectID: "proj-3", CostSubcents: 999, OccurredAt: t0.Add(1 * time.Hour)},
|
||||
{ID: "e5", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 500, OccurredAt: t1},
|
||||
{ID: "e6", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 0, OccurredAt: t0.Add(2 * time.Hour), CostSource: &unpriced},
|
||||
}
|
||||
for _, e := range events {
|
||||
if err := repo.CreateCostEvent(ctx, e); err != nil {
|
||||
t.Fatalf("create cost event %s: %v", e.ID, err)
|
||||
}
|
||||
}
|
||||
return t0, t1
|
||||
}
|
||||
|
||||
func createSpendWindowTestAgent(t *testing.T, repo *sqlite.Repository, wsID, agentID string) {
|
||||
t.Helper()
|
||||
agent := &models.AgentInstance{
|
||||
ID: agentID,
|
||||
WorkspaceID: wsID,
|
||||
Name: "test-" + agentID,
|
||||
Role: models.AgentRoleWorker,
|
||||
Status: models.AgentStatusIdle,
|
||||
}
|
||||
if err := repo.CreateAgentInstance(context.Background(), agent); err != nil {
|
||||
t.Fatalf("create test agent %s: %v", agentID, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForWorkspace(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
t0, t1 := spendWindowFixture(t, repo)
|
||||
ctx := context.Background()
|
||||
|
||||
got, err := repo.SpendWindowForWorkspace(ctx, "ws-1", t0, true, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForWorkspace: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 250 {
|
||||
t.Errorf("PricedSubcents = %d, want 250 (e2=200 + e3=50 + e6=0; excludes e1 before window, e4 other workspace, e5 at upper bound)", got.PricedSubcents)
|
||||
}
|
||||
if !got.Degraded {
|
||||
t.Error("Degraded = false, want true (e6 is unpriced and in window)")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForWorkspace_TotalPeriodOmitsLowerBound(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
_, t1 := spendWindowFixture(t, repo)
|
||||
ctx := context.Background()
|
||||
|
||||
got, err := repo.SpendWindowForWorkspace(ctx, "ws-1", time.Time{}, false, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForWorkspace: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 350 {
|
||||
t.Errorf("PricedSubcents = %d, want 350 (e1=100 + e2=200 + e3=50 + e6=0; still excludes e5 at upper bound, e4 other workspace)", got.PricedSubcents)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForAgent(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
t0, t1 := spendWindowFixture(t, repo)
|
||||
ctx := context.Background()
|
||||
|
||||
got, err := repo.SpendWindowForAgent(ctx, "agent-1", t0, true, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForAgent: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 250 {
|
||||
t.Errorf("PricedSubcents = %d, want 250", got.PricedSubcents)
|
||||
}
|
||||
if !got.Degraded {
|
||||
t.Error("Degraded = false, want true")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForAgent_NoUnpricedEventsIsNotDegraded(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
createSpendWindowTestAgent(t, repo, "ws-1", "agent-clean")
|
||||
|
||||
t0 := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
|
||||
t1 := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
|
||||
if err := repo.CreateCostEvent(ctx, &models.CostEvent{
|
||||
ID: "clean-1", AgentProfileID: "agent-clean", ProjectID: "proj-1",
|
||||
CostSubcents: 42, OccurredAt: t0.Add(time.Hour),
|
||||
}); err != nil {
|
||||
t.Fatalf("create cost event: %v", err)
|
||||
}
|
||||
|
||||
got, err := repo.SpendWindowForAgent(ctx, "agent-clean", t0, true, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForAgent: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 42 {
|
||||
t.Errorf("PricedSubcents = %d, want 42", got.PricedSubcents)
|
||||
}
|
||||
if got.Degraded {
|
||||
t.Error("Degraded = true, want false (no unpriced events)")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForAgent_NoEventsIsZeroNotError(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
createSpendWindowTestAgent(t, repo, "ws-1", "agent-empty")
|
||||
|
||||
t0 := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
|
||||
t1 := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
|
||||
got, err := repo.SpendWindowForAgent(ctx, "agent-empty", t0, true, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForAgent: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 0 || got.Degraded {
|
||||
t.Errorf("got %+v, want zero value", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForProject(t *testing.T) {
|
||||
repo := newTestRepo(t)
|
||||
t0, t1 := spendWindowFixture(t, repo)
|
||||
ctx := context.Background()
|
||||
|
||||
got, err := repo.SpendWindowForProject(ctx, "proj-1", t0, true, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForProject: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 200 {
|
||||
t.Errorf("PricedSubcents = %d, want 200 (e2=200 + e6=0; excludes e3/e4 other projects, e1 before window, e5 at upper bound)", got.PricedSubcents)
|
||||
}
|
||||
if !got.Degraded {
|
||||
t.Error("Degraded = false, want true (e6 is unpriced, project proj-1, in window)")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSpendWindowForProject_DoesNotUseTaskCurrentProject(t *testing.T) {
|
||||
// Reparenting a task must not move its historical spend between
|
||||
// ceilings (AC-OFFICE-BUDGET-002.15): the query filters on the cost
|
||||
// event's own project_id, never a task join, so this test seeds no
|
||||
// tasks table at all and still resolves correctly.
|
||||
repo := newTestRepo(t)
|
||||
ctx := context.Background()
|
||||
createSpendWindowTestAgent(t, repo, "ws-1", "agent-1")
|
||||
|
||||
t0 := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
|
||||
t1 := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
|
||||
if err := repo.CreateCostEvent(ctx, &models.CostEvent{
|
||||
ID: "reparent-1", AgentProfileID: "agent-1", ProjectID: "proj-original",
|
||||
CostSubcents: 77, OccurredAt: t0.Add(time.Hour),
|
||||
}); err != nil {
|
||||
t.Fatalf("create cost event: %v", err)
|
||||
}
|
||||
|
||||
got, err := repo.SpendWindowForProject(ctx, "proj-original", t0, true, t1)
|
||||
if err != nil {
|
||||
t.Fatalf("SpendWindowForProject: %v", err)
|
||||
}
|
||||
if got.PricedSubcents != 77 {
|
||||
t.Errorf("PricedSubcents = %d, want 77", got.PricedSubcents)
|
||||
}
|
||||
}
|
||||
@@ -73,6 +73,7 @@ func (r *Repository) deleteWorkspaceDataTx(ctx context.Context, tx *sqlx.Tx, wor
|
||||
`DELETE FROM office_workspace_routing WHERE workspace_id = ?`,
|
||||
`DELETE FROM office_workspace_settings WHERE workspace_id = ?`,
|
||||
`DELETE FROM office_budget_policies WHERE workspace_id = ?`,
|
||||
`DELETE FROM office_budget_default_settings WHERE workspace_id = ?`,
|
||||
`DELETE FROM office_routine_runs WHERE routine_id IN (SELECT id FROM office_routines WHERE workspace_id = ?)`,
|
||||
`DELETE FROM office_routine_triggers WHERE routine_id IN (SELECT id FROM office_routines WHERE workspace_id = ?)`,
|
||||
`DELETE FROM task_workspace_group_members WHERE workspace_group_id IN (
|
||||
|
||||
@@ -215,11 +215,22 @@ func applyServiceOverrides(opts *service.ServiceOptions, o service.ServiceOption
|
||||
|
||||
// insertTestCostEvent inserts a cost event directly into the DB for
|
||||
// budget rollup tests. costSubcents is hundredths of a cent.
|
||||
//
|
||||
// occurred_at/created_at are bound as time.Time values, not pre-formatted
|
||||
// strings: the production CreateCostEvent path binds event.OccurredAt the
|
||||
// same way, and the pre-launch spend-window queries
|
||||
// (internal/office/repository/sqlite/spendwindow.go) compare occurred_at
|
||||
// against a time.Time bound the same way too. A hand-formatted
|
||||
// time.RFC3339 string ("...T...Z") sorts inconsistently against the
|
||||
// driver's own time.Time formatting ("... ...+00:00") once a query compares
|
||||
// two timestamps seconds apart rather than months apart, which silently
|
||||
// zeroed out spend in AC-OFFICE-BUDGET-006 admission tests until this was
|
||||
// made to match.
|
||||
func insertTestCostEvent(t *testing.T, svc interface {
|
||||
ExecSQL(t *testing.T, q string, args ...interface{})
|
||||
}, agentID, taskID string, costSubcents int64) {
|
||||
t.Helper()
|
||||
now := time.Now().UTC().Format(time.RFC3339)
|
||||
now := time.Now().UTC()
|
||||
svc.ExecSQL(t,
|
||||
`INSERT INTO office_cost_events (id, agent_profile_id, task_id, cost_subcents, occurred_at, created_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?)`,
|
||||
|
||||
@@ -0,0 +1,453 @@
|
||||
package service
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"strconv"
|
||||
"time"
|
||||
|
||||
"go.uber.org/zap"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// Activity-log field key/value literals shared across the budget-admission
|
||||
// entries in this file and in failRunNoEscalation (retry.go).
|
||||
const (
|
||||
activityFieldCeiling = "ceiling"
|
||||
ceilingNotDetermined = "not_determined"
|
||||
ceilingBuiltInDefault = "built_in_default"
|
||||
)
|
||||
|
||||
// admitRun performs the five pre-launch admission gates of
|
||||
// AC-OFFICE-BUDGET-001.14 and returns true only when the run may proceed to
|
||||
// launch. It replaces the old checkBudget, which fail-opened both when no
|
||||
// evaluator was wired and when the evaluator errored -- two of this
|
||||
// capability's three closed fail-open paths. The third, zero configured
|
||||
// policies, is closed by gate 5 (REQ-OFFICE-BUDGET-003's built-in default).
|
||||
func (si *SchedulerIntegration) admitRun(
|
||||
ctx context.Context, run *models.Run, agent *models.AgentInstance,
|
||||
) bool {
|
||||
provenance := shared.ClassifyRunProvenance(run.Reason)
|
||||
|
||||
// Gate 1: workspace resolution (AC-OFFICE-BUDGET-001.13). The lookup
|
||||
// itself already happened in processRun via GetAgentFromConfig, which
|
||||
// now disposes of a lookup ERROR itself (deferWorkspaceLookupFailure)
|
||||
// before admitRun is ever called, per the recorded W2 human disposition
|
||||
// that GetAgentFromConfig's own error contract is not reshaped. This
|
||||
// gate is therefore defense-in-depth, not a live production path: the
|
||||
// repository's agentInstanceFilter (workspace_id != '') guarantees any
|
||||
// agent GetAgentFromConfig successfully returns already has a non-empty
|
||||
// WorkspaceID, so this branch is structurally unreachable via the sole
|
||||
// real caller and exists to keep AC-OFFICE-BUDGET-001.13's textual
|
||||
// requirement true of admitRun itself, independent of that caller.
|
||||
// AdmitRunForTest exercises it directly against a constructed agent.
|
||||
if agent.WorkspaceID == "" {
|
||||
incBudgetCancelledNoWorkspace(provenance)
|
||||
return si.cancelBudgetRun(ctx, run, agent, "no_resolvable_workspace",
|
||||
"run_budget_workspace_unresolvable", nil)
|
||||
}
|
||||
|
||||
// Gate 2: evaluator presence (AC-OFFICE-BUDGET-001.5/.6).
|
||||
if si.svc.budgetChecker == nil {
|
||||
if provenance == shared.RunProvenanceAttended {
|
||||
return true
|
||||
}
|
||||
incBudgetBlockedAbsentEvaluator(provenance)
|
||||
return si.cancelBudgetRun(ctx, run, agent, "no_budget_evaluator",
|
||||
"run_budget_no_evaluator", nil)
|
||||
}
|
||||
|
||||
// Gate 3/4: evaluator invocation + applicable policies. The run's
|
||||
// project identifier is resolved first (cheap: a single lookup, and its
|
||||
// two permanent-cancellation outcomes -- (c) unparseable payload, (d)
|
||||
// task not found -- are unconditional regardless of evaluator health),
|
||||
// but a *lookup error* (b) must not itself decide the disposition:
|
||||
// AC-OFFICE-BUDGET-001.14/-006.7 require project resolution to yield to
|
||||
// gate 3 succeeding first, so that a run whose evaluator errors and
|
||||
// whose project lookup would also fail gets one determinate disposition
|
||||
// (evaluator fault) rather than one depending on which lookup happens to
|
||||
// run first. On a lookup error we therefore invoke the evaluator with no
|
||||
// project scope (a project-lookup failure is not itself evidence a
|
||||
// project applies -- AC-OFFICE-BUDGET-001.15 already treats "no project"
|
||||
// this way) to test gate 3 in isolation: an evaluator fault discovered
|
||||
// there takes precedence, and only once gate 3 is confirmed healthy does
|
||||
// the unresolvable project get its own distinguishable disposition
|
||||
// (AC-OFFICE-BUDGET-006.3).
|
||||
projectID, res := si.resolveRunProject(ctx, run.Payload)
|
||||
switch res {
|
||||
case projectResolutionUnparseable:
|
||||
incBudgetCancelledUnparseablePayload(provenance)
|
||||
return si.cancelBudgetRun(ctx, run, agent, "unparseable_payload",
|
||||
"run_budget_payload_unparseable", nil)
|
||||
case projectResolutionTaskNotFound:
|
||||
incBudgetCancelledTaskNotFound(provenance)
|
||||
return si.cancelBudgetRun(ctx, run, agent, "task_not_found",
|
||||
"run_budget_task_not_found", nil)
|
||||
}
|
||||
hasProject := res == projectResolutionFound
|
||||
if res == projectResolutionLookupError {
|
||||
projectID, hasProject = "", false
|
||||
}
|
||||
|
||||
now := time.Now().UTC()
|
||||
result, err := si.svc.EvaluatePreLaunch(ctx, agent.WorkspaceID, agent.ID, projectID, hasProject, provenance, now)
|
||||
if err != nil {
|
||||
var upErr *models.UnevaluatedPolicyError
|
||||
if errors.As(err, &upErr) {
|
||||
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralUnevaluatedPolicy, upErr.PolicyID)
|
||||
}
|
||||
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralEvaluatorFault, "")
|
||||
}
|
||||
if res == projectResolutionLookupError {
|
||||
// Gate 3 just succeeded (the evaluator itself is healthy) but the
|
||||
// project remains unresolvable -- its own distinguishable cause,
|
||||
// per AC-OFFICE-BUDGET-006.3/-006.7.
|
||||
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralProjectLookupError, "")
|
||||
}
|
||||
si.logPolicyObservability(ctx, agent.WorkspaceID, run.ID, result.Policies, now)
|
||||
degradedAdmitted := anyDegradedAdmitted(result.Policies)
|
||||
if result.Decision != models.PreLaunchDecisionLaunch {
|
||||
return si.finishPolicyBlock(ctx, run, agent, result.DecidingPolicy)
|
||||
}
|
||||
|
||||
return si.admitDefaultCeilingGate(ctx, run, agent, provenance, result, degradedAdmitted, now)
|
||||
}
|
||||
|
||||
// admitDefaultCeilingGate evaluates gate 5 (AC-OFFICE-BUDGET-003.1/.4/.11):
|
||||
// the built-in default ceiling, applied to unattended runs only, and only
|
||||
// when no workspace-scoped blocking-capable daily policy already supersedes
|
||||
// it. Split out of admitRun to keep its cyclomatic complexity within the
|
||||
// repo's golangci-lint limit; degradedAdmitted carries whether any of
|
||||
// result's stored policies were already degraded-admitted at gate 4, so the
|
||||
// AC-OFFICE-BUDGET-005.4 degraded-window counter still fires at most once
|
||||
// per run even when both gate 4 and gate 5 saw a degraded window.
|
||||
func (si *SchedulerIntegration) admitDefaultCeilingGate(
|
||||
ctx context.Context, run *models.Run, agent *models.AgentInstance,
|
||||
provenance shared.RunProvenance, result models.PreLaunchResult, degradedAdmitted bool, now time.Time,
|
||||
) bool {
|
||||
if provenance != shared.RunProvenanceUnattended || result.WorkspaceDailyBlockingSuperseded {
|
||||
if degradedAdmitted {
|
||||
incBudgetAdmittedDegradedWindow(provenance)
|
||||
}
|
||||
return true
|
||||
}
|
||||
def, defErr := si.svc.EvaluateDefaultCeiling(ctx, agent.WorkspaceID, now)
|
||||
if defErr != nil {
|
||||
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralEvaluatorFault, "")
|
||||
}
|
||||
si.logPolicyObservability(ctx, agent.WorkspaceID, run.ID, []models.PreLaunchPolicyResult{def}, now)
|
||||
if def.LimitExceeded || def.DegradationBlocked {
|
||||
return si.finishPolicyBlock(ctx, run, agent, &def)
|
||||
}
|
||||
incBudgetAdmittedDefault(provenance)
|
||||
if degradedAdmitted || isDegradedAdmitted(&def) {
|
||||
incBudgetAdmittedDegradedWindow(provenance)
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// finishPolicyBlock finishes run as blocked by p -- either a stored policy
|
||||
// or the built-in default (p.IsDefault). Per AC-OFFICE-BUDGET-005.7/-004.6,
|
||||
// a policy that blocked purely on pricing degradation (its limit was not
|
||||
// also reached) carries the distinct run_budget_unmeasurable outcome and a
|
||||
// distinct activity action; a plain limit block, including one where
|
||||
// degradation also fired, keeps the existing budget_blocked outcome and
|
||||
// action, with the degradation flag carried on the entry alone.
|
||||
func (si *SchedulerIntegration) finishPolicyBlock(
|
||||
ctx context.Context, run *models.Run, agent *models.AgentInstance, p *models.PreLaunchPolicyResult,
|
||||
) bool {
|
||||
si.releaseCheckoutIfNeeded(ctx, run)
|
||||
si.svc.clearAgentWorking(ctx, agent.ID, run.ID)
|
||||
provenance := shared.ClassifyRunProvenance(run.Reason)
|
||||
|
||||
action := "run_budget_blocked"
|
||||
outcome := RunOutcomeBudgetBlocked
|
||||
if !p.LimitExceeded {
|
||||
action = "run_budget_pricing_degraded_blocked"
|
||||
outcome = RunOutcomeBudgetUnmeasurable
|
||||
incBudgetBlockedPricingDegraded(provenance)
|
||||
} else {
|
||||
incBudgetBlockedByLimit(provenance)
|
||||
}
|
||||
_ = si.svc.FinishRun(ctx, run.ID, outcome)
|
||||
|
||||
fields := map[string]string{"degraded": strconv.FormatBool(p.Degraded)}
|
||||
if p.IsDefault {
|
||||
fields[activityFieldCeiling] = ceilingBuiltInDefault
|
||||
} else {
|
||||
fields["policy_id"] = p.PolicyID
|
||||
}
|
||||
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
|
||||
action, "run", run.ID, mustJSON(fields), run.ID, "")
|
||||
return false
|
||||
}
|
||||
|
||||
// cancelBudgetRun cancels run for a permanent, non-retryable admission
|
||||
// outcome -- an unresolvable workspace, an absent evaluator on an
|
||||
// unattended run, an unparseable payload, or a task that no longer exists
|
||||
// -- mirroring cancelStaleRun's release/cancel/publish/log sequence. Always
|
||||
// returns false.
|
||||
func (si *SchedulerIntegration) cancelBudgetRun(
|
||||
ctx context.Context, run *models.Run, agent *models.AgentInstance,
|
||||
reason, action string, extraFields map[string]string,
|
||||
) bool {
|
||||
si.releaseCheckoutIfNeeded(ctx, run)
|
||||
si.svc.clearAgentWorking(ctx, agent.ID, run.ID)
|
||||
|
||||
if err := si.svc.repo.CancelRun(ctx, run.ID, reason); err != nil {
|
||||
si.logger.Error("failed to cancel run", zap.String("run_id", run.ID), zap.Error(err))
|
||||
} else {
|
||||
si.svc.publishRunProcessed(ctx, run.ID, RunStatusCancelled, run)
|
||||
}
|
||||
|
||||
fields := map[string]string{activityFieldCeiling: ceilingNotDetermined}
|
||||
for k, v := range extraFields {
|
||||
fields[k] = v
|
||||
}
|
||||
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
|
||||
action, "run", run.ID, mustJSON(fields), run.ID, "")
|
||||
return false
|
||||
}
|
||||
|
||||
// projectResolution enumerates the outcomes of resolving a run's project
|
||||
// identifier for gate 4 (AC-OFFICE-BUDGET-006.7).
|
||||
type projectResolution int
|
||||
|
||||
const (
|
||||
// projectResolutionNone covers outcome (a): a well-formed payload with
|
||||
// no task identifier, or a task that resolves with no project. Not a
|
||||
// fault; no project-scoped policy applies (AC-OFFICE-BUDGET-001.15).
|
||||
projectResolutionNone projectResolution = iota
|
||||
projectResolutionFound
|
||||
// projectResolutionLookupError covers outcome (b): GetTaskBasicInfo
|
||||
// returned an error. An evaluator fault, deferred under
|
||||
// AC-OFFICE-BUDGET-006.3.
|
||||
projectResolutionLookupError
|
||||
// projectResolutionUnparseable covers outcome (c): the payload cannot
|
||||
// be parsed as JSON. Must not be read as (a); the run is cancelled,
|
||||
// never retried or failed.
|
||||
projectResolutionUnparseable
|
||||
// projectResolutionTaskNotFound covers outcome (d): the lookup
|
||||
// succeeded but the named task does not exist. Cancelled, never
|
||||
// retried or failed.
|
||||
projectResolutionTaskNotFound
|
||||
)
|
||||
|
||||
// resolveRunProject resolves a run's project identifier for gate 4,
|
||||
// implementing AC-OFFICE-BUDGET-006.7's four-outcome split. It does not
|
||||
// reuse extractProjectID (which collapses all four outcomes to "" for its
|
||||
// other, non-admission callers) or ParseRunPayload (which silently
|
||||
// swallows a JSON unmarshal error), because gate 4 must distinguish all
|
||||
// four rather than treating a malformed payload as "no project".
|
||||
func (si *SchedulerIntegration) resolveRunProject(
|
||||
ctx context.Context, payload string,
|
||||
) (projectID string, res projectResolution) {
|
||||
if payload == "" || payload == "{}" {
|
||||
return "", projectResolutionNone
|
||||
}
|
||||
|
||||
var parsed struct {
|
||||
TaskID string `json:"task_id"`
|
||||
}
|
||||
if err := json.Unmarshal([]byte(payload), &parsed); err != nil {
|
||||
return "", projectResolutionUnparseable
|
||||
}
|
||||
if parsed.TaskID == "" {
|
||||
return "", projectResolutionNone
|
||||
}
|
||||
|
||||
info, err := si.svc.repo.GetTaskBasicInfo(ctx, parsed.TaskID)
|
||||
if err != nil {
|
||||
return "", projectResolutionLookupError
|
||||
}
|
||||
if info == nil {
|
||||
return "", projectResolutionTaskNotFound
|
||||
}
|
||||
if info.ProjectID == "" {
|
||||
return "", projectResolutionNone
|
||||
}
|
||||
return info.ProjectID, projectResolutionFound
|
||||
}
|
||||
|
||||
// budgetDeferralCause is one of the three AC-OFFICE-BUDGET-006.4 admission
|
||||
// faults that share the evaluator fault's retry/backoff mechanics
|
||||
// (AC-OFFICE-BUDGET-001.3/.16) but must stay distinguishable from it and
|
||||
// from each other in their activity entries (AC-OFFICE-BUDGET-006.5). The
|
||||
// workspace-lookup-error branch of AC-OFFICE-BUDGET-001.13 is deliberately
|
||||
// NOT a fourth value here: it never reaches admitRun at all (processRun
|
||||
// resolves it before admitRun is called, since no *models.AgentInstance
|
||||
// exists yet to pass in), so it has its own dedicated pair,
|
||||
// deferWorkspaceLookupFailure/cancelUnresolvableAgentRun, sharing this
|
||||
// type's action-naming and no-escalation shape but not its cause value.
|
||||
type budgetDeferralCause int
|
||||
|
||||
const (
|
||||
budgetDeferralEvaluatorFault budgetDeferralCause = iota
|
||||
budgetDeferralUnevaluatedPolicy
|
||||
budgetDeferralProjectLookupError
|
||||
)
|
||||
|
||||
func (c budgetDeferralCause) deferredAction() string {
|
||||
switch c {
|
||||
case budgetDeferralUnevaluatedPolicy:
|
||||
return "run_budget_unevaluated_policy_deferred"
|
||||
case budgetDeferralProjectLookupError:
|
||||
return "run_budget_project_lookup_deferred"
|
||||
default:
|
||||
return "run_budget_evaluator_fault_deferred"
|
||||
}
|
||||
}
|
||||
|
||||
func (c budgetDeferralCause) failedAction() string {
|
||||
switch c {
|
||||
case budgetDeferralUnevaluatedPolicy:
|
||||
return "run_budget_unevaluated_policy_failed"
|
||||
case budgetDeferralProjectLookupError:
|
||||
return "run_budget_project_lookup_failed"
|
||||
default:
|
||||
return "run_budget_evaluator_fault_failed"
|
||||
}
|
||||
}
|
||||
|
||||
// admitBudgetDeferral defers (retries) run for one of the three
|
||||
// AC-OFFICE-BUDGET-006.4 admission-fault causes, or fails it without
|
||||
// escalation once retries are exhausted (AC-OFFICE-BUDGET-001.17). It
|
||||
// reuses the existing scheduleRetry/isRetryStale machinery so retry_count,
|
||||
// backoff and the staleness bound are shared with every other retry class
|
||||
// (AC-OFFICE-BUDGET-001.16/.18), but never calls escalateFailure. policyID
|
||||
// names the policy per AC-OFFICE-BUDGET-005.5/-006.5's naming rule and is
|
||||
// "" for every cause but budgetDeferralUnevaluatedPolicy. Always returns
|
||||
// false: every call site uses it as `return si.admitBudgetDeferral(...)`.
|
||||
func (si *SchedulerIntegration) admitBudgetDeferral(
|
||||
ctx context.Context, run *models.Run, agent *models.AgentInstance,
|
||||
cause budgetDeferralCause, policyID string,
|
||||
) bool {
|
||||
si.releaseCheckoutIfNeeded(ctx, run)
|
||||
provenance := shared.ClassifyRunProvenance(run.Reason)
|
||||
|
||||
if run.RetryCount >= MaxRetryCount {
|
||||
incBudgetFailedNoEscalation(cause, provenance)
|
||||
if err := si.svc.failRunNoEscalation(ctx, run, agent, cause, policyID); err != nil {
|
||||
si.logger.Error("failed to fail run without escalation",
|
||||
zap.String("run_id", run.ID), zap.Error(err))
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
if stale, _ := isRetryStale(run); stale {
|
||||
incBudgetCancelledStaleDeferral(provenance)
|
||||
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
|
||||
"run_budget_deferral_stale_cancelled", "run", run.ID,
|
||||
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined, "cause": "budget_deferral"}), run.ID, "")
|
||||
} else {
|
||||
switch cause {
|
||||
case budgetDeferralEvaluatorFault:
|
||||
incBudgetDeferredEvaluatorFault(provenance)
|
||||
case budgetDeferralUnevaluatedPolicy:
|
||||
incBudgetDeferredUnevaluatedPolicy(provenance)
|
||||
case budgetDeferralProjectLookupError:
|
||||
incBudgetDeferredProjectLookup(provenance)
|
||||
}
|
||||
fields := map[string]string{
|
||||
activityFieldCeiling: ceilingNotDetermined,
|
||||
"attempt": strconv.Itoa(run.RetryCount + 1),
|
||||
}
|
||||
if policyID != "" {
|
||||
fields["policy_id"] = policyID
|
||||
}
|
||||
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
|
||||
cause.deferredAction(), "run", run.ID, mustJSON(fields), run.ID, "")
|
||||
}
|
||||
|
||||
if err := si.svc.scheduleRetry(ctx, run); err != nil {
|
||||
si.logger.Error("failed to schedule budget deferral retry",
|
||||
zap.String("run_id", run.ID), zap.Error(err))
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// cancelUnresolvableAgentRun implements AC-OFFICE-BUDGET-001.13's "lookup
|
||||
// succeeded and found no agent instance" disposition, called from
|
||||
// processRun before an *models.AgentInstance is available -- the run
|
||||
// carries no workspace and therefore no ceiling that could ever be
|
||||
// evaluated, so it is cancelled rather than retried or failed, and never
|
||||
// escalated (AC-OFFICE-BUDGET-001.17). Shares its action with admitRun's
|
||||
// gate 1 (agent found but WorkspaceID == ""), the other branch of the same
|
||||
// disposition; unlike cancelBudgetRun's other callers, no agent is
|
||||
// available here, so the activity entry carries no workspace scope.
|
||||
func (si *SchedulerIntegration) cancelUnresolvableAgentRun(ctx context.Context, run *models.Run) {
|
||||
provenance := shared.ClassifyRunProvenance(run.Reason)
|
||||
incBudgetCancelledNoWorkspace(provenance)
|
||||
si.cleanupWorkspaceLookupRun(ctx, run)
|
||||
|
||||
if err := si.svc.repo.CancelRun(ctx, run.ID, "no_resolvable_workspace"); err != nil {
|
||||
si.logger.Error("failed to cancel run", zap.String("run_id", run.ID), zap.Error(err))
|
||||
} else {
|
||||
si.svc.publishRunProcessed(ctx, run.ID, RunStatusCancelled, run)
|
||||
}
|
||||
si.svc.LogActivityWithRun(ctx, "", "scheduler", "office-scheduler",
|
||||
"run_budget_workspace_unresolvable", "run", run.ID,
|
||||
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined}), run.ID, "")
|
||||
}
|
||||
|
||||
// deferWorkspaceLookupFailure implements AC-OFFICE-BUDGET-001.13's "lookup
|
||||
// returned an error" disposition: deferred/retried on the same terms as an
|
||||
// evaluator fault (AC-OFFICE-BUDGET-001.3/.16/.18), and at MaxRetryCount
|
||||
// failed without escalation (AC-OFFICE-BUDGET-006.4) rather than through
|
||||
// the generic HandleRunFailure/escalateFailure path, which would queue a
|
||||
// new run for the CEO agent (AC-OFFICE-BUDGET-001.17). Mirrors
|
||||
// admitBudgetDeferral's shape, but no *models.AgentInstance is available
|
||||
// here (the lookup itself is what failed), so the activity entry carries
|
||||
// no workspace scope. The run may still own a checkout from an earlier
|
||||
// routed launch, so this path releases run-owned state before retrying.
|
||||
func (si *SchedulerIntegration) deferWorkspaceLookupFailure(ctx context.Context, run *models.Run) {
|
||||
provenance := shared.ClassifyRunProvenance(run.Reason)
|
||||
si.cleanupWorkspaceLookupRun(ctx, run)
|
||||
|
||||
if run.RetryCount >= MaxRetryCount {
|
||||
incBudgetFailedWorkspaceLookup(provenance)
|
||||
if err := si.svc.FailRun(ctx, run.ID); err != nil {
|
||||
si.logger.Error("failed to fail run without escalation",
|
||||
zap.String("run_id", run.ID), zap.Error(err))
|
||||
return
|
||||
}
|
||||
si.svc.LogActivityWithRun(ctx, "", "system", "scheduler",
|
||||
"run_budget_workspace_lookup_failed", "run", run.ID,
|
||||
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined}), run.ID, "")
|
||||
return
|
||||
}
|
||||
|
||||
if stale, _ := isRetryStale(run); stale {
|
||||
incBudgetCancelledStaleDeferral(provenance)
|
||||
si.svc.LogActivityWithRun(ctx, "", "scheduler", "office-scheduler",
|
||||
"run_budget_deferral_stale_cancelled", "run", run.ID,
|
||||
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined, "cause": "workspace_lookup"}), run.ID, "")
|
||||
} else {
|
||||
incBudgetDeferredWorkspaceLookup(provenance)
|
||||
si.svc.LogActivityWithRun(ctx, "", "scheduler", "office-scheduler",
|
||||
"run_budget_workspace_lookup_deferred", "run", run.ID,
|
||||
mustJSON(map[string]string{
|
||||
activityFieldCeiling: ceilingNotDetermined,
|
||||
"attempt": strconv.Itoa(run.RetryCount + 1),
|
||||
}), run.ID, "")
|
||||
}
|
||||
|
||||
if err := si.svc.scheduleRetry(ctx, run); err != nil {
|
||||
si.logger.Error("failed to schedule workspace lookup retry",
|
||||
zap.String("run_id", run.ID), zap.Error(err))
|
||||
}
|
||||
}
|
||||
|
||||
// cleanupWorkspaceLookupRun clears ownership retained by a routed run that
|
||||
// was requeued after launch. The owner-scoped release is a no-op when this
|
||||
// attempt never held a checkout, so a lookup failure cannot steal another
|
||||
// run's lock.
|
||||
func (si *SchedulerIntegration) cleanupWorkspaceLookupRun(ctx context.Context, run *models.Run) {
|
||||
si.releaseCheckoutIfNeeded(ctx, run)
|
||||
if run != nil {
|
||||
si.svc.clearAgentWorking(ctx, run.AgentProfileID, run.ID)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,935 @@
|
||||
package service_test
|
||||
|
||||
// Covers the five pre-launch admission gates of
|
||||
// docs/specs/office/requirements/budget-enforcement.md AC-OFFICE-BUDGET-001.14,
|
||||
// replacing the old checkBudget's two fail-open paths (no evaluator wired,
|
||||
// evaluator error) and closing the third (zero configured policies) via the
|
||||
// built-in default at gate 5.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"sort"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/service"
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// fakeBudgetEvaluator lets admission tests force EvaluatePreLaunch/
|
||||
// EvaluateDefaultCeiling's error and result shapes without needing a real
|
||||
// repository failure.
|
||||
type fakeBudgetEvaluator struct {
|
||||
preLaunchResult models.PreLaunchResult
|
||||
preLaunchErr error
|
||||
defaultResult models.PreLaunchPolicyResult
|
||||
defaultErr error
|
||||
}
|
||||
|
||||
func (f *fakeBudgetEvaluator) CheckPreExecutionBudget(
|
||||
context.Context, string, string, string,
|
||||
) (bool, string, error) {
|
||||
return true, "", nil
|
||||
}
|
||||
|
||||
func (f *fakeBudgetEvaluator) EvaluateBudget(context.Context, string, string, string) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *fakeBudgetEvaluator) EvaluatePreLaunch(
|
||||
context.Context, string, string, string, bool, shared.RunProvenance, time.Time,
|
||||
) (models.PreLaunchResult, error) {
|
||||
return f.preLaunchResult, f.preLaunchErr
|
||||
}
|
||||
|
||||
func (f *fakeBudgetEvaluator) EvaluateDefaultCeiling(
|
||||
context.Context, string, time.Time,
|
||||
) (models.PreLaunchPolicyResult, error) {
|
||||
return f.defaultResult, f.defaultErr
|
||||
}
|
||||
|
||||
// deferralAttempts returns the "attempt" field of every activity entry for
|
||||
// runID matching action, sorted ascending. Sorted rather than
|
||||
// created_at-ordered because repeated deferrals in a test can land within
|
||||
// the same timestamp resolution.
|
||||
func deferralAttempts(t *testing.T, svc *service.Service, wsID, runID, action string) []string {
|
||||
t.Helper()
|
||||
entries, err := svc.ListActivity(context.Background(), wsID, 50)
|
||||
if err != nil {
|
||||
t.Fatalf("list activity: %v", err)
|
||||
}
|
||||
var attempts []string
|
||||
for _, e := range entries {
|
||||
if e.RunID != runID || string(e.Action) != action {
|
||||
continue
|
||||
}
|
||||
var fields map[string]string
|
||||
if err := json.Unmarshal([]byte(e.Details), &fields); err != nil {
|
||||
t.Fatalf("unmarshal activity details %q: %v", e.Details, err)
|
||||
}
|
||||
attempts = append(attempts, fields["attempt"])
|
||||
}
|
||||
sort.Strings(attempts)
|
||||
return attempts
|
||||
}
|
||||
|
||||
func hasActivityAction(t *testing.T, svc *service.Service, wsID, action string) bool {
|
||||
t.Helper()
|
||||
entries, err := svc.ListActivity(context.Background(), wsID, 50)
|
||||
if err != nil {
|
||||
t.Fatalf("list activity: %v", err)
|
||||
}
|
||||
for _, e := range entries {
|
||||
if string(e.Action) == action {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// TestAdmitRun_NoEvaluatorWired_UnattendedCancels covers AC-OFFICE-BUDGET-001.5:
|
||||
// an absent evaluator is a deployment fact, not a transient fault, so an
|
||||
// unattended run is cancelled rather than retried or failed.
|
||||
func TestAdmitRun_NoEvaluatorWired_UnattendedCancels(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
svc.SetBudgetChecker(nil)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-no-evaluator-unattended", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
|
||||
if run.Status != service.RunStatusCancelled {
|
||||
t.Fatalf("status = %q, want cancelled", run.Status)
|
||||
}
|
||||
if !hasActivityAction(t, svc, "ws-1", "run_budget_no_evaluator") {
|
||||
t.Error("expected run_budget_no_evaluator activity entry")
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_NoEvaluatorWired_AttendedLaunches covers AC-OFFICE-BUDGET-001.6:
|
||||
// an absent evaluator never blocks an attended run.
|
||||
func TestAdmitRun_NoEvaluatorWired_AttendedLaunches(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
svc.SetBudgetChecker(nil)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-no-evaluator-attended", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestTask(t, svc, "task-no-evaluator-attended", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-no-evaluator-attended"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if hasActivityAction(t, svc, "ws-1", "run_budget_no_evaluator") {
|
||||
t.Error("attended run must not be blocked by an absent evaluator")
|
||||
}
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
|
||||
if run.Status == service.RunStatusCancelled {
|
||||
t.Fatalf("status = %q, attended run must not be cancelled", run.Status)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_EvaluatorFault_DefersThenFailsWithoutEscalation covers
|
||||
// AC-OFFICE-BUDGET-001.3/.4/.17: a plain evaluator error (not naming any
|
||||
// policy) defers the run, and failing it at MaxRetryCount neither escalates
|
||||
// to the CEO agent nor queues any new run.
|
||||
func TestAdmitRun_EvaluatorFault_DefersThenFailsWithoutEscalation(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
|
||||
ceo := makeAgent("ceo-evaluator-fault", models.AgentRoleCEO)
|
||||
if err := svc.CreateAgentInstance(ctx, ceo); err != nil {
|
||||
t.Fatalf("create ceo: %v", err)
|
||||
}
|
||||
agent := makeAgent("worker-evaluator-fault", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestTask(t, svc, "task-evaluator-fault", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-evaluator-fault"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
|
||||
if run.Status != service.RunStatusQueued {
|
||||
t.Fatalf("status after first fault = %q, want queued (deferred)", run.Status)
|
||||
}
|
||||
if !hasActivityAction(t, svc, "ws-1", "run_budget_evaluator_fault_deferred") {
|
||||
t.Error("expected run_budget_evaluator_fault_deferred activity entry")
|
||||
}
|
||||
|
||||
// Drive the run to MaxRetryCount and re-process it directly (bypassing
|
||||
// the real backoff delay, exactly as the existing retry tests do).
|
||||
run.RetryCount = service.MaxRetryCount
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
|
||||
failed, err := svc.GetRun(ctx, run.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("get run: %v", err)
|
||||
}
|
||||
if failed.Status != service.RunStatusFailed {
|
||||
t.Fatalf("status at MaxRetryCount = %q, want failed", failed.Status)
|
||||
}
|
||||
if !hasActivityAction(t, svc, "ws-1", "run_budget_evaluator_fault_failed") {
|
||||
t.Error("expected run_budget_evaluator_fault_failed activity entry")
|
||||
}
|
||||
|
||||
// AC-OFFICE-BUDGET-001.17: no escalation run queued for the CEO.
|
||||
runs, err := svc.ListRuns(ctx, "ws-1")
|
||||
if err != nil {
|
||||
t.Fatalf("list runs: %v", err)
|
||||
}
|
||||
for _, r := range runs {
|
||||
if r.AgentProfileID == ceo.ID {
|
||||
t.Errorf("unexpected run queued for CEO agent after budget-fault failure: %+v", r)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_UnevaluatedPolicy_NamesPolicyInDeferral covers
|
||||
// AC-OFFICE-BUDGET-006.1/.5: an unevaluated-policy fault is distinguishable
|
||||
// from a plain evaluator fault and names the policy it could not evaluate.
|
||||
func TestAdmitRun_UnevaluatedPolicy_NamesPolicyInDeferral(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-xyz", Err: context.DeadlineExceeded},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-unevaluated-policy", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestTask(t, svc, "task-unevaluated-policy", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-unevaluated-policy"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
|
||||
if run.Status != service.RunStatusQueued {
|
||||
t.Fatalf("status = %q, want queued (deferred)", run.Status)
|
||||
}
|
||||
if !hasActivityAction(t, svc, "ws-1", "run_budget_unevaluated_policy_deferred") {
|
||||
t.Error("expected run_budget_unevaluated_policy_deferred activity entry")
|
||||
}
|
||||
if hasActivityAction(t, svc, "ws-1", "run_budget_evaluator_fault_deferred") {
|
||||
t.Error("unevaluated-policy fault must not also fire the generic evaluator-fault action")
|
||||
}
|
||||
}
|
||||
|
||||
// TestFinishPolicyBlock_ClearsStaleAgentWorkingStatus and
|
||||
// TestCancelBudgetRun_ClearsStaleAgentWorkingStatus pin a fix carried over
|
||||
// from a rebase onto main: main independently added an equivalent
|
||||
// clearAgentWorking call to the old checkBudget's block branch (fixing a
|
||||
// stuck-"working" agent), and cancelBudgetRun's own doc comment already
|
||||
// claimed to mirror cancelStaleRun's release/cancel/publish/log sequence --
|
||||
// which has always included clearAgentWorking -- without actually doing so.
|
||||
// admitRun always runs before markAgentWorking in the real pipeline
|
||||
// (processRun calls admitRun, then prepareAndLaunch marks working), so the
|
||||
// only way an agent is already "working" when a block/cancel fires for the
|
||||
// same run.ID is a run that reached the launch boundary once, then got
|
||||
// requeued (e.g. a contended checkout retry) and is being re-admitted.
|
||||
|
||||
// TestFinishPolicyBlock_ClearsStaleAgentWorkingStatus covers finishPolicyBlock.
|
||||
func TestFinishPolicyBlock_ClearsStaleAgentWorkingStatus(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
deciding := &models.PreLaunchPolicyResult{PolicyID: "policy-stale-working", LimitExceeded: true}
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchResult: models.PreLaunchResult{
|
||||
Decision: models.PreLaunchDecisionBlockedByLimit,
|
||||
DecidingPolicy: deciding,
|
||||
Policies: []models.PreLaunchPolicyResult{*deciding},
|
||||
},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-stale-working-block", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
|
||||
t.Fatalf("mark agent working: %v", err)
|
||||
}
|
||||
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusWorking, "before the re-admission block")
|
||||
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
|
||||
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusIdle,
|
||||
"after a policy block clears a stale working mark left by an earlier attempt")
|
||||
}
|
||||
|
||||
// TestCancelBudgetRun_ClearsStaleAgentWorkingStatus covers cancelBudgetRun,
|
||||
// via gate 1's cancellation path.
|
||||
func TestCancelBudgetRun_ClearsStaleAgentWorkingStatus(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-stale-working-cancel", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
|
||||
t.Fatalf("mark agent working: %v", err)
|
||||
}
|
||||
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusWorking, "before the re-admission cancel")
|
||||
|
||||
unresolvedAgent := *agent
|
||||
unresolvedAgent.WorkspaceID = ""
|
||||
service.AdmitRunForTest(svc, ctx, run, &unresolvedAgent)
|
||||
|
||||
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusIdle,
|
||||
"after a gate-1 cancel clears a stale working mark left by an earlier attempt")
|
||||
}
|
||||
|
||||
// TestFailRunNoEscalation_ClearsStaleAgentWorkingStatus covers
|
||||
// failRunNoEscalation (retry.go), reached via admitBudgetDeferral once
|
||||
// RetryCount reaches MaxRetryCount. Same stale-mark scenario as the two
|
||||
// tests above: a run that reached the launch boundary once, was requeued,
|
||||
// then exhausted its retries on a budget-admission fault must not leave its
|
||||
// agent stuck "working" forever.
|
||||
func TestFailRunNoEscalation_ClearsStaleAgentWorkingStatus(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-stale-working-no-escalation", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
|
||||
t.Fatalf("mark agent working: %v", err)
|
||||
}
|
||||
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusWorking, "before the re-admission fault")
|
||||
|
||||
run.RetryCount = service.MaxRetryCount
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
|
||||
failed, err := svc.GetRun(ctx, run.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("get run: %v", err)
|
||||
}
|
||||
if failed.Status != service.RunStatusFailed {
|
||||
t.Fatalf("status at MaxRetryCount = %q, want failed", failed.Status)
|
||||
}
|
||||
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusIdle,
|
||||
"after failRunNoEscalation clears a stale working mark left by an earlier attempt")
|
||||
}
|
||||
|
||||
// TestProcessRun_MissingAgentReleasesPriorCheckout covers a routed run that
|
||||
// was requeued after launch. The next scheduler pass may find that its agent
|
||||
// no longer exists, but the run still owns the task checkout from its prior
|
||||
// attempt. The cancellation must release that ownership.
|
||||
func TestProcessRun_MissingAgentReleasesPriorCheckout(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-routed-missing", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `
|
||||
INSERT INTO tasks (id, workspace_id, title, created_at, updated_at)
|
||||
VALUES ('task-routed-missing', 'ws-1', 'Routed task', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
|
||||
`)
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-routed-missing"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
acquired, err := svc.RepoForTest().CheckoutTaskForRun(ctx, "task-routed-missing", agent.ID, run.ID)
|
||||
if err != nil || !acquired {
|
||||
t.Fatalf("seed run checkout: acquired=%v err=%v", acquired, err)
|
||||
}
|
||||
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
|
||||
t.Fatalf("mark agent working: %v", err)
|
||||
}
|
||||
if err := svc.RepoForTest().DeleteAgentInstance(ctx, agent.ID); err != nil {
|
||||
t.Fatalf("delete agent: %v", err)
|
||||
}
|
||||
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
|
||||
replacement := makeAgent("worker-routed-replacement", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, replacement); err != nil {
|
||||
t.Fatalf("create replacement agent: %v", err)
|
||||
}
|
||||
acquired, err = svc.CheckoutTask(ctx, "task-routed-missing", replacement.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("replacement checkout: %v", err)
|
||||
}
|
||||
if !acquired {
|
||||
t.Fatal("replacement agent could not acquire a checkout left by the missing-agent cancellation")
|
||||
}
|
||||
|
||||
cancelled, err := svc.GetRun(ctx, run.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("get cancelled run: %v", err)
|
||||
}
|
||||
if cancelled.Status != service.RunStatusCancelled {
|
||||
t.Fatalf("run status = %q, want cancelled", cancelled.Status)
|
||||
}
|
||||
}
|
||||
|
||||
// TestProcessRun_WorkspaceLookupErrorReleasesPriorCheckout covers the retry
|
||||
// branch. A temporary repository lookup error must not preserve a checkout
|
||||
// while the run waits in the queue.
|
||||
func TestProcessRun_WorkspaceLookupErrorReleasesPriorCheckout(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-routed-lookup-error", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `
|
||||
INSERT INTO tasks (id, workspace_id, title, created_at, updated_at)
|
||||
VALUES ('task-routed-lookup-error', 'ws-1', 'Routed task', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
|
||||
`)
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-routed-lookup-error"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
acquired, err := svc.RepoForTest().CheckoutTaskForRun(ctx, "task-routed-lookup-error", agent.ID, run.ID)
|
||||
if err != nil || !acquired {
|
||||
t.Fatalf("seed run checkout: acquired=%v err=%v", acquired, err)
|
||||
}
|
||||
|
||||
// Make both agent lookup queries fail with a transient database error.
|
||||
svc.ExecSQL(t, "DROP TABLE agent_profiles")
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
|
||||
acquired, err = svc.CheckoutTask(ctx, "task-routed-lookup-error", "replacement-agent")
|
||||
if err != nil {
|
||||
t.Fatalf("replacement checkout: %v", err)
|
||||
}
|
||||
if !acquired {
|
||||
t.Fatal("replacement agent could not acquire a checkout left by the lookup-error deferral")
|
||||
}
|
||||
|
||||
deferred, err := svc.GetRun(ctx, run.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("get deferred run: %v", err)
|
||||
}
|
||||
if deferred.Status != service.RunStatusQueued {
|
||||
t.Fatalf("run status = %q, want queued", deferred.Status)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_RepeatedDeferral_AttemptIncrementsPerActivity covers
|
||||
// AC-OFFICE-BUDGET-005.6: each deferral of the same run writes its own
|
||||
// activity entry -- never coalesced into a single running total -- and each
|
||||
// entry's "attempt" field tracks that call's run.RetryCount+1.
|
||||
func TestAdmitRun_RepeatedDeferral_AttemptIncrementsPerActivity(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-attempt", Err: context.DeadlineExceeded},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-attempt-increments", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestTask(t, svc, "task-attempt-increments", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-attempt-increments"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
for i := 0; i < 3; i++ {
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
run.RetryCount++
|
||||
}
|
||||
|
||||
got := deferralAttempts(t, svc, "ws-1", run.ID, "run_budget_unevaluated_policy_deferred")
|
||||
want := []string{"1", "2", "3"}
|
||||
if len(got) != len(want) {
|
||||
t.Fatalf("attempts = %v, want %v (one entry per deferral, not coalesced)", got, want)
|
||||
}
|
||||
for i, w := range want {
|
||||
if got[i] != w {
|
||||
t.Errorf("attempts = %v, want %v", got, want)
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_DefaultCeiling_BlocksUnattendedRunWithZeroPolicies closes the
|
||||
// third of the three fail-open paths this capability replaces: with zero
|
||||
// configured policies, an unattended run over the built-in default's daily
|
||||
// ceiling is blocked rather than launched unconditionally.
|
||||
func TestAdmitRun_DefaultCeiling_BlocksUnattendedRunWithZeroPolicies(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-default-ceiling", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestCostEvent(t, svc, agent.ID, "task-default-ceiling", int64(600_000))
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
|
||||
assertOutcome(t, run, service.RunOutcomeBudgetBlocked)
|
||||
if !hasActivityAction(t, svc, "ws-1", "run_budget_blocked") {
|
||||
t.Error("expected run_budget_blocked activity entry")
|
||||
}
|
||||
}
|
||||
|
||||
// TestResolveRunProject covers AC-OFFICE-BUDGET-006.7's four-outcome split.
|
||||
// Tested directly against resolveRunProject rather than through the full
|
||||
// scheduler pipeline: checkoutTask's own contention query independently
|
||||
// requires the named task to already exist (a 0-row checkout update reads
|
||||
// identically to "held by another agent"), so a task-not-found or a
|
||||
// tasks-table failure never reaches admitRun through that path at all in
|
||||
// this codebase's existing checkout flow -- resolveRunProject's own
|
||||
// contract is what this capability adds and is what needs covering here.
|
||||
func TestResolveRunProject(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
insertTestTask(t, svc, "task-with-project", "ws-1")
|
||||
svc.ExecSQL(t, `UPDATE tasks SET project_id = ? WHERE id = ?`, "project-1", "task-with-project")
|
||||
insertTestTask(t, svc, "task-no-project", "ws-1")
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
payload string
|
||||
wantProjectID string
|
||||
wantRes int
|
||||
}{
|
||||
{"empty payload", "", "", service.ProjectResolutionNoneForTest},
|
||||
{"empty object payload", "{}", "", service.ProjectResolutionNoneForTest},
|
||||
{"no task_id key", `{"other":"field"}`, "", service.ProjectResolutionNoneForTest},
|
||||
{"task resolves with no project", `{"task_id":"task-no-project"}`, "", service.ProjectResolutionNoneForTest},
|
||||
{"task resolves with a project", `{"task_id":"task-with-project"}`, "project-1", service.ProjectResolutionFoundForTest},
|
||||
{"unparseable payload", `{not-json`, "", service.ProjectResolutionUnparseableForTest},
|
||||
{"task does not exist", `{"task_id":"does-not-exist"}`, "", service.ProjectResolutionTaskNotFoundForTest},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
gotID, gotRes := service.ResolveRunProjectForTest(svc, ctx, tc.payload)
|
||||
if gotID != tc.wantProjectID || gotRes != tc.wantRes {
|
||||
t.Errorf("resolveRunProject(%q) = (%q, %d), want (%q, %d)",
|
||||
tc.payload, gotID, gotRes, tc.wantProjectID, tc.wantRes)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
t.Run("lookup error", func(t *testing.T) {
|
||||
svc.ExecSQL(t, `DROP TABLE tasks`)
|
||||
_, gotRes := service.ResolveRunProjectForTest(svc, ctx, `{"task_id":"task-with-project"}`)
|
||||
if gotRes != service.ProjectResolutionLookupErrorForTest {
|
||||
t.Errorf("resolution = %d, want lookup error (%d)", gotRes, service.ProjectResolutionLookupErrorForTest)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// TestAdmitRun_PricingDegradedBlock_UnmeasurableOutcome covers
|
||||
// AC-OFFICE-BUDGET-004.6/-005.7: a policy that blocks purely on pricing
|
||||
// degradation (its limit was never confirmed reached) carries the distinct
|
||||
// run_budget_unmeasurable outcome and its own activity action, not the plain
|
||||
// limit-block pair.
|
||||
func TestAdmitRun_PricingDegradedBlock_UnmeasurableOutcome(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
deciding := &models.PreLaunchPolicyResult{
|
||||
PolicyID: "policy-pricing-degraded", Degraded: true, DegradationBlocked: true, LimitExceeded: false,
|
||||
}
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchResult: models.PreLaunchResult{
|
||||
Decision: models.PreLaunchDecisionBlockedByDegradation,
|
||||
DecidingPolicy: deciding,
|
||||
Policies: []models.PreLaunchPolicyResult{*deciding},
|
||||
},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-pricing-degraded-block", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
|
||||
assertOutcome(t, run, service.RunOutcomeBudgetUnmeasurable)
|
||||
if !hasActivityAction(t, svc, "ws-1", "run_budget_pricing_degraded_blocked") {
|
||||
t.Error("expected run_budget_pricing_degraded_blocked activity entry")
|
||||
}
|
||||
if hasActivityAction(t, svc, "ws-1", "run_budget_blocked") {
|
||||
t.Error("a pricing-degraded block must not also fire the plain limit-block action")
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_DefaultCeiling_ExemptsAttendedRun covers AC-OFFICE-BUDGET-003.3:
|
||||
// the built-in default ceiling gates unattended runs only. An attended run
|
||||
// launches even though its workspace already exceeds the default ceiling
|
||||
// (mirroring TestAdmitRun_DefaultCeiling_BlocksUnattendedRunWithZeroPolicies's
|
||||
// spend fixture, but with a task-assigned, attended run instead).
|
||||
func TestAdmitRun_DefaultCeiling_ExemptsAttendedRun(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
agent := makeAgent("worker-default-ceiling-attended", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestCostEvent(t, svc, agent.ID, "task-default-ceiling-attended", int64(600_000))
|
||||
insertTestTask(t, svc, "task-default-ceiling-attended-run", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-default-ceiling-attended-run"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
|
||||
if run.Status == service.RunStatusCancelled {
|
||||
t.Fatalf("status = %q, attended run must not be cancelled by the default ceiling", run.Status)
|
||||
}
|
||||
if run.Status == "finished" && run.Outcome != nil && *run.Outcome == service.RunOutcomeBudgetBlocked {
|
||||
t.Fatalf("attended run was finished with outcome %q, want not blocked by the default ceiling", *run.Outcome)
|
||||
}
|
||||
if hasActivityAction(t, svc, "ws-1", "run_budget_blocked") {
|
||||
t.Error("attended run must not trigger a default-ceiling block")
|
||||
}
|
||||
}
|
||||
|
||||
// activityActionForRun returns the single activity action recorded for
|
||||
// runID within wsID's activity log, failing the test if none is found.
|
||||
// cancelUnresolvableAgentRun logs with an empty workspace scope (no agent
|
||||
// available to read WorkspaceID from), so callers pass "" for that scenario.
|
||||
func activityActionForRun(t *testing.T, svc *service.Service, wsID, runID string) string {
|
||||
t.Helper()
|
||||
entries, err := svc.ListActivity(context.Background(), wsID, 50)
|
||||
if err != nil {
|
||||
t.Fatalf("list activity: %v", err)
|
||||
}
|
||||
for _, e := range entries {
|
||||
if e.RunID == runID {
|
||||
return string(e.Action)
|
||||
}
|
||||
}
|
||||
t.Fatalf("no activity entry found for run %s in workspace %q", runID, wsID)
|
||||
return ""
|
||||
}
|
||||
|
||||
// TestBudgetAdmission_ActionsAreDistinguishable covers AC-OFFICE-BUDGET-005.3/
|
||||
// -006.5: every admission-fault, cancellation, and block disposition this
|
||||
// capability introduces writes its own distinct activity action, so an
|
||||
// operator (or an alerting query keyed on the action string) can always
|
||||
// tell dispositions apart. Each scenario runs against its own service
|
||||
// instance so setup that mutates shared state (a dropped table, a forced
|
||||
// retry count) can't leak into another scenario's result.
|
||||
func TestBudgetAdmission_ActionsAreDistinguishable(t *testing.T) {
|
||||
type observedAction struct{ scenario, action string }
|
||||
var seen []observedAction
|
||||
record := func(scenario, action string) {
|
||||
seen = append(seen, observedAction{scenario, action})
|
||||
}
|
||||
|
||||
t.Run("workspace_lookup_deferred", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-ws-deferred", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `DROP TABLE agent_profiles`)
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
// deferWorkspaceLookupFailure logs with no workspace scope: no
|
||||
// *models.AgentInstance was ever resolved to read a WorkspaceID from.
|
||||
record("workspace_lookup_deferred", activityActionForRun(t, svc, "", run.ID))
|
||||
})
|
||||
|
||||
t.Run("workspace_lookup_failed", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-ws-failed", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `DROP TABLE agent_profiles`)
|
||||
run.RetryCount = service.MaxRetryCount
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
record("workspace_lookup_failed", activityActionForRun(t, svc, "", run.ID))
|
||||
})
|
||||
|
||||
t.Run("workspace_unresolvable", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-ws-unresolvable", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `DELETE FROM agent_profiles WHERE id = ?`, agent.ID)
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
record("workspace_unresolvable", activityActionForRun(t, svc, "", run.ID))
|
||||
})
|
||||
|
||||
t.Run("unevaluated_policy_deferred", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-actions", Err: context.DeadlineExceeded},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-unevaluated-deferred", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
|
||||
record("unevaluated_policy_deferred", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
t.Run("unevaluated_policy_failed", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-actions", Err: context.DeadlineExceeded},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-unevaluated-failed", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
run.RetryCount = service.MaxRetryCount
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
record("unevaluated_policy_failed", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
// project_lookup_deferred/failed, payload_unparseable and task_not_found
|
||||
// all drive admitRun directly via AdmitRunForTest rather than through
|
||||
// RunSchedulerTick/ProcessRunForTest: as TestResolveRunProject's doc
|
||||
// comment explains, checkoutTask's own contention query independently
|
||||
// requires the named task to exist (or the tasks table to be queryable
|
||||
// at all), so a task-not-found or tasks-table failure is intercepted by
|
||||
// checkoutTask as "held by another agent" / a checkout error before the
|
||||
// run ever reaches admitRun through the scheduler pipeline -- exactly
|
||||
// the scenario each of these needs to construct.
|
||||
|
||||
t.Run("project_lookup_deferred", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-project-deferred", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `DROP TABLE tasks`)
|
||||
run.Payload = `{"task_id":"any-task"}`
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
record("project_lookup_deferred", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
t.Run("project_lookup_failed", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-project-failed", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
svc.ExecSQL(t, `DROP TABLE tasks`)
|
||||
run.Payload = `{"task_id":"any-task"}`
|
||||
run.RetryCount = service.MaxRetryCount
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
record("project_lookup_failed", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
t.Run("payload_unparseable", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-unparseable", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
run.Payload = `{not-json`
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
record("payload_unparseable", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
t.Run("task_not_found", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-task-not-found", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
run.Payload = `{"task_id":"does-not-exist"}`
|
||||
service.AdmitRunForTest(svc, ctx, run, agent)
|
||||
record("task_not_found", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
t.Run("pricing_degraded_blocked", func(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
deciding := &models.PreLaunchPolicyResult{
|
||||
PolicyID: "policy-actions-degraded", Degraded: true, DegradationBlocked: true, LimitExceeded: false,
|
||||
}
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{
|
||||
Decision: models.PreLaunchDecisionBlockedByDegradation, DecidingPolicy: deciding,
|
||||
Policies: []models.PreLaunchPolicyResult{*deciding},
|
||||
}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
agent := makeAgent("worker-actions-pricing-degraded", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
|
||||
record("pricing_degraded_blocked", activityActionForRun(t, svc, "ws-1", run.ID))
|
||||
})
|
||||
|
||||
const wantScenarios = 10
|
||||
if len(seen) != wantScenarios {
|
||||
t.Fatalf("expected %d scenarios to record an action, got %d: %+v", wantScenarios, len(seen), seen)
|
||||
}
|
||||
byAction := make(map[string]string, len(seen))
|
||||
for _, o := range seen {
|
||||
if prior, ok := byAction[o.action]; ok {
|
||||
t.Errorf("action %q fired for both %q and %q; every disposition must be independently distinguishable",
|
||||
o.action, prior, o.scenario)
|
||||
continue
|
||||
}
|
||||
byAction[o.action] = o.scenario
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,137 @@
|
||||
package service
|
||||
|
||||
import (
|
||||
"expvar"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// expvar maps for AC-OFFICE-BUDGET-005.4's nine required counters, in the
|
||||
// same /debug/vars surface as the existing Office metrics (routing_*,
|
||||
// cost_events_*). Mirrors scheduler/metrics_vars.go's shape: counters only,
|
||||
// each labelled by run provenance (AC-OFFICE-BUDGET-007.1).
|
||||
var (
|
||||
budgetBlockedByLimitTotal = expvar.NewMap("office_budget_blocked_by_limit_total")
|
||||
budgetDeferredEvaluatorFaultTotal = expvar.NewMap("office_budget_deferred_evaluator_fault_total")
|
||||
budgetBlockedAbsentEvaluatorTotal = expvar.NewMap("office_budget_blocked_absent_evaluator_total")
|
||||
budgetDeferredWorkspaceLookupTotal = expvar.NewMap("office_budget_deferred_workspace_lookup_total")
|
||||
budgetCancelledNoWorkspaceTotal = expvar.NewMap("office_budget_cancelled_no_workspace_total")
|
||||
budgetCancelledStaleDeferralTotal = expvar.NewMap("office_budget_cancelled_stale_deferral_total")
|
||||
budgetBlockedPricingDegradedTotal = expvar.NewMap("office_budget_blocked_pricing_degraded_total")
|
||||
budgetAdmittedDefaultTotal = expvar.NewMap("office_budget_admitted_default_total")
|
||||
budgetAdmittedDegradedWindowTotal = expvar.NewMap("office_budget_admitted_degraded_window_total")
|
||||
)
|
||||
|
||||
// expvar maps for AC-OFFICE-BUDGET-006.6's seven additional counters, one
|
||||
// per state AC-OFFICE-BUDGET-006.5 names beyond the nine above: two
|
||||
// deferral-attempt counters for the causes AC-OFFICE-BUDGET-005.4's literal
|
||||
// enumeration omits (unevaluated-policy, project-lookup-error --
|
||||
// workspace-lookup deferral already has budgetDeferredWorkspaceLookupTotal
|
||||
// above), three MaxRetryCount-failure counters, one per AC-OFFICE-BUDGET-
|
||||
// 006.4 cause (the "evaluator error itself" is explicitly out of that
|
||||
// criterion's scope, so it is not a fourth), and two AC-OFFICE-BUDGET-006.7
|
||||
// cancellation counters. Kept in a separate var block from the nine above
|
||||
// because they answer a distinct criterion, not a revision of it.
|
||||
var (
|
||||
budgetDeferredUnevaluatedPolicyTotal = expvar.NewMap("office_budget_deferred_unevaluated_policy_total")
|
||||
budgetDeferredProjectLookupTotal = expvar.NewMap("office_budget_deferred_project_lookup_total")
|
||||
budgetFailedWorkspaceLookupTotal = expvar.NewMap("office_budget_failed_workspace_lookup_total")
|
||||
budgetFailedUnevaluatedPolicyTotal = expvar.NewMap("office_budget_failed_unevaluated_policy_total")
|
||||
budgetFailedProjectLookupTotal = expvar.NewMap("office_budget_failed_project_lookup_total")
|
||||
budgetCancelledUnparseablePayload = expvar.NewMap("office_budget_cancelled_unparseable_payload_total")
|
||||
budgetCancelledTaskNotFoundTotal = expvar.NewMap("office_budget_cancelled_task_not_found_total")
|
||||
)
|
||||
|
||||
// provenanceLabel renders a run's provenance as the "provenance=..." expvar
|
||||
// map key every counter in this file shares.
|
||||
func provenanceLabel(p shared.RunProvenance) string {
|
||||
if p.Attended() {
|
||||
return "provenance=attended"
|
||||
}
|
||||
return "provenance=unattended"
|
||||
}
|
||||
|
||||
func incBudgetBlockedByLimit(p shared.RunProvenance) {
|
||||
budgetBlockedByLimitTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetDeferredEvaluatorFault(p shared.RunProvenance) {
|
||||
budgetDeferredEvaluatorFaultTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetBlockedAbsentEvaluator(p shared.RunProvenance) {
|
||||
budgetBlockedAbsentEvaluatorTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetDeferredWorkspaceLookup(p shared.RunProvenance) {
|
||||
budgetDeferredWorkspaceLookupTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetCancelledNoWorkspace(p shared.RunProvenance) {
|
||||
budgetCancelledNoWorkspaceTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetCancelledStaleDeferral(p shared.RunProvenance) {
|
||||
budgetCancelledStaleDeferralTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetBlockedPricingDegraded(p shared.RunProvenance) {
|
||||
budgetBlockedPricingDegradedTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetAdmittedDefault(p shared.RunProvenance) {
|
||||
budgetAdmittedDefaultTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
// incBudgetAdmittedDegradedWindow implements AC-OFFICE-BUDGET-005.4's carved
|
||||
// out rule for this one counter: callers must only invoke this at a point
|
||||
// where the run's final disposition is already known to be launch, and only
|
||||
// when at least one evaluated policy or the default was degraded-admitted
|
||||
// (isDegradedAdmitted) -- never once per AC-OFFICE-BUDGET-004.8 activity
|
||||
// entry, since a later gate can still block the run after that entry is
|
||||
// written.
|
||||
func incBudgetAdmittedDegradedWindow(p shared.RunProvenance) {
|
||||
budgetAdmittedDegradedWindowTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetDeferredUnevaluatedPolicy(p shared.RunProvenance) {
|
||||
budgetDeferredUnevaluatedPolicyTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetDeferredProjectLookup(p shared.RunProvenance) {
|
||||
budgetDeferredProjectLookupTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetFailedWorkspaceLookup(p shared.RunProvenance) {
|
||||
budgetFailedWorkspaceLookupTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetFailedUnevaluatedPolicy(p shared.RunProvenance) {
|
||||
budgetFailedUnevaluatedPolicyTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetFailedProjectLookup(p shared.RunProvenance) {
|
||||
budgetFailedProjectLookupTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetCancelledUnparseablePayload(p shared.RunProvenance) {
|
||||
budgetCancelledUnparseablePayload.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
func incBudgetCancelledTaskNotFound(p shared.RunProvenance) {
|
||||
budgetCancelledTaskNotFoundTotal.Add(provenanceLabel(p), 1)
|
||||
}
|
||||
|
||||
// incBudgetFailedNoEscalation increments the MaxRetryCount-failure counter
|
||||
// matching cause, per AC-OFFICE-BUDGET-006.6's "not one counter shared
|
||||
// across the three" rule. The evaluator-fault-proper cause is deliberately
|
||||
// not routed here: AC-OFFICE-BUDGET-006.4 excludes "the evaluator error
|
||||
// itself" from its own three named causes.
|
||||
func incBudgetFailedNoEscalation(cause budgetDeferralCause, p shared.RunProvenance) {
|
||||
switch cause {
|
||||
case budgetDeferralUnevaluatedPolicy:
|
||||
incBudgetFailedUnevaluatedPolicy(p)
|
||||
case budgetDeferralProjectLookupError:
|
||||
incBudgetFailedProjectLookup(p)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,382 @@
|
||||
package service_test
|
||||
|
||||
// Covers AC-OFFICE-BUDGET-005.4: nine /debug/vars counters, one per
|
||||
// individually-observable admission state, each labelled by run provenance.
|
||||
// Each test drives a real admission decision (mostly via fakeBudgetEvaluator,
|
||||
// as budget_admission_test.go already does) and asserts the exact counter
|
||||
// bumps by exactly one, and that sibling counters for other states do not
|
||||
// move -- so a mislabelled or misplaced increment fails loudly rather than
|
||||
// only being caught by a coincidentally-passing total.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/service"
|
||||
)
|
||||
|
||||
const (
|
||||
metricBlockedByLimit = "office_budget_blocked_by_limit_total"
|
||||
metricDeferredEvalFault = "office_budget_deferred_evaluator_fault_total"
|
||||
metricBlockedNoEvaluator = "office_budget_blocked_absent_evaluator_total"
|
||||
metricDeferredWorkspace = "office_budget_deferred_workspace_lookup_total"
|
||||
metricCancelledNoWS = "office_budget_cancelled_no_workspace_total"
|
||||
metricCancelledStale = "office_budget_cancelled_stale_deferral_total"
|
||||
metricBlockedDegraded = "office_budget_blocked_pricing_degraded_total"
|
||||
metricAdmittedDefault = "office_budget_admitted_default_total"
|
||||
metricAdmittedDegradedWin = "office_budget_admitted_degraded_window_total"
|
||||
|
||||
labelUnattended = "provenance=unattended"
|
||||
labelAttended = "provenance=attended"
|
||||
)
|
||||
|
||||
func TestAdmitRun_MetricBlockedByLimit(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{
|
||||
Decision: models.PreLaunchDecisionBlockedByLimit,
|
||||
DecidingPolicy: &models.PreLaunchPolicyResult{PolicyID: "p-limit", LimitExceeded: true},
|
||||
}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended)
|
||||
beforeDegraded := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-blocked-limit", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricBlockedByLimit, labelUnattended, got, before+1)
|
||||
}
|
||||
if got := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended); got != beforeDegraded {
|
||||
t.Errorf("%s[%s] = %d, want unchanged %d", metricBlockedDegraded, labelUnattended, got, beforeDegraded)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAdmitRun_MetricBlockedPricingDegraded(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{
|
||||
Decision: models.PreLaunchDecisionBlockedByDegradation,
|
||||
DecidingPolicy: &models.PreLaunchPolicyResult{
|
||||
PolicyID: "p-degraded", LimitExceeded: false, Degraded: true, DegradationBlocked: true,
|
||||
},
|
||||
}}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended)
|
||||
beforeLimit := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-blocked-degraded", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricBlockedDegraded, labelUnattended, got, before+1)
|
||||
}
|
||||
if got := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended); got != beforeLimit {
|
||||
t.Errorf("%s[%s] = %d, want unchanged %d", metricBlockedByLimit, labelUnattended, got, beforeLimit)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAdmitRun_MetricDeferredEvaluatorFault(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricDeferredEvalFault, labelAttended)
|
||||
|
||||
agent := makeAgent("worker-metric-deferred-fault", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestTask(t, svc, "task-metric-deferred-fault", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-metric-deferred-fault"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricDeferredEvalFault, labelAttended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricDeferredEvalFault, labelAttended, got, before+1)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAdmitRun_MetricBlockedAbsentEvaluator(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
svc.SetBudgetChecker(nil)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricBlockedNoEvaluator, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-no-evaluator", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricBlockedNoEvaluator, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricBlockedNoEvaluator, labelUnattended, got, before+1)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_MetricDeferredWorkspaceLookup covers the one counter whose
|
||||
// cause never reaches admitRun at all (W2 disposition): a genuine
|
||||
// GetAgentFromConfig I/O error, instrumented at its existing call site in
|
||||
// processRun. AC-OFFICE-BUDGET-001.13 gives this a different disposition
|
||||
// than a lookup that succeeds and finds no row (see
|
||||
// TestProcessRun_AgentRowDeleted_Cancels below): the query is broken by
|
||||
// dropping the underlying table after the agent, so the earlier
|
||||
// create/queue/claim calls that also read it succeed normally and only the
|
||||
// processRun call under test observes the failure -- a real, non-ErrNoRows
|
||||
// error, not a simulation of one.
|
||||
func TestAdmitRun_MetricDeferredWorkspaceLookup(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-lookup-error", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
svc.ExecSQL(t, `DROP TABLE agent_profiles`)
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricDeferredWorkspace, labelUnattended, got, before+1)
|
||||
}
|
||||
}
|
||||
|
||||
// TestProcessRun_AgentRowDeleted_Cancels covers AC-OFFICE-BUDGET-001.13's
|
||||
// other workspace-lookup disposition: the lookup itself succeeds (no I/O
|
||||
// error) but finds no row, because the agent was deleted after the run was
|
||||
// queued. Unlike a lookup error (deferred/retried above), this is
|
||||
// cancelled -- an orphaned run has no workspace and so no ceiling that
|
||||
// could ever be evaluated -- and must never reach MaxRetryCount or
|
||||
// escalate. Drives it through the real processRun pipeline (not
|
||||
// AdmitRunForTest, which only reaches admitRun's separate, structurally
|
||||
// unreachable-in-production gate-1 branch for an agent found with an empty
|
||||
// WorkspaceID -- see TestAdmitRun_MetricCancelledNoWorkspace above).
|
||||
func TestProcessRun_AgentRowDeleted_Cancels(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
beforeCancelled := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended)
|
||||
beforeDeferred := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-agent-deleted", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
svc.ExecSQL(t, `DELETE FROM agent_profiles WHERE id = ?`, agent.ID)
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended); got != beforeCancelled+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricCancelledNoWS, labelUnattended, got, beforeCancelled+1)
|
||||
}
|
||||
if got := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended); got != beforeDeferred {
|
||||
t.Errorf("%s[%s] = %d, want unchanged %d (a deleted agent must cancel, not defer)",
|
||||
metricDeferredWorkspace, labelUnattended, got, beforeDeferred)
|
||||
}
|
||||
|
||||
got, err := svc.GetRun(ctx, run.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("get run: %v", err)
|
||||
}
|
||||
if got.Status != service.RunStatusCancelled {
|
||||
t.Errorf("run status = %q, want %q", got.Status, service.RunStatusCancelled)
|
||||
}
|
||||
if got.RetryCount != 0 {
|
||||
t.Errorf("retry_count = %d, want 0 (cancelled, never retried)", got.RetryCount)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_MetricCancelledNoWorkspace covers gate 1 via AdmitRunForTest
|
||||
// rather than the full scheduler pipeline: GetAgentFromConfig's own
|
||||
// agentInstanceFilter (workspace_id must be non-empty) means a real
|
||||
// ClaimNextRun/processRun cycle can never hand admitRun an agent with an
|
||||
// empty WorkspaceID, mirroring resolveRunProject's already-documented
|
||||
// unreachable branches. The gate 1 code path itself is real and still needs
|
||||
// coverage.
|
||||
func TestAdmitRun_MetricCancelledNoWorkspace(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-no-workspace", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
|
||||
unresolvedAgent := *agent
|
||||
unresolvedAgent.WorkspaceID = ""
|
||||
service.AdmitRunForTest(svc, ctx, run, &unresolvedAgent)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricCancelledNoWS, labelUnattended, got, before+1)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_MetricCancelledStaleDeferral drives admitBudgetDeferral's
|
||||
// stale branch by backdating a claimed run's RequestedAt past retryMaxAge,
|
||||
// mirroring the RetryCount mutation the MaxRetryCount test in
|
||||
// budget_admission_test.go already uses to reach a similar deep branch.
|
||||
func TestAdmitRun_MetricCancelledStaleDeferral(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricCancelledStale, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-stale-deferral", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
run, err := svc.ClaimNextRun(ctx)
|
||||
if err != nil || run == nil {
|
||||
t.Fatalf("claim: %v", err)
|
||||
}
|
||||
run.RequestedAt = time.Now().Add(-25 * time.Hour)
|
||||
|
||||
service.ProcessRunForTest(svc, ctx, run)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricCancelledStale, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricCancelledStale, labelUnattended, got, before+1)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAdmitRun_MetricAdmittedDefault(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch},
|
||||
defaultResult: models.PreLaunchPolicyResult{IsDefault: true},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricAdmittedDefault, labelUnattended)
|
||||
beforeDegraded := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-admitted-default", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricAdmittedDefault, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricAdmittedDefault, labelUnattended, got, before+1)
|
||||
}
|
||||
if got := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended); got != beforeDegraded {
|
||||
t.Errorf("%s[%s] = %d, want unchanged %d (default was not degraded)", metricAdmittedDegradedWin, labelUnattended, got, beforeDegraded)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_MetricAdmittedDegradedWindow_ViaDefault covers the gate-5
|
||||
// branch of AC-OFFICE-BUDGET-005.4's carved-out counter: the default's
|
||||
// window was degraded but did not block, and the run still launches.
|
||||
func TestAdmitRun_MetricAdmittedDegradedWindow_ViaDefault(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch},
|
||||
defaultResult: models.PreLaunchPolicyResult{
|
||||
IsDefault: true, Degraded: true, DegradationBlocked: false, LimitExceeded: false,
|
||||
},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended)
|
||||
|
||||
agent := makeAgent("worker-metric-degraded-default", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricAdmittedDegradedWin, labelUnattended, got, before+1)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdmitRun_MetricAdmittedDegradedWindow_ViaStoredPolicyBypassingGate5
|
||||
// covers the other launch point that can carry a degraded-admitted policy:
|
||||
// an attended run, whose provenance bypasses gate 5 entirely, but which was
|
||||
// still admitted against a stored policy's degraded window at gate 4.
|
||||
func TestAdmitRun_MetricAdmittedDegradedWindow_ViaStoredPolicyBypassingGate5(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
fake := &fakeBudgetEvaluator{
|
||||
preLaunchResult: models.PreLaunchResult{
|
||||
Decision: models.PreLaunchDecisionLaunch,
|
||||
Policies: []models.PreLaunchPolicyResult{
|
||||
{PolicyID: "p-degraded-admitted", Degraded: true, DegradationBlocked: false, LimitExceeded: false},
|
||||
},
|
||||
},
|
||||
}
|
||||
svc.SetBudgetChecker(fake)
|
||||
ctx := context.Background()
|
||||
before := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelAttended)
|
||||
|
||||
agent := makeAgent("worker-metric-degraded-attended", models.AgentRoleWorker)
|
||||
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
|
||||
t.Fatalf("create agent: %v", err)
|
||||
}
|
||||
insertTestTask(t, svc, "task-metric-degraded-attended", "ws-1")
|
||||
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
|
||||
`{"task_id":"task-metric-degraded-attended"}`, ""); err != nil {
|
||||
t.Fatalf("queue: %v", err)
|
||||
}
|
||||
|
||||
service.RunSchedulerTick(svc, ctx)
|
||||
|
||||
if got := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelAttended); got != before+1 {
|
||||
t.Errorf("%s[%s] = %d, want %d", metricAdmittedDegradedWin, labelAttended, got, before+1)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
package service
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"go.uber.org/zap"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
)
|
||||
|
||||
const (
|
||||
actionBudgetPolicySkipped = "run_budget_policy_skipped"
|
||||
actionBudgetPolicyDegradedAdmitted = "run_budget_policy_degraded_admitted"
|
||||
)
|
||||
|
||||
// utcDayStart returns the UTC midnight at or before at, the dedup boundary
|
||||
// AC-OFFICE-BUDGET-002.13 and AC-OFFICE-BUDGET-004.8 share.
|
||||
func utcDayStart(at time.Time) time.Time {
|
||||
u := at.UTC()
|
||||
return time.Date(u.Year(), u.Month(), u.Day(), 0, 0, 0, 0, time.UTC)
|
||||
}
|
||||
|
||||
// skipIssueLabels renders a stored policy's PolicyValidationIssues as a
|
||||
// stable, sorted list of short field names, so one activity entry can name
|
||||
// every violation a policy has at once (AC-OFFICE-BUDGET-002.13), rather
|
||||
// than one entry per violated field.
|
||||
func skipIssueLabels(issues models.PolicyValidationIssues) []string {
|
||||
var out []string
|
||||
if issues.UnrecognizedPeriod {
|
||||
out = append(out, "unrecognized_period")
|
||||
}
|
||||
if issues.NonPositiveLimit {
|
||||
out = append(out, "non_positive_limit")
|
||||
}
|
||||
if issues.UnrecognizedScope {
|
||||
out = append(out, "unrecognized_scope")
|
||||
}
|
||||
if issues.UnrecognizedAction {
|
||||
out = append(out, "unrecognized_action")
|
||||
}
|
||||
if issues.EmptyScopeID {
|
||||
out = append(out, "empty_scope_id")
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// skippedPolicyFields renders a skipped policy's activity-entry fields.
|
||||
// AC-OFFICE-BUDGET-002.5 requires naming the unrecognized period value and
|
||||
// AC-OFFICE-BUDGET-002.11 requires naming the non-positive limit itself,
|
||||
// alongside the policy id and the (already-present) issue labels that
|
||||
// satisfy AC-OFFICE-BUDGET-002.14's "offending field" for the remaining
|
||||
// issues.
|
||||
func skippedPolicyFields(p *models.PreLaunchPolicyResult) map[string]string {
|
||||
fields := map[string]string{
|
||||
"policy_id": p.PolicyID,
|
||||
"issues": strings.Join(skipIssueLabels(p.SkipIssues), ","),
|
||||
}
|
||||
if p.SkipIssues.UnrecognizedPeriod {
|
||||
fields["period"] = string(p.Period)
|
||||
}
|
||||
if p.SkipIssues.NonPositiveLimit {
|
||||
fields["limit_subcents"] = strconv.FormatInt(p.LimitSubcents, 10)
|
||||
}
|
||||
return fields
|
||||
}
|
||||
|
||||
// isDegradedAdmitted reports whether p's window was pricing-degraded but did
|
||||
// not itself block the run -- the condition AC-OFFICE-BUDGET-004.4/-004.7/
|
||||
// -004.8's activity entry and AC-OFFICE-BUDGET-005.4's "admitted against a
|
||||
// pricing-degraded window" counter share.
|
||||
func isDegradedAdmitted(p *models.PreLaunchPolicyResult) bool {
|
||||
return p.Degraded && !p.DegradationBlocked && !p.LimitExceeded
|
||||
}
|
||||
|
||||
// anyDegradedAdmitted reports whether any policy in policies satisfies
|
||||
// isDegradedAdmitted, for admitRun's AC-OFFICE-BUDGET-005.4 counter, which
|
||||
// must fire at most once per run regardless of how many policies qualify.
|
||||
func anyDegradedAdmitted(policies []models.PreLaunchPolicyResult) bool {
|
||||
for i := range policies {
|
||||
if isDegradedAdmitted(&policies[i]) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// logPolicyObservability writes the operator-visible entries
|
||||
// AC-OFFICE-BUDGET-002.5/-002.11/-002.14 (a stored policy this build cannot
|
||||
// evaluate, skipped) and AC-OFFICE-BUDGET-004.4/-004.7/-004.8 (a policy's
|
||||
// window was pricing-degraded but did not block via degradation) require,
|
||||
// each deduplicated at most once per policy per UTC day
|
||||
// (AC-OFFICE-BUDGET-002.13). Called once per admission evaluation of a set
|
||||
// of policies (the stored policies from EvaluatePreLaunch, or a single
|
||||
// built-in default result from EvaluateDefaultCeiling) independent of the
|
||||
// run's final decision: AC-OFFICE-BUDGET-005.4 states the degraded-admitted
|
||||
// entry is written per non-blocking-degraded policy even when a later
|
||||
// policy or gate 5 still blocks the run overall — only the *counter*, not
|
||||
// this entry, is conditioned on the run's final disposition; see
|
||||
// incBudgetAdmittedDegradedWindow's own call sites in budget_admission.go
|
||||
// for where that conditioning happens.
|
||||
func (si *SchedulerIntegration) logPolicyObservability(
|
||||
ctx context.Context, workspaceID, runID string, policies []models.PreLaunchPolicyResult, at time.Time,
|
||||
) {
|
||||
day := utcDayStart(at)
|
||||
for i := range policies {
|
||||
p := &policies[i]
|
||||
switch {
|
||||
case p.Skipped:
|
||||
si.logOncePerPolicyPerDay(ctx, workspaceID, runID, actionBudgetPolicySkipped, p.PolicyID, day,
|
||||
skippedPolicyFields(p))
|
||||
case isDegradedAdmitted(p):
|
||||
fields := map[string]string{"degraded": strconv.FormatBool(true)}
|
||||
if p.IsDefault {
|
||||
fields[activityFieldCeiling] = ceilingBuiltInDefault
|
||||
} else {
|
||||
fields["policy_id"] = p.PolicyID
|
||||
}
|
||||
si.logOncePerPolicyPerDay(ctx, workspaceID, runID, actionBudgetPolicyDegradedAdmitted, p.PolicyID, day, fields)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// logOncePerPolicyPerDay writes one activity entry for (workspaceID, action,
|
||||
// targetID) unless one already exists with created_at on or after day.
|
||||
// Best-effort under concurrency, per AC-OFFICE-BUDGET-002.13: two runs
|
||||
// evaluating the same policy concurrently may each observe no entry yet and
|
||||
// each write one. A duplicate is acceptable; this bound exists to stop a
|
||||
// per-evaluation stream, not to guarantee uniqueness.
|
||||
func (si *SchedulerIntegration) logOncePerPolicyPerDay(
|
||||
ctx context.Context, workspaceID, runID, action, targetID string, day time.Time, fields map[string]string,
|
||||
) {
|
||||
exists, err := si.svc.repo.HasActivityToday(ctx, workspaceID, action, targetID, day)
|
||||
if err != nil {
|
||||
si.logger.Warn("failed to check budget activity dedup",
|
||||
zap.String("action", action), zap.String("target_id", targetID), zap.Error(err))
|
||||
return
|
||||
}
|
||||
if exists {
|
||||
return
|
||||
}
|
||||
si.svc.LogActivityWithRun(ctx, workspaceID, "scheduler", "office-scheduler",
|
||||
action, "policy", targetID, mustJSON(fields), runID, "")
|
||||
}
|
||||
@@ -0,0 +1,203 @@
|
||||
package service_test
|
||||
|
||||
// Covers AC-OFFICE-BUDGET-002.5/-002.11/-002.14 (a stored policy this build
|
||||
// cannot evaluate is skipped, and the skip is operator-visible), and
|
||||
// AC-OFFICE-BUDGET-004.4/-004.7/-004.8 (a pricing-degraded, non-blocking
|
||||
// policy is operator-visible too), plus the AC-OFFICE-BUDGET-002.13
|
||||
// at-most-once-per-policy-per-UTC-day dedup bound both share.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
"github.com/kandev/kandev/internal/office/service"
|
||||
)
|
||||
|
||||
func activityDetails(t *testing.T, svc *service.Service, wsID, action string) (string, bool) {
|
||||
t.Helper()
|
||||
entries, err := svc.ListActivity(context.Background(), wsID, 50)
|
||||
if err != nil {
|
||||
t.Fatalf("list activity: %v", err)
|
||||
}
|
||||
for _, e := range entries {
|
||||
if string(e.Action) == action {
|
||||
return e.Details, true
|
||||
}
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
func countActivityAction(t *testing.T, svc *service.Service, wsID, action string) int {
|
||||
t.Helper()
|
||||
entries, err := svc.ListActivity(context.Background(), wsID, 50)
|
||||
if err != nil {
|
||||
t.Fatalf("list activity: %v", err)
|
||||
}
|
||||
n := 0
|
||||
for _, e := range entries {
|
||||
if string(e.Action) == action {
|
||||
n++
|
||||
}
|
||||
}
|
||||
return n
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_SkippedPolicy_NamesPolicyAndIssues covers
|
||||
// AC-OFFICE-BUDGET-002.5/-002.11/-002.14: a skipped policy's entry names
|
||||
// the policy and every violated field, not just one.
|
||||
func TestLogPolicyObservability_SkippedPolicy_NamesPolicyAndIssues(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
policies := []models.PreLaunchPolicyResult{
|
||||
{
|
||||
PolicyID: "policy-skip-1",
|
||||
Skipped: true,
|
||||
SkipIssues: models.PolicyValidationIssues{
|
||||
NonPositiveLimit: true,
|
||||
UnrecognizedScope: true,
|
||||
},
|
||||
},
|
||||
}
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
|
||||
|
||||
details, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_skipped")
|
||||
if !ok {
|
||||
t.Fatal("expected run_budget_policy_skipped activity entry")
|
||||
}
|
||||
if !strings.Contains(details, "policy-skip-1") {
|
||||
t.Errorf("details = %q, want policy id policy-skip-1", details)
|
||||
}
|
||||
if !strings.Contains(details, "non_positive_limit") || !strings.Contains(details, "unrecognized_scope") {
|
||||
t.Errorf("details = %q, want both violated issues named", details)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_SkippedPolicy_DedupedPerDay covers
|
||||
// AC-OFFICE-BUDGET-002.13: the same policy's skip is recorded at most once
|
||||
// per UTC day, not once per evaluation.
|
||||
func TestLogPolicyObservability_SkippedPolicy_DedupedPerDay(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
policies := []models.PreLaunchPolicyResult{
|
||||
{PolicyID: "policy-skip-dedup", Skipped: true, SkipIssues: models.PolicyValidationIssues{NonPositiveLimit: true}},
|
||||
}
|
||||
now := time.Now()
|
||||
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, now)
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-2", policies, now)
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-3", policies, now)
|
||||
|
||||
if n := countActivityAction(t, svc, "ws-1", "run_budget_policy_skipped"); n != 1 {
|
||||
t.Errorf("run_budget_policy_skipped entries = %d, want exactly 1 (deduped)", n)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_SkippedPolicy_NewDayWritesAgain covers the
|
||||
// other side of AC-OFFICE-BUDGET-002.13's bound: the dedup is per UTC day,
|
||||
// not forever, so a later day's evaluation writes a fresh entry. The first
|
||||
// entry is backdated directly (CreateActivityEntry always stamps real
|
||||
// wall-clock time, not the evaluation instant passed to
|
||||
// logPolicyObservability, which is always time.Now().UTC() in production)
|
||||
// to simulate "written yesterday" without waiting a real day.
|
||||
func TestLogPolicyObservability_SkippedPolicy_NewDayWritesAgain(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
policies := []models.PreLaunchPolicyResult{
|
||||
{PolicyID: "policy-skip-newday", Skipped: true, SkipIssues: models.PolicyValidationIssues{NonPositiveLimit: true}},
|
||||
}
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
|
||||
|
||||
svc.ExecSQL(t, `UPDATE office_activity_log SET created_at = ? WHERE action = ?`,
|
||||
time.Now().UTC().Add(-25*time.Hour), "run_budget_policy_skipped")
|
||||
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-2", policies, time.Now())
|
||||
|
||||
if n := countActivityAction(t, svc, "ws-1", "run_budget_policy_skipped"); n != 2 {
|
||||
t.Errorf("run_budget_policy_skipped entries across two days = %d, want 2", n)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_DegradedNonBlocking_WritesAdmittedEntry covers
|
||||
// AC-OFFICE-BUDGET-004.4/-004.7: a policy whose window was pricing-degraded
|
||||
// but which did not block (degradation exempted it, or the limit was not
|
||||
// reached) gets an operator-visible, distinctly-actioned entry.
|
||||
func TestLogPolicyObservability_DegradedNonBlocking_WritesAdmittedEntry(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
policies := []models.PreLaunchPolicyResult{
|
||||
{PolicyID: "policy-degraded-1", Degraded: true, DegradationBlocked: false, LimitExceeded: false},
|
||||
}
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
|
||||
|
||||
details, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted")
|
||||
if !ok {
|
||||
t.Fatal("expected run_budget_policy_degraded_admitted activity entry")
|
||||
}
|
||||
if !strings.Contains(details, "policy-degraded-1") {
|
||||
t.Errorf("details = %q, want policy id policy-degraded-1", details)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_DegradedButLimitExceeded_NoAdmittedEntry
|
||||
// covers AC-OFFICE-BUDGET-004.6: when the limit was also reached, the
|
||||
// degradation fact belongs on the block entry alone (already carried by
|
||||
// finishPolicyBlock's "degraded" field) -- this policy is not "admitted",
|
||||
// so it must not also get a degraded-admitted entry.
|
||||
func TestLogPolicyObservability_DegradedButLimitExceeded_NoAdmittedEntry(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
policies := []models.PreLaunchPolicyResult{
|
||||
{PolicyID: "policy-degraded-exceeded", Degraded: true, DegradationBlocked: false, LimitExceeded: true},
|
||||
}
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
|
||||
|
||||
if _, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted"); ok {
|
||||
t.Error("a policy whose limit was exceeded must not get a degraded-admitted entry")
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_DegradedAndBlocked_NoAdmittedEntry covers the
|
||||
// symmetric case: a policy whose degradation criterion itself blocked
|
||||
// (DegradationBlocked) is reported via the block entry, not this one.
|
||||
func TestLogPolicyObservability_DegradedAndBlocked_NoAdmittedEntry(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
policies := []models.PreLaunchPolicyResult{
|
||||
{PolicyID: "policy-degraded-blocked", Degraded: true, DegradationBlocked: true, LimitExceeded: false},
|
||||
}
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
|
||||
|
||||
if _, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted"); ok {
|
||||
t.Error("a policy that blocked via degradation must not also get a degraded-admitted entry")
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogPolicyObservability_DefaultCeilingDegraded_NamesBuiltInDefault
|
||||
// covers AC-OFFICE-BUDGET-004.8's "or stating that the ceiling was the
|
||||
// built-in default" alternative to naming a policy id.
|
||||
func TestLogPolicyObservability_DefaultCeilingDegraded_NamesBuiltInDefault(t *testing.T) {
|
||||
svc := newTestService(t)
|
||||
ctx := context.Background()
|
||||
|
||||
def := models.PreLaunchPolicyResult{
|
||||
IsDefault: true, Degraded: true, DegradationBlocked: false, LimitExceeded: false,
|
||||
}
|
||||
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", []models.PreLaunchPolicyResult{def}, time.Now())
|
||||
|
||||
details, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted")
|
||||
if !ok {
|
||||
t.Fatal("expected run_budget_policy_degraded_admitted activity entry for the built-in default")
|
||||
}
|
||||
if !strings.Contains(details, "built_in_default") {
|
||||
t.Errorf("details = %q, want the built-in default named", details)
|
||||
}
|
||||
}
|
||||
@@ -2,6 +2,8 @@ package service
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"errors"
|
||||
"fmt"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/models"
|
||||
@@ -13,16 +15,30 @@ func (s *Service) ListAgentsFromConfig(ctx context.Context, workspaceID string)
|
||||
return s.repo.ListAgentInstances(ctx, workspaceID)
|
||||
}
|
||||
|
||||
// GetAgentFromConfig looks up an agent by ID or name.
|
||||
// GetAgentFromConfig looks up an agent by ID or name. The error it returns
|
||||
// wraps sql.ErrNoRows if, and only if, both underlying lookups genuinely
|
||||
// found no matching row -- never if either failed for another reason (a
|
||||
// transient I/O error). Callers that must tell "no such agent" apart from
|
||||
// a transient failure (AC-OFFICE-BUDGET-001.13) use errors.Is(err,
|
||||
// sql.ErrNoRows) rather than a second lookup or a new sentinel type; this
|
||||
// is the same two calls as before, just no longer collapsing a real error
|
||||
// into the generic not-found string.
|
||||
func (s *Service) GetAgentFromConfig(ctx context.Context, idOrName string) (*models.AgentInstance, error) {
|
||||
if agent, err := s.repo.GetAgentInstance(ctx, idOrName); err == nil {
|
||||
agent, errByID := s.repo.GetAgentInstance(ctx, idOrName)
|
||||
if errByID == nil {
|
||||
return agent, nil
|
||||
}
|
||||
agent, err := s.repo.GetAgentInstanceByNameAny(ctx, idOrName)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("agent not found: %s", idOrName)
|
||||
agent, errByName := s.repo.GetAgentInstanceByNameAny(ctx, idOrName)
|
||||
if errByName == nil {
|
||||
return agent, nil
|
||||
}
|
||||
return agent, nil
|
||||
if !errors.Is(errByID, sql.ErrNoRows) {
|
||||
return nil, errByID
|
||||
}
|
||||
if !errors.Is(errByName, sql.ErrNoRows) {
|
||||
return nil, errByName
|
||||
}
|
||||
return nil, fmt.Errorf("agent not found: %s: %w", idOrName, sql.ErrNoRows)
|
||||
}
|
||||
|
||||
// ListSkillsFromConfig returns all skills for a workspace.
|
||||
|
||||
@@ -148,6 +148,36 @@ func (s *Service) escalateFailure(
|
||||
return nil
|
||||
}
|
||||
|
||||
// failRunNoEscalation performs escalateFailure's non-escalating half for a
|
||||
// budget-admission fault (AC-OFFICE-BUDGET-001.17/-006.4): it marks the run
|
||||
// permanently failed and records one operator-visible activity entry
|
||||
// naming cause, but does not re-fetch the agent and does not call
|
||||
// queueCEOAgentError. A run failed by a budget-admission fault must not
|
||||
// queue any new run, by any path.
|
||||
func (s *Service) failRunNoEscalation(
|
||||
ctx context.Context, run *models.Run, agent *models.AgentInstance,
|
||||
cause budgetDeferralCause, policyID string,
|
||||
) error {
|
||||
if err := s.FailRun(ctx, run.ID); err != nil {
|
||||
return fmt.Errorf("fail run: %w", err)
|
||||
}
|
||||
s.clearAgentWorking(ctx, run.AgentProfileID, run.ID)
|
||||
|
||||
fields := map[string]string{activityFieldCeiling: ceilingNotDetermined}
|
||||
if policyID != "" {
|
||||
fields["policy_id"] = policyID
|
||||
}
|
||||
s.LogActivityWithRun(ctx, agent.WorkspaceID, "system", "scheduler",
|
||||
cause.failedAction(), "agent", run.AgentProfileID,
|
||||
mustJSON(fields), run.ID, "")
|
||||
|
||||
s.logger.Warn("run permanently failed by budget admission fault",
|
||||
zap.String("run_id", run.ID),
|
||||
zap.String("agent", agent.Name),
|
||||
zap.Int("retry_count", run.RetryCount))
|
||||
return nil
|
||||
}
|
||||
|
||||
// queueCEOAgentError finds the CEO agent in the workspace and queues an
|
||||
// agent_error run for it. When the failing run's agent IS the CEO, the
|
||||
// escalation is skipped rather than re-queuing the CEO to handle its own
|
||||
|
||||
@@ -56,16 +56,17 @@ const (
|
||||
|
||||
// Run outcome constants (docs/specs/task-delivery-ledger/spec.md, "Office run
|
||||
// outcome"). Written into runs.outcome alongside status='finished' at each of
|
||||
// the six terminal call sites; NULL on the failed path and on every
|
||||
// the seven terminal call sites; NULL on the failed path and on every
|
||||
// pre-activation row. RunOutcomeProcessed is the only value
|
||||
// RunCountsByDayForAgent counts as succeeded. Every other value buckets into
|
||||
// skipped.
|
||||
const (
|
||||
RunOutcomeProcessed = "processed"
|
||||
RunOutcomeBudgetBlocked = "budget_blocked"
|
||||
RunOutcomeIdleSkipped = "idle_skipped"
|
||||
RunOutcomeAgentInactive = "agent_inactive"
|
||||
RunOutcomeTaskTreeHeld = "task_tree_held"
|
||||
RunOutcomeProcessed = "processed"
|
||||
RunOutcomeBudgetBlocked = "budget_blocked"
|
||||
RunOutcomeIdleSkipped = "idle_skipped"
|
||||
RunOutcomeAgentInactive = "agent_inactive"
|
||||
RunOutcomeTaskTreeHeld = "task_tree_held"
|
||||
RunOutcomeBudgetUnmeasurable = "budget_unmeasurable"
|
||||
)
|
||||
|
||||
// CoalesceWindowSeconds is the default coalescing window.
|
||||
|
||||
@@ -2,6 +2,8 @@ package service
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"errors"
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
@@ -201,12 +203,25 @@ func (si *SchedulerIntegration) processRun(ctx context.Context, run *models.Run)
|
||||
"reason": run.Reason,
|
||||
})
|
||||
|
||||
// Guard: check agent status.
|
||||
// Guard: check agent status. AC-OFFICE-BUDGET-001.13 gives the two ways
|
||||
// this lookup can fail different dispositions: a genuine "no such
|
||||
// agent" (soft-deleted or never existed) is cancelled, never retried or
|
||||
// escalated, since an orphaned run has no workspace and therefore no
|
||||
// ceiling that could ever be evaluated; a transient lookup error is
|
||||
// deferred/retried on the same terms as an evaluator fault and, at
|
||||
// MaxRetryCount, failed without escalation (AC-OFFICE-BUDGET-006.4) --
|
||||
// neither disposition may queue a run for any other agent
|
||||
// (AC-OFFICE-BUDGET-001.17), so neither uses the generic
|
||||
// HandleRunFailure/escalateFailure path, which does exactly that.
|
||||
agent, err := si.svc.GetAgentFromConfig(ctx, agentInstanceID)
|
||||
if err != nil {
|
||||
si.logger.Error("failed to get agent instance",
|
||||
zap.String("run_id", runID), zap.Error(err))
|
||||
_ = si.svc.HandleRunFailure(ctx, run, err)
|
||||
if errors.Is(err, sql.ErrNoRows) {
|
||||
si.cancelUnresolvableAgentRun(ctx, run)
|
||||
return
|
||||
}
|
||||
si.deferWorkspaceLookupFailure(ctx, run)
|
||||
return
|
||||
}
|
||||
|
||||
@@ -254,8 +269,8 @@ func (si *SchedulerIntegration) processRun(ctx context.Context, run *models.Run)
|
||||
return
|
||||
}
|
||||
|
||||
// Pre-execution budget check.
|
||||
if !si.checkBudget(ctx, run, agent, taskID) {
|
||||
// Pre-launch budget admission (AC-OFFICE-BUDGET-001.14's five gates).
|
||||
if !si.admitRun(ctx, run, agent) {
|
||||
return
|
||||
}
|
||||
|
||||
@@ -831,38 +846,6 @@ func (si *SchedulerIntegration) requeueContendedCheckout(ctx context.Context, ru
|
||||
}
|
||||
}
|
||||
|
||||
// checkBudget runs pre-execution budget checks. Returns true if allowed.
|
||||
func (si *SchedulerIntegration) checkBudget(
|
||||
ctx context.Context, run *models.Run,
|
||||
agent *models.AgentInstance, taskID string,
|
||||
) bool {
|
||||
projectID := si.extractProjectID(ctx, run.Payload)
|
||||
allowed, reason, err := si.svc.CheckPreExecutionBudget(
|
||||
ctx, agent.ID, projectID, agent.WorkspaceID)
|
||||
if err != nil {
|
||||
si.logger.Error("budget check failed",
|
||||
zap.String("run_id", run.ID), zap.Error(err))
|
||||
return true // fail-open on error
|
||||
}
|
||||
if !allowed {
|
||||
si.logger.Info("run skipped (budget exceeded)",
|
||||
zap.String("run_id", run.ID), zap.String("reason", reason))
|
||||
si.releaseCheckoutIfNeeded(ctx, run)
|
||||
si.svc.clearAgentWorking(ctx, agent.ID, run.ID)
|
||||
_ = si.svc.FinishRun(ctx, run.ID, RunOutcomeBudgetBlocked)
|
||||
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID,
|
||||
"scheduler", "office-scheduler",
|
||||
"run_budget_blocked", "run", run.ID,
|
||||
mustJSON(map[string]string{
|
||||
"agent": agent.Name,
|
||||
"agent_id": agent.ID,
|
||||
"reason": reason,
|
||||
}), run.ID, "")
|
||||
return false
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// releaseCheckoutIfNeeded releases the task checkout the given run may hold.
|
||||
// Delegates to the owner-scoped releaseTaskCheckoutForRun (Review round 3)
|
||||
// rather than the unscoped repo.ReleaseTaskCheckout: every call site here
|
||||
|
||||
@@ -4,11 +4,13 @@ package service
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/kandev/kandev/internal/agentctl/types/streams"
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
@@ -360,6 +362,22 @@ type BudgetEvaluator interface {
|
||||
// pause). The office service discards the per-policy results; the
|
||||
// costs package is responsible for any side effects.
|
||||
EvaluateBudget(ctx context.Context, workspaceID, agentInstanceID, projectID string) error
|
||||
|
||||
// EvaluatePreLaunch and EvaluateDefaultCeiling back the pre-launch
|
||||
// admission gates of REQ-OFFICE-BUDGET-001/-003/-006
|
||||
// (internal/office/service/budget_admission.go). Unlike
|
||||
// CheckPreExecutionBudget/EvaluateBudget above, neither has a
|
||||
// nil-evaluator fallback: "no evaluator wired" is its own admission gate
|
||||
// (AC-OFFICE-BUDGET-001.5/.6), decided by the caller before either method
|
||||
// is invoked, never a fail-open default inside it.
|
||||
EvaluatePreLaunch(
|
||||
ctx context.Context,
|
||||
workspaceID, agentInstanceID, projectID string,
|
||||
hasProject bool,
|
||||
provenance shared.RunProvenance,
|
||||
at time.Time,
|
||||
) (models.PreLaunchResult, error)
|
||||
EvaluateDefaultCeiling(ctx context.Context, workspaceID string, at time.Time) (models.PreLaunchPolicyResult, error)
|
||||
}
|
||||
|
||||
// SetBudgetChecker wires the costs.CostService (or a test fake) as the
|
||||
@@ -749,6 +767,46 @@ func (s *Service) CheckBudget(ctx context.Context, workspaceID, agentInstanceID,
|
||||
return s.budgetChecker.EvaluateBudget(ctx, workspaceID, agentInstanceID, projectID)
|
||||
}
|
||||
|
||||
// errBudgetEvaluatorNotConfigured is returned by EvaluatePreLaunch and
|
||||
// EvaluateDefaultCeiling when no BudgetEvaluator is wired. Unlike
|
||||
// CheckBudget's no-op, both calls always need a real disposition -- there
|
||||
// is no zero-value PreLaunchResult/PreLaunchPolicyResult that means
|
||||
// anything -- so a nil budgetChecker is a distinguishable error rather than
|
||||
// a silent no-op. Safe today only because admitRun's gate 2
|
||||
// (budget_admission.go) already checks budgetChecker == nil before either
|
||||
// is ever called; this guard is what keeps a future caller that skips gate
|
||||
// 2 from a nil-pointer dereference instead.
|
||||
var errBudgetEvaluatorNotConfigured = errors.New("office: no budget evaluator configured")
|
||||
|
||||
// EvaluatePreLaunch delegates to the wired BudgetEvaluator for the
|
||||
// pre-launch admission gates (budget_admission.go). Callers must check
|
||||
// gate 2 (evaluator presence, s.budgetChecker == nil) themselves before
|
||||
// calling this — see the BudgetEvaluator doc comment above.
|
||||
func (s *Service) EvaluatePreLaunch(
|
||||
ctx context.Context,
|
||||
workspaceID, agentInstanceID, projectID string,
|
||||
hasProject bool,
|
||||
provenance shared.RunProvenance,
|
||||
at time.Time,
|
||||
) (models.PreLaunchResult, error) {
|
||||
if s.budgetChecker == nil {
|
||||
return models.PreLaunchResult{}, errBudgetEvaluatorNotConfigured
|
||||
}
|
||||
return s.budgetChecker.EvaluatePreLaunch(ctx, workspaceID, agentInstanceID, projectID, hasProject, provenance, at)
|
||||
}
|
||||
|
||||
// EvaluateDefaultCeiling delegates to the wired BudgetEvaluator for gate 5
|
||||
// of budget_admission.go. See EvaluatePreLaunch above for the nil-evaluator
|
||||
// caveat.
|
||||
func (s *Service) EvaluateDefaultCeiling(
|
||||
ctx context.Context, workspaceID string, at time.Time,
|
||||
) (models.PreLaunchPolicyResult, error) {
|
||||
if s.budgetChecker == nil {
|
||||
return models.PreLaunchPolicyResult{}, errBudgetEvaluatorNotConfigured
|
||||
}
|
||||
return s.budgetChecker.EvaluateDefaultCeiling(ctx, workspaceID, at)
|
||||
}
|
||||
|
||||
// CreateBudgetPolicy creates a new budget policy.
|
||||
func (s *Service) CreateBudgetPolicy(ctx context.Context, policy *models.BudgetPolicy) error {
|
||||
return s.repo.CreateBudgetPolicy(ctx, policy)
|
||||
|
||||
@@ -2,6 +2,7 @@ package service
|
||||
|
||||
import (
|
||||
"context"
|
||||
"expvar"
|
||||
"fmt"
|
||||
"testing"
|
||||
"time"
|
||||
@@ -168,6 +169,55 @@ func ProcessRunForTest(svc *Service, ctx context.Context, run *models.Run) {
|
||||
si.processRun(ctx, run)
|
||||
}
|
||||
|
||||
// Exported mirrors of resolveRunProject's unexported projectResolution
|
||||
// values, for external test packages using ResolveRunProjectForTest.
|
||||
const (
|
||||
ProjectResolutionNoneForTest = int(projectResolutionNone)
|
||||
ProjectResolutionFoundForTest = int(projectResolutionFound)
|
||||
ProjectResolutionLookupErrorForTest = int(projectResolutionLookupError)
|
||||
ProjectResolutionUnparseableForTest = int(projectResolutionUnparseable)
|
||||
ProjectResolutionTaskNotFoundForTest = int(projectResolutionTaskNotFound)
|
||||
)
|
||||
|
||||
// ResolveRunProjectForTest exposes resolveRunProject for external test
|
||||
// packages, so gate 4's project-resolution outcomes
|
||||
// (AC-OFFICE-BUDGET-006.7) can be tested directly rather than through the
|
||||
// full scheduler pipeline, which independently gates on task existence in
|
||||
// checkoutTask before admitRun/resolveRunProject ever runs.
|
||||
func ResolveRunProjectForTest(svc *Service, ctx context.Context, payload string) (projectID string, resolution int) {
|
||||
si := &SchedulerIntegration{svc: svc, logger: svc.logger}
|
||||
pid, res := si.resolveRunProject(ctx, payload)
|
||||
return pid, int(res)
|
||||
}
|
||||
|
||||
// AdmitRunForTest exposes admitRun directly for external test packages, so
|
||||
// gate 1's "agent found but carries no workspace identifier" branch
|
||||
// (AC-OFFICE-BUDGET-001.13) can be tested against a constructed
|
||||
// *models.AgentInstance rather than through the full scheduler pipeline.
|
||||
// The repository's own agentInstanceFilter (workspace_id must be non-empty) makes an
|
||||
// empty-WorkspaceID agent unreachable via GetAgentFromConfig, the only real
|
||||
// caller processRun uses to obtain admitRun's agent argument -- the same
|
||||
// "structurally unreachable via the full pipeline, but a real and correctly
|
||||
// implemented branch of the function itself" situation already recorded for
|
||||
// resolveRunProject's task-not-found and lookup-error outcomes.
|
||||
func AdmitRunForTest(svc *Service, ctx context.Context, run *models.Run, agent *models.AgentInstance) bool {
|
||||
si := &SchedulerIntegration{svc: svc, logger: svc.logger}
|
||||
return si.admitRun(ctx, run, agent)
|
||||
}
|
||||
|
||||
// LogPolicyObservabilityForTest exposes logPolicyObservability for external
|
||||
// test packages, so the skip/degraded-admitted entries and their
|
||||
// per-policy-per-day dedup (AC-OFFICE-BUDGET-002.13/-004.8) can be tested
|
||||
// directly against a chosen set of PreLaunchPolicyResult values, without
|
||||
// needing a real admission evaluation (stored policies, spend events) to
|
||||
// produce them.
|
||||
func LogPolicyObservabilityForTest(
|
||||
svc *Service, ctx context.Context, workspaceID, runID string, policies []models.PreLaunchPolicyResult, at time.Time,
|
||||
) {
|
||||
si := &SchedulerIntegration{svc: svc, logger: svc.logger}
|
||||
si.logPolicyObservability(ctx, workspaceID, runID, policies, at)
|
||||
}
|
||||
|
||||
// BuildEnvVarsForTest exposes buildEnvVars for external test packages.
|
||||
func BuildEnvVarsForTest(
|
||||
si *SchedulerIntegration,
|
||||
@@ -202,6 +252,34 @@ func BuildSkillManifestForTest(
|
||||
// with the office-tier delivery code. Coverage moved into
|
||||
// internal/agent/runtime/lifecycle/skill.
|
||||
|
||||
// BudgetMetricValueForTest reads the current value of an AC-OFFICE-BUDGET-
|
||||
// 005.4 expvar counter for external test packages, by its published
|
||||
// /debug/vars name (e.g. "office_budget_blocked_by_limit_total") and map
|
||||
// key (e.g. "provenance=unattended"). Reading through the global expvar
|
||||
// registry, rather than the package-private *expvar.Map vars directly,
|
||||
// means a test also pins the exact published name a real /debug/vars
|
||||
// scrape would see. Returns 0 for a key that hasn't been incremented yet.
|
||||
func BudgetMetricValueForTest(t *testing.T, name, label string) int64 {
|
||||
t.Helper()
|
||||
v := expvar.Get(name)
|
||||
if v == nil {
|
||||
t.Fatalf("no expvar registered under %q", name)
|
||||
}
|
||||
m, ok := v.(*expvar.Map)
|
||||
if !ok {
|
||||
t.Fatalf("expvar %q is a %T, want *expvar.Map", name, v)
|
||||
}
|
||||
got := m.Get(label)
|
||||
if got == nil {
|
||||
return 0
|
||||
}
|
||||
i, ok := got.(*expvar.Int)
|
||||
if !ok {
|
||||
t.Fatalf("expvar %q[%q] is a %T, want *expvar.Int", name, label, got)
|
||||
}
|
||||
return i.Value()
|
||||
}
|
||||
|
||||
// GetWakeReceiptForTest exposes the repo's parent_child_wake_receipts read
|
||||
// so ParentWakeReconciler tests can assert a paused/unresolved-assignee
|
||||
// skip leaves no partial receipt behind.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
package shared
|
||||
|
||||
// RunProvenance classifies a run as attended or unattended, per
|
||||
// REQ-OFFICE-BUDGET-007 (docs/specs/office/requirements/budget-run-provenance.md).
|
||||
// A person plausibly caused an attended run and is plausibly waiting on it.
|
||||
type RunProvenance int
|
||||
|
||||
const (
|
||||
// RunProvenanceUnattended is the safe default for any reason not on the
|
||||
// attended allowlist, including one the build has never seen.
|
||||
RunProvenanceUnattended RunProvenance = iota
|
||||
RunProvenanceAttended
|
||||
)
|
||||
|
||||
// Attended reports whether p classifies as attended.
|
||||
func (p RunProvenance) Attended() bool { return p == RunProvenanceAttended }
|
||||
|
||||
// attendedRunReasons is the exact 20-literal allowlist of
|
||||
// AC-OFFICE-BUDGET-007.2: 16 current reasons plus 4 legacy literals. Every
|
||||
// other value, including one the build does not recognize, classifies as
|
||||
// unattended (RunProvenanceUnattended's zero value).
|
||||
//
|
||||
// Polarity warning: this is the OPPOSITE safe default from
|
||||
// IsPeriodicTasklessWake, which reads the same runs.reason column for the
|
||||
// idle-skip gate. Do not reuse that classifier here — see the glossary
|
||||
// (docs/specs/office/glossary.md, "Budget enforcement").
|
||||
var attendedRunReasons = map[string]struct{}{
|
||||
"task_assigned": {},
|
||||
"task_comment": {},
|
||||
"task_review_requested": {},
|
||||
"task_changes_requested": {},
|
||||
"task_blockers_resolved": {},
|
||||
"task_children_completed": {},
|
||||
"approval_resolved": {},
|
||||
"routine_dispatch_event": {},
|
||||
"manual_resume_after_failure": {},
|
||||
"task_mentioned": {},
|
||||
"task_reopened": {},
|
||||
"task_reopened_via_comment": {},
|
||||
"task_unblocked": {},
|
||||
"task_ready_to_close": {},
|
||||
"stage_pending": {},
|
||||
"stage_changes_requested": {},
|
||||
// Legacy literals, still reachable on rows queued before the named
|
||||
// constants above existed.
|
||||
"review_started": {},
|
||||
"approval_started": {},
|
||||
"blockers_resolved": {},
|
||||
"children_completed": {},
|
||||
}
|
||||
|
||||
// ClassifyRunProvenance implements AC-OFFICE-BUDGET-007.1/.2: a total
|
||||
// function of reason, computed once per run and never revised by any gate.
|
||||
func ClassifyRunProvenance(reason string) RunProvenance {
|
||||
if _, ok := attendedRunReasons[reason]; ok {
|
||||
return RunProvenanceAttended
|
||||
}
|
||||
return RunProvenanceUnattended
|
||||
}
|
||||
@@ -0,0 +1,218 @@
|
||||
package shared_test
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"strconv"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// This test implements AC-OFFICE-BUDGET-007.3: it derives the inventory of
|
||||
// every run-reason string literal in the Office source by reading the
|
||||
// source with go/ast — never by matching constant identifiers, and never
|
||||
// from a list of literals maintained alongside it — and fails the build
|
||||
// when one is classified by neither the attended allowlist
|
||||
// (AC-OFFICE-BUDGET-007.2, shared.ClassifyRunProvenance) nor the explicit
|
||||
// unattended list (AC-OFFICE-BUDGET-007.4, attendedForTest/unattendedForTest
|
||||
// below). It reads plain .go files with go/parser, not golang.org/x/tools/go/packages:
|
||||
// alias declarations (e.g. RunReasonHeartbeat = shared.RunReasonHeartbeat) are
|
||||
// recognized syntactically (RHS is not a string *ast.BasicLit) and skipped
|
||||
// rather than resolved, which is sufficient because the aliased constant's
|
||||
// package is itself one of the seven enumerated blocks this test scans.
|
||||
//
|
||||
// attendedForTest and unattendedForTest are declared here, independently of
|
||||
// shared.attendedRunReasons and of each other. AC-OFFICE-BUDGET-007.4
|
||||
// requires the unattended list never be computed as attendedForTest's
|
||||
// complement — a derived list would make every literal a member of one set
|
||||
// by construction, and the test could never fail.
|
||||
var attendedForTest = map[string]bool{
|
||||
"task_assigned": true,
|
||||
"task_comment": true,
|
||||
"task_review_requested": true,
|
||||
"task_changes_requested": true,
|
||||
"task_blockers_resolved": true,
|
||||
"task_children_completed": true,
|
||||
"approval_resolved": true,
|
||||
"routine_dispatch_event": true,
|
||||
"manual_resume_after_failure": true,
|
||||
"task_mentioned": true,
|
||||
"task_reopened": true,
|
||||
"task_reopened_via_comment": true,
|
||||
"task_unblocked": true,
|
||||
"task_ready_to_close": true,
|
||||
"stage_pending": true,
|
||||
"stage_changes_requested": true,
|
||||
"review_started": true,
|
||||
"approval_started": true,
|
||||
"blockers_resolved": true,
|
||||
"children_completed": true,
|
||||
}
|
||||
|
||||
var unattendedForTest = map[string]bool{
|
||||
"agent_error": true,
|
||||
"budget_alert": true,
|
||||
"heartbeat": true,
|
||||
"routine_dispatch": true,
|
||||
"routine_dispatch_cron": true,
|
||||
"routine_trigger": true,
|
||||
}
|
||||
|
||||
// runReasonBlock names one of AC-OFFICE-BUDGET-007.3's seven enumerated
|
||||
// declaration blocks, located by relative file path plus an anchor constant
|
||||
// name already known to live in that block — never by line number.
|
||||
type runReasonBlock struct {
|
||||
label string
|
||||
relPath string
|
||||
anchorName string
|
||||
}
|
||||
|
||||
var runReasonBlocks = []runReasonBlock{
|
||||
{"a", "../scheduler/run.go", "RunReasonTaskAssigned"},
|
||||
{"b (RunReason*)", "../service/run.go", "RunReasonTaskAssigned"},
|
||||
{"b (legacyRunReason*)", "../service/run.go", "legacyRunReasonBlockersResolved"},
|
||||
{"c", "./runreasons.go", "RunReasonRoutineDispatch"},
|
||||
{"d", "../routing/types.go", "WakeReasonHeartbeat"},
|
||||
{"e", "../../runs/commentkeys/commentkeys.go", "TaskCommentReason"},
|
||||
{"f", "../onboarding/service.go", "runReasonTaskAssigned"},
|
||||
{"g", "../service/failure.go", "RunReasonManualResumeAfterFailure"},
|
||||
}
|
||||
|
||||
// excludedIdentifiers is AC-OFFICE-BUDGET-007.3's exact six-entry exclusion
|
||||
// list: constants that share an enumerated block with a run reason but are
|
||||
// not themselves one. Exclusion is by name, never by inferring intent from
|
||||
// the string value.
|
||||
var excludedIdentifiers = map[string]bool{
|
||||
"RoutineSourceCron": true, // shared.RoutineSourceCron
|
||||
"TaskCommentPrefix": true, // commentkeys.TaskCommentPrefix
|
||||
"EngineDispatchedValue": true, // commentkeys.EngineDispatchedValue
|
||||
"InboxKindAgentRunFailed": true,
|
||||
"InboxKindAgentPausedAfterFails": true,
|
||||
"autoPauseReasonPrefix": true,
|
||||
}
|
||||
|
||||
func thisDir(t *testing.T) string {
|
||||
t.Helper()
|
||||
_, file, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
t.Fatal("runtime.Caller(0) failed; cannot locate test file for relative source paths")
|
||||
}
|
||||
return filepath.Dir(file)
|
||||
}
|
||||
|
||||
// findConstBlock parses path and returns the *ast.GenDecl (Tok == CONST)
|
||||
// containing a ValueSpec named anchor. Fails the test — never skips or
|
||||
// returns a smaller inventory — when the file can't be parsed or the
|
||||
// anchor isn't found, per AC-OFFICE-BUDGET-007.3's "shall fail rather than
|
||||
// pass on the smaller inventory" when a block was renamed, moved, or deleted.
|
||||
func findConstBlock(t *testing.T, path, anchor string) *ast.GenDecl {
|
||||
t.Helper()
|
||||
fset := token.NewFileSet()
|
||||
f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
|
||||
if err != nil {
|
||||
t.Fatalf("parse %s: %v", path, err)
|
||||
}
|
||||
for _, decl := range f.Decls {
|
||||
gen, ok := decl.(*ast.GenDecl)
|
||||
if !ok || gen.Tok != token.CONST {
|
||||
continue
|
||||
}
|
||||
for _, spec := range gen.Specs {
|
||||
vs, ok := spec.(*ast.ValueSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, name := range vs.Names {
|
||||
if name.Name == anchor {
|
||||
return gen
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
t.Fatalf("anchor constant %q not found in %s — enumerated block moved, renamed, "+
|
||||
"or deleted; AC-OFFICE-BUDGET-007.3 requires the build fail here rather than "+
|
||||
"silently shrink the run-reason inventory", anchor, path)
|
||||
return nil
|
||||
}
|
||||
|
||||
// literalsInBlock returns every string-literal constant value declared
|
||||
// directly in gen (an alias RHS — a *ast.SelectorExpr or *ast.Ident rather
|
||||
// than a string *ast.BasicLit — contributes no new literal and is skipped,
|
||||
// per AC-OFFICE-BUDGET-007.3), excluding any name in excludedIdentifiers.
|
||||
func literalsInBlock(gen *ast.GenDecl) map[string]bool {
|
||||
out := map[string]bool{}
|
||||
for _, spec := range gen.Specs {
|
||||
vs, ok := spec.(*ast.ValueSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for i, name := range vs.Names {
|
||||
if excludedIdentifiers[name.Name] {
|
||||
continue
|
||||
}
|
||||
if i >= len(vs.Values) {
|
||||
continue // iota-style repeated spec with no literal of its own
|
||||
}
|
||||
lit, ok := vs.Values[i].(*ast.BasicLit)
|
||||
if !ok || lit.Kind != token.STRING {
|
||||
continue // alias RHS (SelectorExpr/Ident) — no new literal
|
||||
}
|
||||
val, err := strconv.Unquote(lit.Value)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
out[val] = true
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func TestRunReasonInventory_EveryLiteralIsClassified(t *testing.T) {
|
||||
dir := thisDir(t)
|
||||
|
||||
if overlap := intersect(attendedForTest, unattendedForTest); len(overlap) > 0 {
|
||||
t.Fatalf("attendedForTest and unattendedForTest are not disjoint: %v", overlap)
|
||||
}
|
||||
|
||||
seen := map[string][]string{} // literal -> blocks it was found in
|
||||
for _, block := range runReasonBlocks {
|
||||
path := filepath.Join(dir, block.relPath)
|
||||
gen := findConstBlock(t, path, block.anchorName)
|
||||
for literal := range literalsInBlock(gen) {
|
||||
seen[literal] = append(seen[literal], block.label)
|
||||
}
|
||||
}
|
||||
|
||||
if len(seen) == 0 {
|
||||
t.Fatal("inventory came back empty — every enumerated block failed to parse " +
|
||||
"or contribute a literal; this test cannot have passed by accident")
|
||||
}
|
||||
|
||||
for literal, blocks := range seen {
|
||||
inAttended := attendedForTest[literal]
|
||||
inUnattended := unattendedForTest[literal]
|
||||
if !inAttended && !inUnattended {
|
||||
t.Errorf("run-reason literal %q (declared in block(s) %v) is classified by "+
|
||||
"neither AC-OFFICE-BUDGET-007.2's attended allowlist nor "+
|
||||
"AC-OFFICE-BUDGET-007.4's unattended list — classify it in "+
|
||||
"shared.attendedRunReasons (and mirror the choice in this test's "+
|
||||
"attendedForTest/unattendedForTest) before merging", literal, blocks)
|
||||
}
|
||||
if inAttended && inUnattended {
|
||||
t.Errorf("run-reason literal %q is in both attendedForTest and "+
|
||||
"unattendedForTest — the two lists must be disjoint", literal)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func intersect(a, b map[string]bool) []string {
|
||||
var out []string
|
||||
for k := range a {
|
||||
if b[k] {
|
||||
out = append(out, k)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
package shared_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/kandev/kandev/internal/office/shared"
|
||||
)
|
||||
|
||||
// TestClassifyRunProvenance_AttendedAllowlist pins AC-OFFICE-BUDGET-007.2's
|
||||
// exact 20-literal attended allowlist (16 current + 4 legacy).
|
||||
func TestClassifyRunProvenance_AttendedAllowlist(t *testing.T) {
|
||||
attended := []string{
|
||||
"task_assigned",
|
||||
"task_comment",
|
||||
"task_review_requested",
|
||||
"task_changes_requested",
|
||||
"task_blockers_resolved",
|
||||
"task_children_completed",
|
||||
"approval_resolved",
|
||||
"routine_dispatch_event",
|
||||
"manual_resume_after_failure",
|
||||
"task_mentioned",
|
||||
"task_reopened",
|
||||
"task_reopened_via_comment",
|
||||
"task_unblocked",
|
||||
"task_ready_to_close",
|
||||
"stage_pending",
|
||||
"stage_changes_requested",
|
||||
"review_started",
|
||||
"approval_started",
|
||||
"blockers_resolved",
|
||||
"children_completed",
|
||||
}
|
||||
if len(attended) != 20 {
|
||||
t.Fatalf("test fixture drift: want 20 attended literals, got %d", len(attended))
|
||||
}
|
||||
for _, reason := range attended {
|
||||
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceAttended {
|
||||
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceAttended", reason, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestClassifyRunProvenance_UnattendedExplicitList pins AC-OFFICE-BUDGET-007.4's
|
||||
// exact 6-literal unattended list.
|
||||
func TestClassifyRunProvenance_UnattendedExplicitList(t *testing.T) {
|
||||
unattended := []string{
|
||||
"agent_error",
|
||||
"budget_alert",
|
||||
"heartbeat",
|
||||
"routine_dispatch",
|
||||
"routine_dispatch_cron",
|
||||
"routine_trigger",
|
||||
}
|
||||
if len(unattended) != 6 {
|
||||
t.Fatalf("test fixture drift: want 6 unattended literals, got %d", len(unattended))
|
||||
}
|
||||
for _, reason := range unattended {
|
||||
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceUnattended {
|
||||
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceUnattended", reason, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestClassifyRunProvenance_UnknownReasonIsUnattended pins AC-OFFICE-BUDGET-007.2's
|
||||
// safe default: a value the build has never seen classifies unattended, never
|
||||
// as a third state and never exempt from a gate.
|
||||
func TestClassifyRunProvenance_UnknownReasonIsUnattended(t *testing.T) {
|
||||
for _, reason := range []string{"", "some_future_reason_nobody_has_written_yet"} {
|
||||
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceUnattended {
|
||||
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceUnattended (safe default)", reason, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestClassifyRunProvenance_PolarityDiffersFromIsPeriodicTasklessWake pins the
|
||||
// glossary's polarity warning: routine_dispatch is non-periodic for the
|
||||
// idle-skip gate but unattended for budget enforcement — the same literal,
|
||||
// opposite safe answer. A shared implementation would invert one of them.
|
||||
func TestClassifyRunProvenance_PolarityDiffersFromIsPeriodicTasklessWake(t *testing.T) {
|
||||
reason := shared.RunReasonRoutineDispatch
|
||||
if shared.IsPeriodicTasklessWake(reason) {
|
||||
t.Fatalf("test assumption violated: IsPeriodicTasklessWake(%q) should be false", reason)
|
||||
}
|
||||
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceUnattended {
|
||||
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceUnattended even though "+
|
||||
"IsPeriodicTasklessWake treats it as non-periodic", reason, got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunProvenance_Attended(t *testing.T) {
|
||||
if !shared.RunProvenanceAttended.Attended() {
|
||||
t.Error("RunProvenanceAttended.Attended() = false, want true")
|
||||
}
|
||||
if shared.RunProvenanceUnattended.Attended() {
|
||||
t.Error("RunProvenanceUnattended.Attended() = true, want false")
|
||||
}
|
||||
}
|
||||
@@ -17,7 +17,12 @@ describe("budget label maps", () => {
|
||||
"notify_only",
|
||||
"pause_agent",
|
||||
]);
|
||||
expect(Object.keys(BUDGET_PERIOD_LABEL_KEYS).sort()).toEqual(["monthly", "total"]);
|
||||
expect(Object.keys(BUDGET_PERIOD_LABEL_KEYS).sort()).toEqual([
|
||||
"daily",
|
||||
"monthly",
|
||||
"total",
|
||||
"yearly",
|
||||
]);
|
||||
});
|
||||
|
||||
it("resolves every mapped key to real copy", () => {
|
||||
|
||||
@@ -89,7 +89,9 @@ export const CONCURRENCY_POLICY_LABEL_KEYS: Record<string, string> = {
|
||||
* identifier.
|
||||
*/
|
||||
export const BUDGET_PERIOD_LABEL_KEYS: Record<string, string> = {
|
||||
daily: "office:budgetPeriodDaily",
|
||||
monthly: "office:budgetPeriodMonthly",
|
||||
yearly: "office:budgetPeriodYearly",
|
||||
total: "office:budgetPeriodTotal",
|
||||
};
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ import { listBudgets, deleteBudget } from "@/lib/api/domains/office-api";
|
||||
import type { BudgetPolicy } from "@/lib/state/slices/office/types";
|
||||
import { BudgetPolicyCard } from "./budget-policy-card";
|
||||
import { CreateBudgetForm } from "./create-budget-form";
|
||||
import { DefaultCeilingCard } from "./default-ceiling-card";
|
||||
import { useTranslation } from "react-i18next";
|
||||
// Module-level `t` for the error-only strings inside the fetching effect below:
|
||||
// putting the hook's `t` in that dep array would re-issue the request on every
|
||||
@@ -63,6 +64,8 @@ export function BudgetsTab({ workspaceId }: { workspaceId: string }) {
|
||||
</Button>
|
||||
</div>
|
||||
|
||||
<DefaultCeilingCard workspaceId={workspaceId} />
|
||||
|
||||
{showCreate && (
|
||||
<CreateBudgetForm
|
||||
workspaceId={workspaceId}
|
||||
|
||||
@@ -84,9 +84,15 @@ function FormFields({
|
||||
<SelectValue />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
<SelectItem value="daily" className="cursor-pointer">
|
||||
{t("office:daily")}
|
||||
</SelectItem>
|
||||
<SelectItem value="monthly" className="cursor-pointer">
|
||||
{t("office:monthly")}
|
||||
</SelectItem>
|
||||
<SelectItem value="yearly" className="cursor-pointer">
|
||||
{t("office:yearly")}
|
||||
</SelectItem>
|
||||
<SelectItem value="total" className="cursor-pointer">
|
||||
{t("office:total")}
|
||||
</SelectItem>
|
||||
@@ -146,7 +152,7 @@ export function CreateBudgetForm({ workspaceId, onCreated, onCancel }: Props) {
|
||||
// Budgets are stored as hundredths of a cent (subcents) to
|
||||
// match cost_subcents semantics — see apps/web/lib/utils.ts:formatDollars.
|
||||
limitSubcents: Math.round(parseFloat(state.limitDollars || "0") * 10000),
|
||||
period: state.period as "monthly" | "total",
|
||||
period: state.period as "daily" | "monthly" | "yearly" | "total",
|
||||
alertThresholdPct: parseInt(state.alertPct, 10) || 80,
|
||||
actionOnExceed: state.action as "notify_only" | "pause_agent" | "block_new_tasks",
|
||||
});
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
|
||||
|
||||
const getDefaultCeilingMock = vi.fn<(workspaceId: string) => Promise<{ limit_subcents: number }>>();
|
||||
const setDefaultCeilingMock =
|
||||
vi.fn<(workspaceId: string, limitSubcents: number) => Promise<{ limit_subcents: number }>>();
|
||||
|
||||
vi.mock("@/lib/api/domains/office-api", () => ({
|
||||
getDefaultCeiling: (workspaceId: string) => getDefaultCeilingMock(workspaceId),
|
||||
setDefaultCeiling: (workspaceId: string, limitSubcents: number) =>
|
||||
setDefaultCeilingMock(workspaceId, limitSubcents),
|
||||
}));
|
||||
|
||||
const toastError = vi.fn();
|
||||
const toastSuccess = vi.fn();
|
||||
vi.mock("@/lib/toast/sonner", () => ({
|
||||
toast: {
|
||||
success: (...args: unknown[]) => toastSuccess(...args),
|
||||
error: (...args: unknown[]) => toastError(...args),
|
||||
},
|
||||
}));
|
||||
|
||||
const EDIT_BUTTON_NAME = "Edit default ceiling";
|
||||
const SAVE_BUTTON_NAME = "Save";
|
||||
|
||||
import { DefaultCeilingCard } from "./default-ceiling-card";
|
||||
|
||||
afterEach(() => {
|
||||
cleanup();
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
// deferred returns a promise plus its resolver, so a test can control exactly
|
||||
// when a fetch "arrives" relative to a workspace switch.
|
||||
function deferred<T>() {
|
||||
let resolve!: (value: T) => void;
|
||||
const promise = new Promise<T>((res) => {
|
||||
resolve = res;
|
||||
});
|
||||
return { promise, resolve };
|
||||
}
|
||||
|
||||
describe("DefaultCeilingCard", () => {
|
||||
it("ignores a stale workspace's response that resolves after switching workspaces", async () => {
|
||||
const wsA = deferred<{ limit_subcents: number }>();
|
||||
const wsB = deferred<{ limit_subcents: number }>();
|
||||
getDefaultCeilingMock.mockImplementationOnce(() => wsA.promise);
|
||||
getDefaultCeilingMock.mockImplementationOnce(() => wsB.promise);
|
||||
|
||||
const { rerender } = render(<DefaultCeilingCard workspaceId="ws-a" />);
|
||||
await waitFor(() => expect(getDefaultCeilingMock).toHaveBeenCalledWith("ws-a"));
|
||||
|
||||
rerender(<DefaultCeilingCard workspaceId="ws-b" />);
|
||||
await waitFor(() => expect(getDefaultCeilingMock).toHaveBeenCalledWith("ws-b"));
|
||||
|
||||
// ws-b's response arrives first, then ws-a's stale response arrives late.
|
||||
await act(async () => {
|
||||
wsB.resolve({ limit_subcents: 200000 });
|
||||
await wsB.promise;
|
||||
});
|
||||
await screen.findByText("$20.00");
|
||||
|
||||
await act(async () => {
|
||||
wsA.resolve({ limit_subcents: 500000 });
|
||||
await wsA.promise;
|
||||
});
|
||||
|
||||
expect(screen.getByText("$20.00")).toBeTruthy();
|
||||
expect(screen.queryByText("$50.00")).toBeNull();
|
||||
});
|
||||
|
||||
it("resets in-progress edits when the workspace changes", async () => {
|
||||
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
|
||||
|
||||
const { rerender } = render(<DefaultCeilingCard workspaceId="ws-a" />);
|
||||
await screen.findByText("$10.00");
|
||||
|
||||
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
|
||||
expect(screen.getByRole("spinbutton")).toBeTruthy();
|
||||
|
||||
rerender(<DefaultCeilingCard workspaceId="ws-b" />);
|
||||
|
||||
expect(screen.queryByRole("spinbutton")).toBeNull();
|
||||
});
|
||||
|
||||
it("does not keep the replacement workspace busy after a stale save settles", async () => {
|
||||
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
|
||||
const pendingSave = deferred<{ limit_subcents: number }>();
|
||||
setDefaultCeilingMock.mockImplementationOnce(() => pendingSave.promise);
|
||||
|
||||
const { rerender } = render(<DefaultCeilingCard workspaceId="ws-a" />);
|
||||
await screen.findByText("$10.00");
|
||||
|
||||
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
|
||||
fireEvent.change(screen.getByRole("spinbutton"), { target: { value: "20" } });
|
||||
fireEvent.click(screen.getByRole("button", { name: SAVE_BUTTON_NAME }));
|
||||
expect(
|
||||
(screen.getByRole("button", { name: SAVE_BUTTON_NAME }) as HTMLButtonElement).disabled,
|
||||
).toBe(true);
|
||||
|
||||
rerender(<DefaultCeilingCard workspaceId="ws-b" />);
|
||||
await screen.findByText("$10.00");
|
||||
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
|
||||
|
||||
expect(
|
||||
(screen.getByRole("button", { name: SAVE_BUTTON_NAME }) as HTMLButtonElement).disabled,
|
||||
).toBe(false);
|
||||
expect((screen.getByRole("button", { name: "Cancel" }) as HTMLButtonElement).disabled).toBe(
|
||||
false,
|
||||
);
|
||||
|
||||
await act(async () => {
|
||||
pendingSave.resolve({ limit_subcents: 200000 });
|
||||
await pendingSave.promise;
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects a non-positive draft ceiling without calling the API", async () => {
|
||||
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
|
||||
render(<DefaultCeilingCard workspaceId="ws-a" />);
|
||||
await screen.findByText("$10.00");
|
||||
|
||||
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
|
||||
const input = screen.getByRole("spinbutton");
|
||||
fireEvent.change(input, { target: { value: "0" } });
|
||||
await act(async () => {
|
||||
fireEvent.click(screen.getByRole("button", { name: SAVE_BUTTON_NAME }));
|
||||
});
|
||||
|
||||
expect(setDefaultCeilingMock).not.toHaveBeenCalled();
|
||||
expect(toastError).toHaveBeenCalledWith("Default ceiling must be greater than zero");
|
||||
});
|
||||
|
||||
it("rejects a non-finite or sub-cent draft ceiling without calling the API", async () => {
|
||||
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
|
||||
render(<DefaultCeilingCard workspaceId="ws-a" />);
|
||||
await screen.findByText("$10.00");
|
||||
|
||||
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
|
||||
const input = screen.getByRole("spinbutton", { name: "Default Ceiling" });
|
||||
fireEvent.change(input, { target: { value: "0.001" } });
|
||||
await act(async () => {
|
||||
fireEvent.click(screen.getByRole("button", { name: SAVE_BUTTON_NAME }));
|
||||
});
|
||||
|
||||
expect(setDefaultCeilingMock).not.toHaveBeenCalled();
|
||||
expect(toastError).toHaveBeenCalledWith("Default ceiling must be greater than zero");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,160 @@
|
||||
"use client";
|
||||
|
||||
import { useEffect, useRef, useState } from "react";
|
||||
import { Button } from "@kandev/ui/button";
|
||||
import { Input } from "@kandev/ui/input";
|
||||
import { Card, CardContent, CardHeader, CardTitle } from "@kandev/ui/card";
|
||||
import { IconPencil } from "@tabler/icons-react";
|
||||
import { toast } from "@/lib/toast/sonner";
|
||||
import { getDefaultCeiling, setDefaultCeiling } from "@/lib/api/domains/office-api";
|
||||
import { formatDollars } from "@/lib/utils";
|
||||
import { useTranslation } from "react-i18next";
|
||||
|
||||
type Props = {
|
||||
workspaceId: string;
|
||||
};
|
||||
|
||||
type EditorProps = {
|
||||
draftDollars: string;
|
||||
saving: boolean;
|
||||
onDraftChange: (value: string) => void;
|
||||
onSave: () => void;
|
||||
onCancel: () => void;
|
||||
};
|
||||
|
||||
function DefaultCeilingEditor({
|
||||
draftDollars,
|
||||
saving,
|
||||
onDraftChange,
|
||||
onSave,
|
||||
onCancel,
|
||||
}: EditorProps) {
|
||||
const { t } = useTranslation();
|
||||
return (
|
||||
<div className="flex flex-col gap-2 sm:flex-row sm:items-center">
|
||||
<Input
|
||||
className="h-8 w-full text-sm [@media(pointer:coarse)]:min-h-11 sm:w-32"
|
||||
type="number"
|
||||
min="0.01"
|
||||
step="0.01"
|
||||
value={draftDollars}
|
||||
onChange={(e) => onDraftChange(e.target.value)}
|
||||
aria-label={t("office:defaultCeiling")}
|
||||
autoFocus
|
||||
/>
|
||||
<Button
|
||||
size="sm"
|
||||
className="w-full cursor-pointer [@media(pointer:coarse)]:min-h-11 sm:w-auto"
|
||||
disabled={saving}
|
||||
onClick={onSave}
|
||||
>
|
||||
{t("office:saveDefaultCeiling")}
|
||||
</Button>
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="sm"
|
||||
className="w-full cursor-pointer [@media(pointer:coarse)]:min-h-11 sm:w-auto"
|
||||
disabled={saving}
|
||||
onClick={onCancel}
|
||||
>
|
||||
{t("common:cancel")}
|
||||
</Button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// DefaultCeilingCard makes the built-in default spend ceiling
|
||||
// (AC-OFFICE-BUDGET-003.5) visible and editable without inspecting the
|
||||
// database. It is visually and structurally distinct from a
|
||||
// BudgetPolicyCard: no scope/action/period controls, since the default is
|
||||
// always workspace-scoped, always daily, and always blocking
|
||||
// (AC-OFFICE-BUDGET-003.2/.3) — only its limit is operator-tunable.
|
||||
export function DefaultCeilingCard({ workspaceId }: Props) {
|
||||
const { t } = useTranslation();
|
||||
const [limitSubcents, setLimitSubcents] = useState<number | null>(null);
|
||||
const [editing, setEditing] = useState(false);
|
||||
const [draftDollars, setDraftDollars] = useState("");
|
||||
const [saving, setSaving] = useState(false);
|
||||
const activeWorkspaceId = useRef(workspaceId);
|
||||
|
||||
useEffect(() => {
|
||||
activeWorkspaceId.current = workspaceId;
|
||||
setLimitSubcents(null);
|
||||
setEditing(false);
|
||||
setDraftDollars("");
|
||||
setSaving(false);
|
||||
getDefaultCeiling(workspaceId)
|
||||
.then((res) => {
|
||||
if (activeWorkspaceId.current !== workspaceId) return;
|
||||
setLimitSubcents(res.limit_subcents);
|
||||
})
|
||||
.catch((err) => {
|
||||
if (activeWorkspaceId.current !== workspaceId) return;
|
||||
toast.error(err instanceof Error ? err.message : t("office:failedToLoadDefaultCeiling"));
|
||||
});
|
||||
// eslint-disable-next-line react-hooks/exhaustive-deps -- toast/t are stable; re-fetch only on workspace change
|
||||
}, [workspaceId]);
|
||||
|
||||
const startEditing = () => {
|
||||
setDraftDollars(limitSubcents == null ? "" : (limitSubcents / 10000).toFixed(2));
|
||||
setEditing(true);
|
||||
};
|
||||
|
||||
const handleSave = async () => {
|
||||
const draftValue = Number(draftDollars);
|
||||
if (!Number.isFinite(draftValue) || draftValue < 0.01) {
|
||||
toast.error(t("office:defaultCeilingMustBePositive"));
|
||||
return;
|
||||
}
|
||||
const nextSubcents = Math.round(draftValue * 10000);
|
||||
const targetWorkspaceId = workspaceId;
|
||||
setSaving(true);
|
||||
try {
|
||||
const res = await setDefaultCeiling(targetWorkspaceId, nextSubcents);
|
||||
if (activeWorkspaceId.current !== targetWorkspaceId) return;
|
||||
setLimitSubcents(res.limit_subcents);
|
||||
setEditing(false);
|
||||
toast.success(t("office:defaultCeilingUpdated"));
|
||||
} catch (err) {
|
||||
if (activeWorkspaceId.current !== targetWorkspaceId) return;
|
||||
toast.error(err instanceof Error ? err.message : t("office:failedToUpdateDefaultCeiling"));
|
||||
} finally {
|
||||
if (activeWorkspaceId.current === targetWorkspaceId) setSaving(false);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<Card>
|
||||
<CardHeader className="flex flex-row items-center justify-between pb-2">
|
||||
<CardTitle className="text-sm">{t("office:defaultCeiling")}</CardTitle>
|
||||
{!editing && (
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="icon-sm"
|
||||
className="cursor-pointer [@media(pointer:coarse)]:h-11 [@media(pointer:coarse)]:w-11"
|
||||
onClick={startEditing}
|
||||
aria-label={t("office:editDefaultCeiling")}
|
||||
>
|
||||
<IconPencil className="h-4 w-4" />
|
||||
</Button>
|
||||
)}
|
||||
</CardHeader>
|
||||
<CardContent className="space-y-2">
|
||||
<p className="text-xs text-muted-foreground">{t("office:defaultCeilingDescription")}</p>
|
||||
{editing ? (
|
||||
<DefaultCeilingEditor
|
||||
draftDollars={draftDollars}
|
||||
saving={saving}
|
||||
onDraftChange={setDraftDollars}
|
||||
onSave={handleSave}
|
||||
onCancel={() => setEditing(false)}
|
||||
/>
|
||||
) : (
|
||||
<div className="text-lg font-semibold">
|
||||
{limitSubcents == null ? t("common:loading") : formatDollars(limitSubcents)}
|
||||
</div>
|
||||
)}
|
||||
</CardContent>
|
||||
</Card>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
import { test, expect } from "../../fixtures/office-fixture";
|
||||
import { officeTopbarTitle } from "../../helpers/office-topbar";
|
||||
import { waitForHttp } from "../../helpers/causal-waits";
|
||||
|
||||
// Covers the frontend surface added by REQ-OFFICE-BUDGET-002.9/.12 (daily/
|
||||
// yearly period options) and REQ-OFFICE-BUDGET-003.5 (built-in default
|
||||
// ceiling, readable/writable without inspecting the database).
|
||||
test.describe("Office budget enforcement UI", () => {
|
||||
test.beforeEach(async ({ testPage }) => {
|
||||
await testPage.goto("/office/workspace/costs");
|
||||
await expect(officeTopbarTitle(testPage)).toHaveText(/Costs/i, { timeout: 10_000 });
|
||||
await testPage.getByRole("tab", { name: "Budgets" }).click();
|
||||
});
|
||||
|
||||
test("default ceiling card shows the built-in default and can be edited", async ({
|
||||
testPage,
|
||||
}) => {
|
||||
const initialLoad = waitForHttp(testPage, "GET", /\/budgets\/default$/);
|
||||
await testPage.reload();
|
||||
await testPage.getByRole("tab", { name: "Budgets" }).click();
|
||||
await initialLoad;
|
||||
|
||||
// Shipped default is 500,000 subcents == $50.00 (AC-OFFICE-BUDGET-003.9)
|
||||
// until a workspace overrides it.
|
||||
const card = testPage.getByText("Default Ceiling").locator("..").locator("..");
|
||||
await expect(card.getByText("$50.00")).toBeVisible();
|
||||
|
||||
await card.getByRole("button", { name: "Edit default ceiling" }).click();
|
||||
const input = card.getByRole("spinbutton");
|
||||
await input.fill("75.50");
|
||||
|
||||
const saved = waitForHttp(testPage, "PUT", /\/budgets\/default$/, {
|
||||
predicate: (r) => r.status() === 200,
|
||||
});
|
||||
await card.getByRole("button", { name: "Save" }).click();
|
||||
await saved;
|
||||
|
||||
await expect(card.getByText("$75.50")).toBeVisible();
|
||||
|
||||
// Reload to prove the write actually persisted server-side, not just in
|
||||
// local component state.
|
||||
const reloadFetch = waitForHttp(testPage, "GET", /\/budgets\/default$/);
|
||||
await testPage.reload();
|
||||
await testPage.getByRole("tab", { name: "Budgets" }).click();
|
||||
await reloadFetch;
|
||||
await expect(
|
||||
testPage.getByText("Default Ceiling").locator("..").locator("..").getByText("$75.50"),
|
||||
).toBeVisible();
|
||||
});
|
||||
|
||||
test("create-budget period select offers exactly daily, monthly, yearly, total", async ({
|
||||
testPage,
|
||||
}) => {
|
||||
await testPage.getByRole("button", { name: "Add Policy" }).click();
|
||||
|
||||
// Period is the 4th FormField (Scope Type, Scope ID, Limit, Period, ...);
|
||||
// scope it via the visible "Period" label rather than a bare role query,
|
||||
// since the form has several comboboxes.
|
||||
const periodField = testPage
|
||||
.locator("div", { has: testPage.getByText("Period", { exact: true }) })
|
||||
.last();
|
||||
await periodField.getByRole("combobox").click();
|
||||
|
||||
const listbox = testPage.getByRole("listbox");
|
||||
await expect(listbox.getByRole("option", { name: "Daily" })).toBeVisible();
|
||||
await expect(listbox.getByRole("option", { name: "Monthly" })).toBeVisible();
|
||||
await expect(listbox.getByRole("option", { name: "Yearly" })).toBeVisible();
|
||||
await expect(listbox.getByRole("option", { name: "Total" })).toBeVisible();
|
||||
// Exactly these four - no fifth/unexpected option leaking through.
|
||||
await expect(listbox.getByRole("option")).toHaveCount(4);
|
||||
});
|
||||
|
||||
test("selecting a daily period in create-budget wires through to the POST body", async ({
|
||||
testPage,
|
||||
officeSeed,
|
||||
}) => {
|
||||
await testPage.getByRole("button", { name: "Add Policy" }).click();
|
||||
|
||||
const scopeIdField = testPage
|
||||
.locator("div", { has: testPage.getByText("Scope ID", { exact: true }) })
|
||||
.last();
|
||||
await scopeIdField.getByPlaceholder("Entity ID").fill(officeSeed.workspaceId);
|
||||
|
||||
const limitField = testPage
|
||||
.locator("div", { has: testPage.getByText("Limit ($)", { exact: true }) })
|
||||
.last();
|
||||
await limitField.getByRole("spinbutton").fill("12.34");
|
||||
|
||||
const periodField = testPage
|
||||
.locator("div", { has: testPage.getByText("Period", { exact: true }) })
|
||||
.last();
|
||||
await periodField.getByRole("combobox").click();
|
||||
await testPage.getByRole("option", { name: "Daily" }).click();
|
||||
|
||||
const posted = waitForHttp(testPage, "POST", /\/budgets$/);
|
||||
await testPage.getByRole("button", { name: "Create Policy" }).click();
|
||||
const response = await posted;
|
||||
|
||||
expect(response.status()).toBe(201);
|
||||
const requestBody = JSON.parse(response.request().postData() ?? "{}") as Record<
|
||||
string,
|
||||
unknown
|
||||
>;
|
||||
expect(requestBody).toMatchObject({
|
||||
scope_type: "workspace",
|
||||
scope_id: officeSeed.workspaceId,
|
||||
limit_subcents: 123400,
|
||||
period: "daily",
|
||||
alert_threshold_pct: 80,
|
||||
action_on_exceed: "notify_only",
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,45 @@
|
||||
import { test, expect } from "../../fixtures/office-fixture";
|
||||
import { officeTopbarTitle } from "../../helpers/office-topbar";
|
||||
import { waitForHttp } from "../../helpers/causal-waits";
|
||||
|
||||
test.describe("Office budget enforcement on mobile", () => {
|
||||
test("edits the default ceiling with reachable controls", async ({ testPage }) => {
|
||||
await testPage.goto("/office/workspace/costs");
|
||||
await expect(officeTopbarTitle(testPage)).toHaveText(/Costs/i, { timeout: 10_000 });
|
||||
const defaultLoad = waitForHttp(testPage, "GET", /\/budgets\/default$/);
|
||||
await testPage.getByRole("tab", { name: "Budgets" }).tap();
|
||||
await defaultLoad;
|
||||
|
||||
const card = testPage.getByText("Default Ceiling").locator("..").locator("..");
|
||||
await expect(card.getByText(/\$\d+\.\d{2}/)).toBeVisible();
|
||||
|
||||
const edit = card.getByRole("button", { name: "Edit default ceiling" });
|
||||
const editBox = await edit.boundingBox();
|
||||
expect(editBox?.width).toBeGreaterThanOrEqual(44);
|
||||
expect(editBox?.height).toBeGreaterThanOrEqual(44);
|
||||
await edit.tap();
|
||||
|
||||
const input = card.getByRole("spinbutton");
|
||||
await expect(input).toHaveAccessibleName("Default Ceiling");
|
||||
await input.fill("75.50");
|
||||
|
||||
const save = card.getByRole("button", { name: "Save" });
|
||||
const cancel = card.getByRole("button", { name: "Cancel" });
|
||||
for (const button of [save, cancel]) {
|
||||
const box = await button.boundingBox();
|
||||
expect(box?.width).toBeGreaterThanOrEqual(44);
|
||||
expect(box?.height).toBeGreaterThanOrEqual(44);
|
||||
}
|
||||
|
||||
const saved = waitForHttp(testPage, "PUT", /\/budgets\/default$/, {
|
||||
predicate: (response) => response.status() === 200,
|
||||
});
|
||||
await save.tap();
|
||||
await saved;
|
||||
await expect(card.getByText("$75.50")).toBeVisible();
|
||||
|
||||
expect(await testPage.evaluate(() => document.documentElement.scrollWidth)).toBeLessThanOrEqual(
|
||||
await testPage.evaluate(() => document.documentElement.clientWidth),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -4,7 +4,6 @@ import type {
|
||||
AgentProfile,
|
||||
Project,
|
||||
CostSummary,
|
||||
BudgetPolicy,
|
||||
Routine,
|
||||
RoutineTrigger,
|
||||
RoutineRun,
|
||||
@@ -64,6 +63,7 @@ export {
|
||||
gitPull,
|
||||
gitPush,
|
||||
} from "./office-extended-api";
|
||||
export { listBudgets, createBudget, updateBudget, deleteBudget } from "./office-budget-api";
|
||||
export type {
|
||||
ImportDiff,
|
||||
ImportPreview,
|
||||
@@ -423,37 +423,32 @@ type CostBreakdownItemRaw = {
|
||||
total_subcents: number;
|
||||
};
|
||||
|
||||
// --- Budget Policies ---
|
||||
// --- Built-in default spend ceiling (AC-OFFICE-BUDGET-003.5) ---
|
||||
|
||||
export function listBudgets(workspaceId: string, options?: ApiRequestOptions) {
|
||||
return fetchJson<{ budgets: BudgetPolicy[] }>(
|
||||
`${BASE}/workspaces/${workspaceId}/budgets`,
|
||||
options,
|
||||
);
|
||||
// DefaultCeilingRaw is the wire shape of GET/PUT .../budgets/default
|
||||
// (internal/office/costs/dto.go's DefaultCeilingResponse /
|
||||
// SetDefaultCeilingRequest, both `{"limit_subcents": ...}`). Named "Raw"
|
||||
// and read as snake_case directly by the caller, matching this file's
|
||||
// existing CostBreakdownItemRaw convention, rather than assuming a
|
||||
// camelCase field the backend does not send.
|
||||
type DefaultCeilingRaw = { limit_subcents: number };
|
||||
|
||||
export function getDefaultCeiling(workspaceId: string, options?: ApiRequestOptions) {
|
||||
return fetchJson<DefaultCeilingRaw>(`${BASE}/workspaces/${workspaceId}/budgets/default`, options);
|
||||
}
|
||||
|
||||
export function createBudget(
|
||||
export function setDefaultCeiling(
|
||||
workspaceId: string,
|
||||
data: Partial<BudgetPolicy>,
|
||||
limitSubcents: number,
|
||||
options?: ApiRequestOptions,
|
||||
) {
|
||||
return fetchJson<BudgetPolicy>(`${BASE}/workspaces/${workspaceId}/budgets`, {
|
||||
return fetchJson<DefaultCeilingRaw>(`${BASE}/workspaces/${workspaceId}/budgets/default`, {
|
||||
...options,
|
||||
init: { method: "POST", body: JSON.stringify(data), ...options?.init },
|
||||
});
|
||||
}
|
||||
|
||||
export function updateBudget(id: string, data: Partial<BudgetPolicy>, options?: ApiRequestOptions) {
|
||||
return fetchJson<BudgetPolicy>(`${BASE}/budgets/${id}`, {
|
||||
...options,
|
||||
init: { method: "PATCH", body: JSON.stringify(data), ...options?.init },
|
||||
});
|
||||
}
|
||||
|
||||
export function deleteBudget(id: string, options?: ApiRequestOptions) {
|
||||
return fetchJson<void>(`${BASE}/budgets/${id}`, {
|
||||
...options,
|
||||
init: { method: "DELETE", ...options?.init },
|
||||
init: {
|
||||
method: "PUT",
|
||||
body: JSON.stringify({ limit_subcents: limitSubcents }),
|
||||
...options?.init,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
vi.mock("@/lib/config", () => ({
|
||||
getBackendConfig: () => ({ apiBaseUrl: "http://api.test" }),
|
||||
}));
|
||||
|
||||
import { createBudget, listBudgets, updateBudget } from "./office-api";
|
||||
|
||||
type FetchInput = Parameters<typeof fetch>[0];
|
||||
type FetchInit = Parameters<typeof fetch>[1];
|
||||
const fetchSpy = vi.fn<(...args: [FetchInput, FetchInit?]) => Promise<Response>>();
|
||||
const WORKSPACE_ID = "workspace-1";
|
||||
|
||||
beforeEach(() => {
|
||||
fetchSpy.mockReset();
|
||||
vi.stubGlobal("fetch", fetchSpy);
|
||||
});
|
||||
|
||||
afterEach(() => vi.unstubAllGlobals());
|
||||
|
||||
function jsonResponse(body: unknown, status = 200): Response {
|
||||
return new Response(JSON.stringify(body), {
|
||||
status,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
}
|
||||
|
||||
function lastCall(): { url: string; init: FetchInit | undefined } {
|
||||
const call = fetchSpy.mock.calls.at(-1);
|
||||
if (!call) throw new Error("expected fetch to have been called");
|
||||
return { url: String(call[0]), init: call[1] };
|
||||
}
|
||||
|
||||
const camelBudget = {
|
||||
scopeType: "workspace" as const,
|
||||
scopeId: WORKSPACE_ID,
|
||||
limitSubcents: 123400,
|
||||
period: "daily" as const,
|
||||
alertThresholdPct: 80,
|
||||
actionOnExceed: "block_new_tasks" as const,
|
||||
};
|
||||
|
||||
const snakeBudget = {
|
||||
id: "budget-1",
|
||||
workspace_id: WORKSPACE_ID,
|
||||
scope_type: "workspace",
|
||||
scope_id: WORKSPACE_ID,
|
||||
limit_subcents: 123400,
|
||||
period: "daily",
|
||||
alert_threshold_pct: 80,
|
||||
action_on_exceed: "block_new_tasks",
|
||||
created_at: "2026-01-01T00:00:00Z",
|
||||
updated_at: "2026-01-01T00:00:00Z",
|
||||
};
|
||||
|
||||
describe("budget policy api", () => {
|
||||
it("maps camelCase fields to the backend snake_case create body", async () => {
|
||||
fetchSpy.mockResolvedValueOnce(jsonResponse({ budget: snakeBudget }, 201));
|
||||
|
||||
const result = await createBudget(WORKSPACE_ID, camelBudget);
|
||||
|
||||
expect(lastCall().init?.method).toBe("POST");
|
||||
expect(JSON.parse(String(lastCall().init?.body))).toEqual({
|
||||
scope_type: "workspace",
|
||||
scope_id: WORKSPACE_ID,
|
||||
limit_subcents: 123400,
|
||||
period: "daily",
|
||||
alert_threshold_pct: 80,
|
||||
action_on_exceed: "block_new_tasks",
|
||||
});
|
||||
expect(result.scopeType).toBe("workspace");
|
||||
expect(result.limitSubcents).toBe(123400);
|
||||
});
|
||||
|
||||
it("maps a partial camelCase patch to snake_case", async () => {
|
||||
fetchSpy.mockResolvedValueOnce(jsonResponse({ budget: snakeBudget }));
|
||||
|
||||
await updateBudget("budget-1", { limitSubcents: 200000, actionOnExceed: "notify_only" });
|
||||
|
||||
expect(lastCall().init?.method).toBe("PATCH");
|
||||
expect(JSON.parse(String(lastCall().init?.body))).toEqual({
|
||||
limit_subcents: 200000,
|
||||
action_on_exceed: "notify_only",
|
||||
});
|
||||
});
|
||||
|
||||
it("normalizes snake_case list responses for the web model", async () => {
|
||||
fetchSpy.mockResolvedValueOnce(jsonResponse({ budgets: [snakeBudget] }));
|
||||
|
||||
const result = await listBudgets(WORKSPACE_ID);
|
||||
|
||||
expect(result.budgets).toEqual([
|
||||
expect.objectContaining({
|
||||
id: "budget-1",
|
||||
workspaceId: WORKSPACE_ID,
|
||||
scopeType: "workspace",
|
||||
scopeId: WORKSPACE_ID,
|
||||
limitSubcents: 123400,
|
||||
alertThresholdPct: 80,
|
||||
actionOnExceed: "block_new_tasks",
|
||||
}),
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,75 @@
|
||||
import { fetchJson, type ApiRequestOptions } from "../client";
|
||||
import type { BudgetPolicy } from "@/lib/state/slices/office/types";
|
||||
|
||||
const BASE = "/api/v1/office";
|
||||
|
||||
type RawBudgetPolicy = Record<string, unknown>;
|
||||
|
||||
function budgetField(raw: RawBudgetPolicy, camelKey: string, snakeKey: string): unknown {
|
||||
return raw[camelKey] ?? raw[snakeKey];
|
||||
}
|
||||
|
||||
function normalizeBudget(raw: unknown): BudgetPolicy {
|
||||
const budget = raw as RawBudgetPolicy;
|
||||
return {
|
||||
id: String(budgetField(budget, "id", "id") ?? ""),
|
||||
workspaceId: String(budgetField(budget, "workspaceId", "workspace_id") ?? ""),
|
||||
scopeType: budgetField(budget, "scopeType", "scope_type") as BudgetPolicy["scopeType"],
|
||||
scopeId: String(budgetField(budget, "scopeId", "scope_id") ?? ""),
|
||||
limitSubcents: Number(budgetField(budget, "limitSubcents", "limit_subcents") ?? 0),
|
||||
period: budgetField(budget, "period", "period") as BudgetPolicy["period"],
|
||||
alertThresholdPct: Number(budgetField(budget, "alertThresholdPct", "alert_threshold_pct") ?? 0),
|
||||
actionOnExceed: budgetField(
|
||||
budget,
|
||||
"actionOnExceed",
|
||||
"action_on_exceed",
|
||||
) as BudgetPolicy["actionOnExceed"],
|
||||
createdAt: String(budgetField(budget, "createdAt", "created_at") ?? ""),
|
||||
updatedAt: String(budgetField(budget, "updatedAt", "updated_at") ?? ""),
|
||||
};
|
||||
}
|
||||
|
||||
function budgetPayload(data: Partial<BudgetPolicy>): Record<string, unknown> {
|
||||
return {
|
||||
scope_type: data.scopeType,
|
||||
scope_id: data.scopeId,
|
||||
limit_subcents: data.limitSubcents,
|
||||
period: data.period,
|
||||
alert_threshold_pct: data.alertThresholdPct,
|
||||
action_on_exceed: data.actionOnExceed,
|
||||
};
|
||||
}
|
||||
|
||||
type BudgetResponse = { budget: unknown };
|
||||
|
||||
export function listBudgets(workspaceId: string, options?: ApiRequestOptions) {
|
||||
return fetchJson<{ budgets: unknown[] }>(
|
||||
`${BASE}/workspaces/${workspaceId}/budgets`,
|
||||
options,
|
||||
).then((res) => ({ budgets: (res.budgets ?? []).map((budget) => normalizeBudget(budget)) }));
|
||||
}
|
||||
|
||||
export function createBudget(
|
||||
workspaceId: string,
|
||||
data: Partial<BudgetPolicy>,
|
||||
options?: ApiRequestOptions,
|
||||
) {
|
||||
return fetchJson<BudgetResponse>(`${BASE}/workspaces/${workspaceId}/budgets`, {
|
||||
...options,
|
||||
init: { method: "POST", body: JSON.stringify(budgetPayload(data)), ...options?.init },
|
||||
}).then((res) => normalizeBudget(res.budget));
|
||||
}
|
||||
|
||||
export function updateBudget(id: string, data: Partial<BudgetPolicy>, options?: ApiRequestOptions) {
|
||||
return fetchJson<BudgetResponse>(`${BASE}/budgets/${id}`, {
|
||||
...options,
|
||||
init: { method: "PATCH", body: JSON.stringify(budgetPayload(data)), ...options?.init },
|
||||
}).then((res) => normalizeBudget(res.budget));
|
||||
}
|
||||
|
||||
export function deleteBudget(id: string, options?: ApiRequestOptions) {
|
||||
return fetchJson<void>(`${BASE}/budgets/${id}`, {
|
||||
...options,
|
||||
init: { method: "DELETE", ...options?.init },
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
vi.mock("@/lib/config", () => ({
|
||||
getBackendConfig: () => ({ apiBaseUrl: "http://api.test" }),
|
||||
}));
|
||||
|
||||
import { getDefaultCeiling, setDefaultCeiling } from "./office-api";
|
||||
|
||||
type FetchInput = Parameters<typeof fetch>[0];
|
||||
type FetchInit = Parameters<typeof fetch>[1];
|
||||
const fetchSpy = vi.fn<(...args: [FetchInput, FetchInit?]) => Promise<Response>>();
|
||||
const WORKSPACE_ID = "workspace-1";
|
||||
const URL = `http://api.test/api/v1/office/workspaces/${WORKSPACE_ID}/budgets/default`;
|
||||
|
||||
beforeEach(() => {
|
||||
fetchSpy.mockReset();
|
||||
vi.stubGlobal("fetch", fetchSpy);
|
||||
});
|
||||
|
||||
afterEach(() => vi.unstubAllGlobals());
|
||||
|
||||
function jsonResponse(body: unknown): Response {
|
||||
return new Response(JSON.stringify(body), {
|
||||
status: 200,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
}
|
||||
|
||||
function lastCall(): { url: string; init: FetchInit | undefined } {
|
||||
const call = fetchSpy.mock.calls.at(-1);
|
||||
if (!call) throw new Error("expected fetch to have been called");
|
||||
return { url: String(call[0]), init: call[1] };
|
||||
}
|
||||
|
||||
describe("built-in default ceiling api", () => {
|
||||
it("reads the effective limit from the snake_case wire response", async () => {
|
||||
fetchSpy.mockResolvedValueOnce(jsonResponse({ limit_subcents: 500_000 }));
|
||||
|
||||
const res = await getDefaultCeiling(WORKSPACE_ID);
|
||||
|
||||
expect(lastCall().url).toBe(URL);
|
||||
expect(res.limit_subcents).toBe(500_000);
|
||||
});
|
||||
|
||||
it("PUTs a snake_case body and returns the updated limit", async () => {
|
||||
fetchSpy.mockResolvedValueOnce(jsonResponse({ limit_subcents: 1_000_000 }));
|
||||
|
||||
const res = await setDefaultCeiling(WORKSPACE_ID, 1_000_000);
|
||||
|
||||
expect(lastCall().url).toBe(URL);
|
||||
expect(lastCall().init?.method).toBe("PUT");
|
||||
expect(JSON.parse(String(lastCall().init?.body))).toEqual({ limit_subcents: 1_000_000 });
|
||||
expect(res.limit_subcents).toBe(1_000_000);
|
||||
});
|
||||
});
|
||||
@@ -141,7 +141,7 @@ export type BudgetPolicy = {
|
||||
scopeType: "agent" | "project" | "workspace";
|
||||
scopeId: string;
|
||||
limitSubcents: number;
|
||||
period: "monthly" | "total";
|
||||
period: "daily" | "monthly" | "yearly" | "total";
|
||||
alertThresholdPct: number;
|
||||
actionOnExceed: "notify_only" | "pause_agent" | "block_new_tasks";
|
||||
createdAt: string;
|
||||
|
||||
@@ -112,8 +112,10 @@
|
||||
"budgetAmount": "Budget: {{amount}}",
|
||||
"budgetCapConcurrencyAndExecutionEnvironment": "Budget cap, concurrency, and execution environment.",
|
||||
"budgetLimitsConcurrencyAndExecutionEnvironment": "Budget limits, concurrency, and execution environment.",
|
||||
"budgetPeriodDaily": "daily",
|
||||
"budgetPeriodMonthly": "monthly",
|
||||
"budgetPeriodTotal": "total",
|
||||
"budgetPeriodYearly": "yearly",
|
||||
"budgetPolicies": "Budget Policies",
|
||||
"budgetPolicyCreated": "Budget policy created",
|
||||
"budgetPolicyDeleted": "Budget policy deleted",
|
||||
@@ -256,11 +258,16 @@
|
||||
"currentlyMapsTo": "Currently maps to",
|
||||
"currentRouteTooltip": "Reflects the next-launch choice. In-flight session details are on each run.",
|
||||
"currentUtilizationOfSubscriptionRateLimit": "Current utilization of subscription rate-limit windows.",
|
||||
"daily": "Daily",
|
||||
"dailyDepUpdate": "Daily Dep Update",
|
||||
"dailySuccessRate": "Daily success rate",
|
||||
"dangerZone": "Danger Zone",
|
||||
"dashboard": "Dashboard",
|
||||
"date": "Date",
|
||||
"defaultCeiling": "Default Ceiling",
|
||||
"defaultCeilingDescription": "Blocks new unattended runs once this workspace's spend for the current UTC day reaches the limit below. Never blocks an attended run. A workspace-level daily policy that pauses agents or blocks new tasks replaces this ceiling; a notify-only policy does not, and both apply together.",
|
||||
"defaultCeilingMustBePositive": "Default ceiling must be greater than zero",
|
||||
"defaultCeilingUpdated": "Default ceiling updated",
|
||||
"defaultFor": "DEFAULT FOR",
|
||||
"defaultForRole": "default for {{role}}",
|
||||
"defaultTier": "Default tier",
|
||||
@@ -286,6 +293,7 @@
|
||||
"dockerImageWithExample": "Docker image (e.g. node:20-slim)",
|
||||
"duration": "Duration",
|
||||
"editable": "Editable",
|
||||
"editDefaultCeiling": "Edit default ceiling",
|
||||
"editRoutine": "Edit routine",
|
||||
"effectiveActionsThisAgentCanRequest": "Effective actions this agent can request during Office runs.",
|
||||
"eGCodeReview": "e.g. code-review",
|
||||
@@ -337,6 +345,7 @@
|
||||
"failedToLoadBudgets": "Failed to load budgets",
|
||||
"failedToLoadChannels": "Failed to load channels",
|
||||
"failedToLoadCostData": "Failed to load cost data",
|
||||
"failedToLoadDefaultCeiling": "Failed to load default ceiling",
|
||||
"failedToLoadDeletionSummary": "Failed to load deletion summary",
|
||||
"failedToLoadDiffs": "Failed to load diffs",
|
||||
"failedToLoadExportBundle": "Failed to load export bundle",
|
||||
@@ -358,6 +367,7 @@
|
||||
"failedToSaveRoutine": "Failed to save routine",
|
||||
"failedToSaveSettings": "Failed to save settings",
|
||||
"failedToUpdateAgent": "Failed to update agent",
|
||||
"failedToUpdateDefaultCeiling": "Failed to update default ceiling",
|
||||
"failedToUpdateRoutine": "Failed to update routine",
|
||||
"failedToUpdateSkills": "Failed to update skills",
|
||||
"fallback": "Fallback",
|
||||
@@ -738,6 +748,7 @@
|
||||
"saveChanges": "Save Changes",
|
||||
"saveConfiguration": "Save Configuration",
|
||||
"saved": "Saved {{filename}}",
|
||||
"saveDefaultCeiling": "Save",
|
||||
"saveOverrides": "Save overrides",
|
||||
"savePermissions": "Save Permissions",
|
||||
"saveSkills": "Save skills",
|
||||
@@ -957,6 +968,7 @@
|
||||
"workspaceDeleted": "Workspace deleted",
|
||||
"workspaceName": "Workspace name",
|
||||
"writeTheDatabaseStateToOn": "Write the database state to on-disk YAML files.",
|
||||
"yearly": "Yearly",
|
||||
"yourModel": "your model",
|
||||
"zoomIn": "Zoom in",
|
||||
"zoomOut": "Zoom out",
|
||||
|
||||
@@ -112,8 +112,10 @@
|
||||
"budgetAmount": "Ɓũďĝēţ: {{amount}}",
|
||||
"budgetCapConcurrencyAndExecutionEnvironment": "Ɓũďĝēţ ćàƥ, ćōńćũŕŕēńćŷ, àńď ēxēćũţĩōń ēńvĩŕōńḿēńţ.",
|
||||
"budgetLimitsConcurrencyAndExecutionEnvironment": "Ɓũďĝēţ ĺĩḿĩţś, ćōńćũŕŕēńćŷ, àńď ēxēćũţĩōń ēńvĩŕōńḿēńţ.",
|
||||
"budgetPeriodDaily": "ďàĩĺŷ",
|
||||
"budgetPeriodMonthly": "ḿōńţĥĺŷ",
|
||||
"budgetPeriodTotal": "ţōţàĺ",
|
||||
"budgetPeriodYearly": "ŷēàŕĺŷ",
|
||||
"budgetPolicies": "Ɓũďĝēţ Ƥōĺĩćĩēś",
|
||||
"budgetPolicyCreated": "Ɓũďĝēţ ƥōĺĩćŷ ćŕēàţēď",
|
||||
"budgetPolicyDeleted": "Ɓũďĝēţ ƥōĺĩćŷ ďēĺēţēď",
|
||||
@@ -256,11 +258,16 @@
|
||||
"currentlyMapsTo": "Ćũŕŕēńţĺŷ ḿàƥś ţō",
|
||||
"currentRouteTooltip": "Ŕēƒĺēćţś ţĥē ńēxţ-ĺàũńćĥ ćĥōĩćē. Ĩń-ƒĺĩĝĥţ śēśśĩōń ďēţàĩĺś àŕē ōń ēàćĥ ŕũń.",
|
||||
"currentUtilizationOfSubscriptionRateLimit": "Ćũŕŕēńţ ũţĩĺĩźàţĩōń ōƒ śũƀśćŕĩƥţĩōń ŕàţē-ĺĩḿĩţ ŵĩńďōŵś.",
|
||||
"daily": "Ďàĩĺŷ",
|
||||
"dailyDepUpdate": "Ďàĩĺŷ Ďēƥ Ũƥďàţē",
|
||||
"dailySuccessRate": "Ďàĩĺŷ śũććēśś ŕàţē",
|
||||
"dangerZone": "Ďàńĝēŕ Źōńē",
|
||||
"dashboard": "Ďàśĥƀōàŕď",
|
||||
"date": "Ďàţē",
|
||||
"defaultCeiling": "Ďēƒàũĺţ Ćēĩĺĩńĝ",
|
||||
"defaultCeilingDescription": "Ɓĺōćķś ńēŵ ũńàţţēńďēď ŕũńś ōńćē ţĥĩś ŵōŕķśƥàćē'ś śƥēńď ƒōŕ ţĥē ćũŕŕēńţ ŨŢĆ ďàŷ ŕēàćĥēś ţĥē ĺĩḿĩţ ƀēĺōŵ. Ńēvēŕ ƀĺōćķś àń àţţēńďēď ŕũń. À ŵōŕķśƥàćē-ĺēvēĺ ďàĩĺŷ ƥōĺĩćŷ ţĥàţ ƥàũśēś àĝēńţś ōŕ ƀĺōćķś ńēŵ ţàśķś ŕēƥĺàćēś ţĥĩś ćēĩĺĩńĝ; à ńōţĩƒŷ-ōńĺŷ ƥōĺĩćŷ ďōēś ńōţ, àńď ƀōţĥ àƥƥĺŷ ţōĝēţĥēŕ.",
|
||||
"defaultCeilingMustBePositive": "Ďēƒàũĺţ ćēĩĺĩńĝ ḿũśţ ƀē ĝŕēàţēŕ ţĥàń źēŕō",
|
||||
"defaultCeilingUpdated": "Ďēƒàũĺţ ćēĩĺĩńĝ ũƥďàţēď",
|
||||
"defaultFor": "ĎĒƑÀŨĹŢ ƑŌŔ",
|
||||
"defaultForRole": "ďēƒàũĺţ ƒōŕ {{role}}",
|
||||
"defaultTier": "Ďēƒàũĺţ ţĩēŕ",
|
||||
@@ -286,6 +293,7 @@
|
||||
"dockerImageWithExample": "Ďōćķēŕ ĩḿàĝē (ē.ĝ. ńōďē:20-śĺĩḿ)",
|
||||
"duration": "Ďũŕàţĩōń",
|
||||
"editable": "Ēďĩţàƀĺē",
|
||||
"editDefaultCeiling": "Ēďĩţ ďēƒàũĺţ ćēĩĺĩńĝ",
|
||||
"editRoutine": "Ēďĩţ ŕōũţĩńē",
|
||||
"effectiveActionsThisAgentCanRequest": "Ēƒƒēćţĩvē àćţĩōńś ţĥĩś àĝēńţ ćàń ŕēqũēśţ ďũŕĩńĝ Ōƒƒĩćē ŕũńś.",
|
||||
"eGCodeReview": "ē.ĝ. ćōďē-ŕēvĩēŵ",
|
||||
@@ -337,6 +345,7 @@
|
||||
"failedToLoadBudgets": "Ƒàĩĺēď ţō ĺōàď ƀũďĝēţś",
|
||||
"failedToLoadChannels": "Ƒàĩĺēď ţō ĺōàď ćĥàńńēĺś",
|
||||
"failedToLoadCostData": "Ƒàĩĺēď ţō ĺōàď ćōśţ ďàţà",
|
||||
"failedToLoadDefaultCeiling": "Ƒàĩĺēď ţō ĺōàď ďēƒàũĺţ ćēĩĺĩńĝ",
|
||||
"failedToLoadDeletionSummary": "Ƒàĩĺēď ţō ĺōàď ďēĺēţĩōń śũḿḿàŕŷ",
|
||||
"failedToLoadDiffs": "Ƒàĩĺēď ţō ĺōàď ďĩƒƒś",
|
||||
"failedToLoadExportBundle": "Ƒàĩĺēď ţō ĺōàď ēxƥōŕţ ƀũńďĺē",
|
||||
@@ -358,6 +367,7 @@
|
||||
"failedToSaveRoutine": "Ƒàĩĺēď ţō śàvē ŕōũţĩńē",
|
||||
"failedToSaveSettings": "Ƒàĩĺēď ţō śàvē śēţţĩńĝś",
|
||||
"failedToUpdateAgent": "Ƒàĩĺēď ţō ũƥďàţē àĝēńţ",
|
||||
"failedToUpdateDefaultCeiling": "Ƒàĩĺēď ţō ũƥďàţē ďēƒàũĺţ ćēĩĺĩńĝ",
|
||||
"failedToUpdateRoutine": "Ƒàĩĺēď ţō ũƥďàţē ŕōũţĩńē",
|
||||
"failedToUpdateSkills": "Ƒàĩĺēď ţō ũƥďàţē śķĩĺĺś",
|
||||
"fallback": "Ƒàĺĺƀàćķ",
|
||||
@@ -738,6 +748,7 @@
|
||||
"saveChanges": "Śàvē Ćĥàńĝēś",
|
||||
"saveConfiguration": "Śàvē Ćōńƒĩĝũŕàţĩōń",
|
||||
"saved": "Śàvēď {{filename}}",
|
||||
"saveDefaultCeiling": "Śàvē",
|
||||
"saveOverrides": "Śàvē ōvēŕŕĩďēś",
|
||||
"savePermissions": "Śàvē Ƥēŕḿĩśśĩōńś",
|
||||
"saveSkills": "Śàvē śķĩĺĺś",
|
||||
@@ -957,6 +968,7 @@
|
||||
"workspaceDeleted": "Ŵōŕķśƥàćē ďēĺēţēď",
|
||||
"workspaceName": "Ŵōŕķśƥàćē ńàḿē",
|
||||
"writeTheDatabaseStateToOn": "Ŵŕĩţē ţĥē ďàţàƀàśē śţàţē ţō ōń-ďĩśķ ŶÀḾĹ ƒĩĺēś.",
|
||||
"yearly": "Ŷēàŕĺŷ",
|
||||
"yourModel": "ŷōũŕ ḿōďēĺ",
|
||||
"zoomIn": "Źōōḿ ĩń",
|
||||
"zoomOut": "Źōōḿ ōũţ",
|
||||
|
||||
@@ -112,8 +112,10 @@
|
||||
"budgetAmount": "Orçamento: {{amount}}",
|
||||
"budgetCapConcurrencyAndExecutionEnvironment": "Limite de orçamento, concorrência e ambiente de execução.",
|
||||
"budgetLimitsConcurrencyAndExecutionEnvironment": "Limites de orçamento, concorrência e ambiente de execução.",
|
||||
"budgetPeriodDaily": "diário",
|
||||
"budgetPeriodMonthly": "mensal",
|
||||
"budgetPeriodTotal": "total",
|
||||
"budgetPeriodYearly": "anual",
|
||||
"budgetPolicies": "Políticas de orçamento",
|
||||
"budgetPolicyCreated": "Política de orçamento criada",
|
||||
"budgetPolicyDeleted": "Política de orçamento eliminada",
|
||||
@@ -256,11 +258,16 @@
|
||||
"currentlyMapsTo": "Atualmente mapeia para",
|
||||
"currentRouteTooltip": "Reflete a escolha do próximo lançamento. Os detalhes das sessões em curso estão em cada execução.",
|
||||
"currentUtilizationOfSubscriptionRateLimit": "Utilização atual das janelas de limite de taxa da subscrição.",
|
||||
"daily": "Diário",
|
||||
"dailyDepUpdate": "Atualização diária de dependências",
|
||||
"dailySuccessRate": "Taxa de sucesso diária",
|
||||
"dangerZone": "Zona de perigo",
|
||||
"dashboard": "Painel",
|
||||
"date": "Data",
|
||||
"defaultCeiling": "Limite máximo predefinido",
|
||||
"defaultCeilingDescription": "Bloqueia novas execuções não assistidas quando a despesa deste espaço de trabalho no dia UTC atual atingir o limite abaixo. Nunca bloqueia uma execução assistida. Uma política diária ao nível do espaço de trabalho que pausa agentes ou bloqueia novas tarefas substitui este limite máximo; uma política apenas de notificação não o substitui, e ambas são aplicadas em conjunto.",
|
||||
"defaultCeilingMustBePositive": "O limite máximo predefinido deve ser superior a zero",
|
||||
"defaultCeilingUpdated": "Limite máximo predefinido atualizado",
|
||||
"defaultFor": "PRÉ-DEFINIDO PARA",
|
||||
"defaultForRole": "pré-definido para {{role}}",
|
||||
"defaultTier": "Escalão pré-definido",
|
||||
@@ -286,6 +293,7 @@
|
||||
"dockerImageWithExample": "Imagem Docker (por exemplo, node:20-slim)",
|
||||
"duration": "Duração",
|
||||
"editable": "Editável",
|
||||
"editDefaultCeiling": "Editar limite máximo predefinido",
|
||||
"editRoutine": "Editar rotina",
|
||||
"effectiveActionsThisAgentCanRequest": "Ações efetivas que este agente pode pedir durante as execuções do Office.",
|
||||
"eGCodeReview": "por exemplo, code-review",
|
||||
@@ -337,6 +345,7 @@
|
||||
"failedToLoadBudgets": "Não foi possível carregar os orçamentos",
|
||||
"failedToLoadChannels": "Não foi possível carregar os canais",
|
||||
"failedToLoadCostData": "Não foi possível carregar os dados de custos",
|
||||
"failedToLoadDefaultCeiling": "Não foi possível carregar o limite máximo predefinido",
|
||||
"failedToLoadDeletionSummary": "Não foi possível carregar o resumo da eliminação",
|
||||
"failedToLoadDiffs": "Não foi possível carregar os diffs",
|
||||
"failedToLoadExportBundle": "Não foi possível carregar o pacote de exportação",
|
||||
@@ -358,6 +367,7 @@
|
||||
"failedToSaveRoutine": "Não foi possível guardar a rotina",
|
||||
"failedToSaveSettings": "Não foi possível guardar as definições",
|
||||
"failedToUpdateAgent": "Não foi possível atualizar o agente",
|
||||
"failedToUpdateDefaultCeiling": "Não foi possível atualizar o limite máximo predefinido",
|
||||
"failedToUpdateRoutine": "Não foi possível atualizar a rotina",
|
||||
"failedToUpdateSkills": "Não foi possível atualizar as competências",
|
||||
"fallback": "Recurso",
|
||||
@@ -738,6 +748,7 @@
|
||||
"saveChanges": "Guardar alterações",
|
||||
"saveConfiguration": "Guardar configuração",
|
||||
"saved": "{{filename}} guardado",
|
||||
"saveDefaultCeiling": "Guardar",
|
||||
"saveOverrides": "Guardar as substituições",
|
||||
"savePermissions": "Guardar permissões",
|
||||
"saveSkills": "Guardar competências",
|
||||
@@ -957,6 +968,7 @@
|
||||
"workspaceDeleted": "Área de trabalho eliminada",
|
||||
"workspaceName": "Nome da área de trabalho",
|
||||
"writeTheDatabaseStateToOn": "Escrever o estado da base de dados em ficheiros YAML no disco.",
|
||||
"yearly": "Anual",
|
||||
"yourModel": "o seu modelo",
|
||||
"zoomIn": "Aproximar",
|
||||
"zoomOut": "Afastar",
|
||||
|
||||
@@ -112,8 +112,10 @@
|
||||
"budgetAmount": "预算:{{amount}}",
|
||||
"budgetCapConcurrencyAndExecutionEnvironment": "预算上限、并发与执行环境。",
|
||||
"budgetLimitsConcurrencyAndExecutionEnvironment": "预算限制、并发与执行环境。",
|
||||
"budgetPeriodDaily": "每日",
|
||||
"budgetPeriodMonthly": "每月",
|
||||
"budgetPeriodTotal": "总计",
|
||||
"budgetPeriodYearly": "每年",
|
||||
"budgetPolicies": "预算策略",
|
||||
"budgetPolicyCreated": "预算策略已创建",
|
||||
"budgetPolicyDeleted": "预算策略已删除",
|
||||
@@ -256,11 +258,16 @@
|
||||
"currentlyMapsTo": "当前映射到",
|
||||
"currentRouteTooltip": "反映下次启动的选择。进行中的会话详情见各次运行。",
|
||||
"currentUtilizationOfSubscriptionRateLimit": "订阅速率限制窗口的当前利用率。",
|
||||
"daily": "每日",
|
||||
"dailyDepUpdate": "每日依赖更新",
|
||||
"dailySuccessRate": "每日成功率",
|
||||
"dangerZone": "危险区域",
|
||||
"dashboard": "仪表盘",
|
||||
"date": "日期",
|
||||
"defaultCeiling": "默认上限",
|
||||
"defaultCeilingDescription": "当此工作区当前 UTC 日的支出达到以下限额时,将阻止新的无人值守运行。永远不会阻止有人值守的运行。工作区级别的每日策略如果设置为暂停智能体或阻止新任务,将取代此上限;仅通知的策略不会取代它,两者会同时生效。",
|
||||
"defaultCeilingMustBePositive": "默认上限必须大于零",
|
||||
"defaultCeilingUpdated": "默认上限已更新",
|
||||
"defaultFor": "默认用于",
|
||||
"defaultForRole": "{{role}} 的默认值",
|
||||
"defaultTier": "默认层级",
|
||||
@@ -286,6 +293,7 @@
|
||||
"dockerImageWithExample": "Docker 镜像(例如 node:20-slim)",
|
||||
"duration": "时长",
|
||||
"editable": "可编辑",
|
||||
"editDefaultCeiling": "编辑默认上限",
|
||||
"editRoutine": "编辑例行程序",
|
||||
"effectiveActionsThisAgentCanRequest": "此智能体在办公室运行期间可请求的有效操作。",
|
||||
"eGCodeReview": "例如 code-review",
|
||||
@@ -337,6 +345,7 @@
|
||||
"failedToLoadBudgets": "加载预算失败",
|
||||
"failedToLoadChannels": "加载渠道失败",
|
||||
"failedToLoadCostData": "加载费用数据失败",
|
||||
"failedToLoadDefaultCeiling": "加载默认上限失败",
|
||||
"failedToLoadDeletionSummary": "加载删除摘要失败",
|
||||
"failedToLoadDiffs": "加载差异失败",
|
||||
"failedToLoadExportBundle": "加载导出包失败",
|
||||
@@ -358,6 +367,7 @@
|
||||
"failedToSaveRoutine": "保存例行程序失败",
|
||||
"failedToSaveSettings": "保存设置失败",
|
||||
"failedToUpdateAgent": "更新智能体失败",
|
||||
"failedToUpdateDefaultCeiling": "更新默认上限失败",
|
||||
"failedToUpdateRoutine": "更新例行程序失败",
|
||||
"failedToUpdateSkills": "更新技能失败",
|
||||
"fallback": "回退",
|
||||
@@ -738,6 +748,7 @@
|
||||
"saveChanges": "保存更改",
|
||||
"saveConfiguration": "保存配置",
|
||||
"saved": "已保存 {{filename}}",
|
||||
"saveDefaultCeiling": "保存",
|
||||
"saveOverrides": "保存覆盖",
|
||||
"savePermissions": "保存权限",
|
||||
"saveSkills": "保存技能",
|
||||
@@ -957,6 +968,7 @@
|
||||
"workspaceDeleted": "工作区已删除",
|
||||
"workspaceName": "工作区名称",
|
||||
"writeTheDatabaseStateToOn": "将数据库状态写入磁盘上的 YAML 文件。",
|
||||
"yearly": "每年",
|
||||
"yourModel": "你的模型",
|
||||
"zoomIn": "放大",
|
||||
"zoomOut": "缩小",
|
||||
|
||||
@@ -112,8 +112,10 @@
|
||||
"budgetAmount": "預算:{{amount}}",
|
||||
"budgetCapConcurrencyAndExecutionEnvironment": "預算上限、併發與執行環境。",
|
||||
"budgetLimitsConcurrencyAndExecutionEnvironment": "預算限制、併發與執行環境。",
|
||||
"budgetPeriodDaily": "每日",
|
||||
"budgetPeriodMonthly": "每月",
|
||||
"budgetPeriodTotal": "總計",
|
||||
"budgetPeriodYearly": "每年",
|
||||
"budgetPolicies": "預算策略",
|
||||
"budgetPolicyCreated": "預算策略已建立",
|
||||
"budgetPolicyDeleted": "預算策略已刪除",
|
||||
@@ -256,11 +258,16 @@
|
||||
"currentlyMapsTo": "目前映射到",
|
||||
"currentRouteTooltip": "反映下次啓動的選擇。進行中的工作階段詳情見各次執行。",
|
||||
"currentUtilizationOfSubscriptionRateLimit": "訂閲速率限制窗口的目前利用率。",
|
||||
"daily": "每日",
|
||||
"dailyDepUpdate": "每日依賴更新",
|
||||
"dailySuccessRate": "每日成功率",
|
||||
"dangerZone": "危險區域",
|
||||
"dashboard": "儀表盤",
|
||||
"date": "日期",
|
||||
"defaultCeiling": "預設上限",
|
||||
"defaultCeilingDescription": "當此工作區目前 UTC 日的支出達到以下限額時,將阻止新的無人值守執行。永遠不會阻止有人值守的執行。工作區級別的每日策略如果設定為暫停代理程式或阻止新任務,將取代此上限;僅通知的策略不會取代它,兩者會同時生效。",
|
||||
"defaultCeilingMustBePositive": "預設上限必須大於零",
|
||||
"defaultCeilingUpdated": "預設上限已更新",
|
||||
"defaultFor": "預設用於",
|
||||
"defaultForRole": "{{role}} 的預設值",
|
||||
"defaultTier": "預設層級",
|
||||
@@ -286,6 +293,7 @@
|
||||
"dockerImageWithExample": "Docker 鏡像(例如 node:20-slim)",
|
||||
"duration": "時長",
|
||||
"editable": "可編輯",
|
||||
"editDefaultCeiling": "編輯預設上限",
|
||||
"editRoutine": "編輯例行程序",
|
||||
"effectiveActionsThisAgentCanRequest": "此代理程式在辦公室執行期間可請求的有效操作。",
|
||||
"eGCodeReview": "例如 code-review",
|
||||
@@ -337,6 +345,7 @@
|
||||
"failedToLoadBudgets": "載入預算失敗",
|
||||
"failedToLoadChannels": "載入渠道失敗",
|
||||
"failedToLoadCostData": "載入費用數據失敗",
|
||||
"failedToLoadDefaultCeiling": "載入預設上限失敗",
|
||||
"failedToLoadDeletionSummary": "載入刪除摘要失敗",
|
||||
"failedToLoadDiffs": "載入差異失敗",
|
||||
"failedToLoadExportBundle": "載入匯出包失敗",
|
||||
@@ -358,6 +367,7 @@
|
||||
"failedToSaveRoutine": "儲存例行程序失敗",
|
||||
"failedToSaveSettings": "儲存設定失敗",
|
||||
"failedToUpdateAgent": "更新代理程式失敗",
|
||||
"failedToUpdateDefaultCeiling": "更新預設上限失敗",
|
||||
"failedToUpdateRoutine": "更新例行程序失敗",
|
||||
"failedToUpdateSkills": "更新技能失敗",
|
||||
"fallback": "後備",
|
||||
@@ -738,6 +748,7 @@
|
||||
"saveChanges": "儲存更改",
|
||||
"saveConfiguration": "儲存設定",
|
||||
"saved": "已儲存 {{filename}}",
|
||||
"saveDefaultCeiling": "儲存",
|
||||
"saveOverrides": "儲存覆蓋",
|
||||
"savePermissions": "儲存權限",
|
||||
"saveSkills": "儲存技能",
|
||||
@@ -957,6 +968,7 @@
|
||||
"workspaceDeleted": "工作區已刪除",
|
||||
"workspaceName": "工作區名稱",
|
||||
"writeTheDatabaseStateToOn": "將數據庫狀態寫入磁碟上的 YAML 檔案。",
|
||||
"yearly": "每年",
|
||||
"yourModel": "你的模型",
|
||||
"zoomIn": "放大",
|
||||
"zoomOut": "縮小",
|
||||
|
||||
@@ -425,8 +425,8 @@
|
||||
"portableConfigNotFound": "未找到",
|
||||
"portableConfigNotFoundHint": "這只是編輯提示。你可以先儲存設定,稍後再新增該檔案。",
|
||||
"portableConfigTitle": "代理程式設定檔",
|
||||
"allowUserNamespacesTitle": "使用者名稱空間支援",
|
||||
"allowUserNamespacesDescription": "允許在容器內建立無特權的使用者名稱空間和執行掛載操作。啟用類似 bwrap 的沙箱工具。",
|
||||
"allowUserNamespacesTitle": "使用者命名空間支援",
|
||||
"allowUserNamespacesDescription": "允許在容器內建立無特權的使用者命名空間和執行掛載操作。啟用類似 bwrap 的沙箱工具。",
|
||||
"allowUserNamespacesNote": "此設定僅影響新建立的容器。現有任務環境必須重置才能使更改生效。",
|
||||
"allowUserNamespacesWarning": "這會為選擇啟用的容器停用 Docker 預設的 AppArmor 限制。僅為需要使用者名稱空間沙箱的可信代理執行環境啟用。"
|
||||
"allowUserNamespacesWarning": "這會為選擇啟用的容器停用 Docker 預設的 AppArmor 限制。僅為需要使用者命名空間沙箱的可信代理執行環境啟用。"
|
||||
}
|
||||
|
||||
@@ -112,8 +112,10 @@
|
||||
"budgetAmount": "預算:{{amount}}",
|
||||
"budgetCapConcurrencyAndExecutionEnvironment": "預算上限、併發與執行環境。",
|
||||
"budgetLimitsConcurrencyAndExecutionEnvironment": "預算限制、併發與執行環境。",
|
||||
"budgetPeriodDaily": "每日",
|
||||
"budgetPeriodMonthly": "每月",
|
||||
"budgetPeriodTotal": "總計",
|
||||
"budgetPeriodYearly": "每年",
|
||||
"budgetPolicies": "預算策略",
|
||||
"budgetPolicyCreated": "預算策略已建立",
|
||||
"budgetPolicyDeleted": "預算策略已刪除",
|
||||
@@ -256,11 +258,16 @@
|
||||
"currentlyMapsTo": "目前對映到",
|
||||
"currentRouteTooltip": "反映下次啟動的選擇。進行中的工作階段詳情見各次執行。",
|
||||
"currentUtilizationOfSubscriptionRateLimit": "訂閱速率限制視窗的目前利用率。",
|
||||
"daily": "每日",
|
||||
"dailyDepUpdate": "每日依賴更新",
|
||||
"dailySuccessRate": "每日成功率",
|
||||
"dangerZone": "危險區域",
|
||||
"dashboard": "儀表盤",
|
||||
"date": "日期",
|
||||
"defaultCeiling": "預設上限",
|
||||
"defaultCeilingDescription": "當此工作區目前 UTC 日的支出達到以下限額時,將阻止新的無人值守執行。永遠不會阻止有人值守的執行。工作區級別的每日策略如果設定為暫停代理程式或阻止新任務,將取代此上限;僅通知的策略不會取代它,兩者會同時生效。",
|
||||
"defaultCeilingMustBePositive": "預設上限必須大於零",
|
||||
"defaultCeilingUpdated": "預設上限已更新",
|
||||
"defaultFor": "預設用於",
|
||||
"defaultForRole": "{{role}} 的預設值",
|
||||
"defaultTier": "預設層級",
|
||||
@@ -286,6 +293,7 @@
|
||||
"dockerImageWithExample": "Docker 映象(例如 node:20-slim)",
|
||||
"duration": "時長",
|
||||
"editable": "可編輯",
|
||||
"editDefaultCeiling": "編輯預設上限",
|
||||
"editRoutine": "編輯例行程式",
|
||||
"effectiveActionsThisAgentCanRequest": "此代理程式在辦公室執行期間可請求的有效操作。",
|
||||
"eGCodeReview": "例如 code-review",
|
||||
@@ -337,6 +345,7 @@
|
||||
"failedToLoadBudgets": "載入預算失敗",
|
||||
"failedToLoadChannels": "載入渠道失敗",
|
||||
"failedToLoadCostData": "載入費用資料失敗",
|
||||
"failedToLoadDefaultCeiling": "載入預設上限失敗",
|
||||
"failedToLoadDeletionSummary": "載入刪除摘要失敗",
|
||||
"failedToLoadDiffs": "載入差異失敗",
|
||||
"failedToLoadExportBundle": "載入匯出包失敗",
|
||||
@@ -358,6 +367,7 @@
|
||||
"failedToSaveRoutine": "儲存例行程式失敗",
|
||||
"failedToSaveSettings": "儲存設定失敗",
|
||||
"failedToUpdateAgent": "更新代理程式失敗",
|
||||
"failedToUpdateDefaultCeiling": "更新預設上限失敗",
|
||||
"failedToUpdateRoutine": "更新例行程式失敗",
|
||||
"failedToUpdateSkills": "更新技能失敗",
|
||||
"fallback": "備援",
|
||||
@@ -738,6 +748,7 @@
|
||||
"saveChanges": "儲存更改",
|
||||
"saveConfiguration": "儲存設定",
|
||||
"saved": "已儲存 {{filename}}",
|
||||
"saveDefaultCeiling": "儲存",
|
||||
"saveOverrides": "儲存覆蓋",
|
||||
"savePermissions": "儲存權限",
|
||||
"saveSkills": "儲存技能",
|
||||
@@ -957,6 +968,7 @@
|
||||
"workspaceDeleted": "工作區已刪除",
|
||||
"workspaceName": "工作區名稱",
|
||||
"writeTheDatabaseStateToOn": "將資料庫狀態寫入磁碟上的 YAML 檔案。",
|
||||
"yearly": "每年",
|
||||
"yourModel": "你的模型",
|
||||
"zoomIn": "放大",
|
||||
"zoomOut": "縮小",
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
specification_version: 1
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office glossary
|
||||
|
||||
Shared vocabulary for Office specifications. Terms are grouped by the capability
|
||||
that defines them; a capability's requirement documents reference this file
|
||||
rather than restating a definition, so one term cannot drift between documents.
|
||||
|
||||
## Budget enforcement
|
||||
|
||||
Defined by [Office: Pre-Launch Budget Enforcement](requirements/budget-enforcement.md)
|
||||
and used by [Budget Admission
|
||||
Integrity](requirements/budget-admission-integrity.md), [Built-In Default Spend
|
||||
Ceiling](requirements/budget-default-ceiling.md), [Budget Measurement
|
||||
Integrity](requirements/budget-measurement-integrity.md) and [Budget Enforcement
|
||||
Observability](requirements/budget-observability.md).
|
||||
|
||||
- **Run provenance:** the classification of a run as *attended* or
|
||||
*unattended*, derived from `runs.reason`.
|
||||
- **Attended run:** a run whose reason is in the attended allowlist
|
||||
(`AC-OFFICE-BUDGET-007.2`). A person plausibly caused it and is plausibly
|
||||
waiting on it.
|
||||
- **Unattended run:** any run that is not attended, **including any reason the
|
||||
allowlist does not recognize**.
|
||||
- **Subcent:** one hundredth of a United States cent, i.e. `1 USD = 10_000`
|
||||
subcents. Already the storage unit of `office_cost_events.cost_subcents` and
|
||||
`office_budget_policies.limit_subcents`.
|
||||
- **Priced spend:** the sum of `cost_subcents` over the cost events a policy's
|
||||
scope selects (`AC-OFFICE-BUDGET-002.15`) and whose `occurred_at` falls in the
|
||||
evaluation window, which by construction counts an unpriced event as zero.
|
||||
- **Unpriced event:** a cost event with `cost_source = 'unpriced'`. A NULL
|
||||
`cost_source` is **not** an unpriced event — it is a legacy row written
|
||||
before the cost contract added the column, and it carries a real cost.
|
||||
- **Pricing-degraded window:** an evaluation window containing at least one
|
||||
unpriced event.
|
||||
- **Evaluator fault:** the pre-execution budget evaluator returning a non-nil
|
||||
error. A missing evaluator is a distinct state, not a fault.
|
||||
- **Evaluation window:** the half-open interval `[cutoff, now)` a policy's
|
||||
period selects, with `cutoff` computed in UTC.
|
||||
- **Admission gate:** one of the five ordered checks in
|
||||
`AC-OFFICE-BUDGET-001.14` that can stop a run before launch.
|
||||
- **Applicable policy:** a policy selected for a run by
|
||||
`AC-OFFICE-BUDGET-001.15`.
|
||||
|
||||
> **Polarity warning for implementers.** `IsPeriodicTasklessWake` classifies
|
||||
> the ambiguous legacy reason `routine_dispatch` as **non**-periodic, because
|
||||
> for the idle-skip gate the safe answer is "do not skip". For budget
|
||||
> enforcement the safe answer is the opposite: the same literal is
|
||||
> **unattended**, because the safe answer here is "do not spend". Reusing
|
||||
> `IsPeriodicTasklessWake` for provenance would invert this and fail open on
|
||||
> exactly the legacy cron rows it is meant to catch.
|
||||
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
created: 2026-09-06
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Budget Admission Integrity Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies which
|
||||
admission gate stops a run and what disposition the run gets. That contract
|
||||
rests on two properties its own criteria never state: that every applicable
|
||||
policy was actually evaluated, and that evaluating them changed nothing.
|
||||
Neither holds in the code this capability replaces.
|
||||
|
||||
The pre-launch evaluator iterates the applicable policies and, when one
|
||||
policy's spend query fails, logs the failure and continues, returning a partial
|
||||
result set and no error. Its caller therefore cannot distinguish "no policy
|
||||
blocked this run" from "the policy that would have blocked it was never
|
||||
evaluated". Separately, the per-policy evaluation is not a query: on the same
|
||||
pre-launch call path it writes `budget.alert` and `budget.exceeded` activity
|
||||
entries and can flip an agent to `paused` — side effects
|
||||
[costs.md](costs.md) owns and which
|
||||
[budget-enforcement.md](budget-enforcement.md)'s Out of scope disclaims.
|
||||
|
||||
This document owns those two properties, completeness and inertness, together
|
||||
with the two identifier-resolution failures that reach the same fail-open
|
||||
outcome by a different route. It does not decide which gate blocks a run; that
|
||||
stays in the companion document.
|
||||
|
||||
## Terminology
|
||||
|
||||
This document uses this capability's shared vocabulary, defined in the [Office
|
||||
glossary](../glossary.md) under **Budget enforcement** — in particular
|
||||
*attended run*, *unattended run*, *evaluator fault*, *applicable policy*,
|
||||
*admission gate*, *evaluation window*, and *priced spend*.
|
||||
|
||||
- **Admission evaluation:** the whole of the work the five admission gates of
|
||||
`AC-OFFICE-BUDGET-001.14` perform for one run, from provenance classification
|
||||
through to the launch or non-launch decision.
|
||||
- **Unevaluated policy:** an applicable policy for which the system could not
|
||||
produce both a priced-spend figure and a pricing-degradation determination.
|
||||
A policy the system deliberately declines to evaluate under
|
||||
`AC-OFFICE-BUDGET-002.5`, `-002.11` or `-002.14` is **not** an unevaluated
|
||||
policy: those criteria decide its disposition, whereas this term names a
|
||||
policy whose disposition could not be decided. The term names an *attempted*
|
||||
evaluation that failed, never one the system chose not to begin: because
|
||||
`AC-OFFICE-BUDGET-006.1` requires every applicable policy be attempted, "not
|
||||
yet reached" is not a state an applicable policy can be left in, and a policy
|
||||
the ordering of `AC-OFFICE-BUDGET-001.9` did not select is therefore not an
|
||||
unevaluated policy.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-OFFICE-BUDGET-006: The admission decision is complete and inert
|
||||
|
||||
**Intent:** A ceiling that is evaluated against some of the applicable policies
|
||||
is not a ceiling, and an admission test that mutates state is not a test. Both
|
||||
failures are silent, and both survive every criterion in the companion
|
||||
documents, because those criteria specify what each gate decides and never
|
||||
specify that the inputs to that decision were all present or that reaching it
|
||||
cost nothing.
|
||||
|
||||
The completeness half matters most on the path this capability exists to fix.
|
||||
`REQ-OFFICE-BUDGET-001`'s intent is that no Office run launches without a
|
||||
ceiling having been evaluated; a partial result set admits the run while
|
||||
reporting no error at all, so the promise fails without any observable symptom.
|
||||
The inertness half matters because `AC-OFFICE-BUDGET-001.9` stops at the first
|
||||
blocking policy. Any side effect produced per policy therefore starts depending
|
||||
on how far down the ordered list the admission decision happened to walk, which
|
||||
would make an operator-visible alert and an agent's paused state a function of
|
||||
policy creation order rather than of spend.
|
||||
|
||||
**User story:** As an operator running Office unattended, I want the ceiling to
|
||||
be computed from every policy that applies and to change nothing on its way to a
|
||||
decision, so that a launch means the ceiling held rather than that part of it
|
||||
went missing.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-006.1:** When any applicable policy selected under
|
||||
`AC-OFFICE-BUDGET-001.15` is an unevaluated policy, the system shall treat
|
||||
that as an evaluator fault and dispose of the run under
|
||||
`AC-OFFICE-BUDGET-001.3`, and shall not decide admission from the policies it
|
||||
did evaluate. Admitting a run on a partial set reproduces the fail-open this
|
||||
capability exists to remove, because the unevaluated policy may be the one
|
||||
that blocks; and because the failure is per policy rather than per call, it
|
||||
produces no error for `AC-OFFICE-BUDGET-001.3` to fire on unless this
|
||||
criterion makes one. Completeness therefore fixes the evaluation model: the
|
||||
system shall attempt every applicable policy before any of them decides
|
||||
admission, and shall apply `AC-OFFICE-BUDGET-001.9`'s first-in-order selection
|
||||
only to a fully evaluated set. Without that two-phase reading the two criteria
|
||||
contradict each other — stopping at the first blocking policy would leave a
|
||||
later erroring policy undetected, which is exactly the partial set this
|
||||
requirement exists to reject, while treating an unvisited policy as
|
||||
unevaluated would make every multi-policy run a fault. This lifts to the
|
||||
policy loop the pattern `AC-OFFICE-BUDGET-001.14` already fixes within a
|
||||
single policy, where the degradation determination is made even for a policy
|
||||
whose limit test has already decided to block.
|
||||
- **AC-OFFICE-BUDGET-006.2:** The admission evaluation shall not write a
|
||||
`budget.alert` or a `budget.exceeded` activity entry, and shall not change any
|
||||
agent's status. Those side effects belong to the post-event evaluation path
|
||||
governed by [costs.md](costs.md), which continues to produce them on its own
|
||||
schedule, unchanged and unconstrained by this capability. This criterion holds
|
||||
whatever the admission outcome: in particular, an applicable policy whose
|
||||
action is `pause_agent` and whose limit is reached shall block the run under
|
||||
`AC-OFFICE-BUDGET-001.7` **without** pausing the agent as part of that
|
||||
decision. The agent's pause remains the post-event path's to perform when the
|
||||
next cost event lands. Stated so the change is a decision rather than a
|
||||
side effect of `AC-OFFICE-BUDGET-001.9`'s stop at the first blocking policy,
|
||||
which would otherwise make the set of alerts fired and agents paused depend on
|
||||
how many policies the admission walk happened to visit.
|
||||
- **AC-OFFICE-BUDGET-006.3:** When the run's project identifier cannot be
|
||||
determined because its lookup failed, the system shall treat that as an
|
||||
evaluator fault and dispose of the run under `AC-OFFICE-BUDGET-001.3`, rather
|
||||
than evaluating the run as one that carries no project identifier. A failed
|
||||
lookup and a run that genuinely has no project are different states:
|
||||
`AC-OFFICE-BUDGET-001.15` makes every `project`-scoped policy inapplicable to
|
||||
the second, so applying that rule to the first lets a transient failure
|
||||
silently remove a whole class of ceiling with no operator-visible symptom. A
|
||||
run carrying no task, or a task that resolves successfully to no project, is
|
||||
the second state and is not a fault. `AC-OFFICE-BUDGET-006.7` classifies every
|
||||
outcome of the resolution, including the two this criterion's error/no-project
|
||||
split does not by itself decide.
|
||||
- **AC-OFFICE-BUDGET-006.4:** When a run deferred by any cause this capability
|
||||
introduces other than the evaluator error itself — the workspace-lookup error
|
||||
branch of `AC-OFFICE-BUDGET-001.13`, an unevaluated policy
|
||||
(`AC-OFFICE-BUDGET-006.1`), or a failed project lookup
|
||||
(`AC-OFFICE-BUDGET-006.3`) — has already reached `MaxRetryCount`, the system
|
||||
shall fail the run and record an operator-visible activity entry naming that
|
||||
cause. The entry shall not name an evaluator error.
|
||||
`AC-OFFICE-BUDGET-001.4` is written for a run scheduled for retry by
|
||||
`AC-OFFICE-BUDGET-001.3` and requires its entry name the evaluator error,
|
||||
which is false for all three; because those three defer *under*
|
||||
`AC-OFFICE-BUDGET-001.3`'s terms, without this criterion each reaches
|
||||
`MaxRetryCount` with a disposition that is either unstated or mislabelled.
|
||||
They reach it on the ordinary path rather than an exotic one: the retry
|
||||
backoff schedule exhausts `MaxRetryCount` well before the staleness bound
|
||||
`AC-OFFICE-BUDGET-001.18` applies, so a sustained outage arrives here and
|
||||
never there.
|
||||
- **AC-OFFICE-BUDGET-006.7:** The run's project identifier shall be resolved at
|
||||
the start of gate 4 of `AC-OFFICE-BUDGET-001.14`, after gate 3 has succeeded,
|
||||
so that a run whose evaluator errors and whose project lookup would also fail
|
||||
has one determinate disposition rather than one depending on which lookup the
|
||||
implementation happens to run first. Resolution has four outcomes and each has
|
||||
a stated disposition, mirroring the error/empty split
|
||||
`AC-OFFICE-BUDGET-001.13` makes for the workspace. (a) The payload is
|
||||
well-formed and carries no task identifier, or the task resolves and carries
|
||||
no project: the run genuinely has no project, no `project`-scoped policy
|
||||
applies to it under `AC-OFFICE-BUDGET-001.15`, and this is not a fault.
|
||||
(b) The lookup returns an error: an evaluator fault under
|
||||
`AC-OFFICE-BUDGET-006.3`, deferred and retried. (c) The payload cannot be
|
||||
parsed: the system shall not read this as outcome (a), because a payload it
|
||||
cannot parse is no evidence that no task identifier was present; it shall
|
||||
cancel the run rather than retry or fail it, and record an operator-visible
|
||||
activity entry naming the unparseable payload. (d) The lookup succeeds and the
|
||||
named task does not exist: the system shall likewise cancel the run, naming
|
||||
the missing task. Cases (c) and (d) are permanent conditions no retry can
|
||||
clear, so deferring them would spend the run's whole retry budget on something
|
||||
that cannot resolve — the reasoning `AC-OFFICE-BUDGET-001.5` already applies
|
||||
to an absent evaluator. A run cancelled here shall not re-enter the queue.
|
||||
- **AC-OFFICE-BUDGET-006.5:** Each state this requirement introduces shall be
|
||||
distinguishable, by the queryable activity-entry field
|
||||
`AC-OFFICE-BUDGET-005.3` establishes, from `budget_blocked` and from every
|
||||
other state that criterion enumerates: an evaluator fault raised by an
|
||||
unevaluated policy (`AC-OFFICE-BUDGET-006.1`), one raised by a failed project
|
||||
lookup (`AC-OFFICE-BUDGET-006.3`), and a deferral failed at `MaxRetryCount`
|
||||
under `AC-OFFICE-BUDGET-006.4`, itself distinguishable by which of that
|
||||
criterion's three causes produced it. The first two share
|
||||
`AC-OFFICE-BUDGET-001.3`'s disposition with the evaluator fault proper and
|
||||
shall still be distinguishable from it and from each other, because the three
|
||||
have different operator remedies. An entry concerning an unevaluated policy —
|
||||
whether the deferral under `AC-OFFICE-BUDGET-006.1` or its failure under
|
||||
`AC-OFFICE-BUDGET-006.4` — shall name the policy it could not evaluate; every
|
||||
other entry named here shall state that no ceiling was determined, per
|
||||
`AC-OFFICE-BUDGET-005.5`. The two cancellations of `AC-OFFICE-BUDGET-006.7` —
|
||||
an unparseable payload (c) and a task that does not exist (d) — are further
|
||||
states on these same terms, distinguishable from each other and from the
|
||||
failed-lookup deferral of (b), because an operator repairs a malformed payload
|
||||
and a deleted task differently.
|
||||
- **AC-OFFICE-BUDGET-006.6:** The system shall expose counters for each state in
|
||||
`AC-OFFICE-BUDGET-006.5`, in the same `/debug/vars` surface and under the same
|
||||
labelling and counting rules as `AC-OFFICE-BUDGET-005.4` — which means the two
|
||||
deferral counters count deferral *attempts* rather than runs, under that
|
||||
criterion's rule for every deferral counter, while a run failed at
|
||||
`MaxRetryCount` increments one counter per cause named in
|
||||
`AC-OFFICE-BUDGET-006.4`, not one counter shared across the three, each
|
||||
counting runs once per run. Sharing one counter would satisfy this criterion
|
||||
while defeating `AC-OFFICE-BUDGET-006.5`'s requirement that the causes stay
|
||||
distinguishable. The two cancellations of `AC-OFFICE-BUDGET-006.7` likewise
|
||||
carry one counter each, counting runs once per run.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Changing the post-event evaluation path.** `AC-OFFICE-BUDGET-006.2` removes
|
||||
two side effects from the *admission* path only. When `budget.alert` and
|
||||
`budget.exceeded` fire, what `alert_threshold_pct` means, and when a
|
||||
`pause_agent` policy pauses an agent all remain governed by
|
||||
[costs.md](costs.md), on the post-event path, unchanged.
|
||||
- **Unpausing an agent paused by the post-event path.** A known separate defect,
|
||||
named in [budget-enforcement.md](budget-enforcement.md)'s Out of scope and not
|
||||
fixed here.
|
||||
- **Retrying an unevaluated policy in isolation.** `AC-OFFICE-BUDGET-006.1`
|
||||
defers the whole run rather than re-evaluating the one policy that failed.
|
||||
A per-policy retry inside a single admission decision would need its own
|
||||
budget and its own bound, and would sit inside the gate sequence
|
||||
`AC-OFFICE-BUDGET-001.14` fixes.
|
||||
- **Distinguishing which underlying failure made a policy unevaluated.** A
|
||||
timeout, a closed database and a malformed stored row all produce one state
|
||||
here. The activity entry names the policy, per `AC-OFFICE-BUDGET-006.5`; it
|
||||
does not classify the cause.
|
||||
- **Retention or pruning of the activity entries this capability writes.**
|
||||
- **The system design for this capability.** Where completeness is enforced and
|
||||
how the admission path is separated from the post-event path belong in the
|
||||
paired system-design document authored before implementation.
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
created: 2026-09-06
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Built-In Default Spend Ceiling Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies when a
|
||||
run is admitted against a spend ceiling. Correct enforcement code with zero
|
||||
policies configured is still no ceiling, and `office_budget_policies` holds
|
||||
zero rows on the reference install. This document owns the bound that exists on
|
||||
a fresh install without an operator opting in.
|
||||
|
||||
It does not change admission behavior, which stays in the companion document,
|
||||
and it does not measure spend, which is
|
||||
[Office: Budget Measurement Integrity](budget-measurement-integrity.md).
|
||||
|
||||
## Terminology
|
||||
|
||||
This document uses this capability's shared vocabulary, defined in the [Office
|
||||
glossary](../glossary.md) under **Budget enforcement** — in particular
|
||||
*attended run*, *unattended run*, *subcent*, *priced spend*, and *evaluation
|
||||
window*.
|
||||
|
||||
- **Built-in default ceiling:** a single operator-tunable limit per workspace,
|
||||
evaluated for unattended runs when no operator policy supersedes it. It is
|
||||
**not** a row in `office_budget_policies`; see
|
||||
`AC-OFFICE-BUDGET-003.7`.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-OFFICE-BUDGET-003: A default ceiling ships enabled for unattended runs
|
||||
|
||||
**Intent:** Beta needs a bound that exists without an operator opting in.
|
||||
Scoping the default to unattended runs is what makes shipping it safe: attended
|
||||
work, which is all of the reference install's measured spend, is unaffected by
|
||||
its presence. The default is a *floor under* the operator's configuration, not
|
||||
a placeholder the operator's first policy replaces — so a policy that never
|
||||
blocks cannot remove it, and editing its limit cannot convert it into a policy
|
||||
that blocks attended work.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-003.1:** When no operator policy supersedes it under
|
||||
`AC-OFFICE-BUDGET-003.4`, the system shall evaluate unattended runs in that
|
||||
workspace against the built-in default ceiling.
|
||||
- **AC-OFFICE-BUDGET-003.2:** The built-in default ceiling shall be 500,000
|
||||
subcents (50.00 USD) of priced spend per workspace per UTC day, and shall
|
||||
block on reaching that limit in the manner of a `block_new_tasks` policy.
|
||||
- **AC-OFFICE-BUDGET-003.3:** The built-in default shall apply to unattended
|
||||
runs only, and shall never block an attended run, including after an operator
|
||||
has changed its limit.
|
||||
- **AC-OFFICE-BUDGET-003.4:** A workspace-scoped `daily` policy shall supersede
|
||||
the built-in default for that workspace, replacing it rather than being
|
||||
evaluated in addition to it, **only when that policy's action is
|
||||
`pause_agent` or `block_new_tasks`**. A workspace-scoped `daily` policy whose
|
||||
action is `notify_only` shall not supersede the built-in default, and both
|
||||
shall be evaluated: the operator's policy notifies and the built-in default
|
||||
still blocks. A policy that never blocks shall not remove the shipped
|
||||
ceiling. A policy skipped under `AC-OFFICE-BUDGET-002.5`,
|
||||
`AC-OFFICE-BUDGET-002.11` or `AC-OFFICE-BUDGET-002.14` shall not supersede the
|
||||
built-in default either: a policy that is not evaluated cannot stand in for the
|
||||
ceiling it displaces, so a malformed row restores the built-in ceiling rather
|
||||
than removing every bound. Nor shall a run deferred or failed under
|
||||
`AC-OFFICE-BUDGET-006.1`, or cancelled under `AC-OFFICE-BUDGET-006.7`, reach
|
||||
this gate at all — an admission decision that
|
||||
could not be completed does not become a decision that the default did not
|
||||
apply.
|
||||
- **AC-OFFICE-BUDGET-003.5:** The built-in default's limit shall be readable and
|
||||
writable by an operator through the same surface that manages budget
|
||||
policies, and its current effective value shall be visible there without
|
||||
inspecting the database.
|
||||
- **AC-OFFICE-BUDGET-003.6:** When the built-in default blocks a run, the
|
||||
activity entry shall state that the ceiling was the built-in default and not
|
||||
an operator-created policy.
|
||||
- **AC-OFFICE-BUDGET-003.7:** Writing the built-in default's limit under
|
||||
`AC-OFFICE-BUDGET-003.5` shall update a single durable per-workspace setting
|
||||
addressed by a stable identifier, and shall not create, update, or delete any
|
||||
row in `office_budget_policies`. The value shall not appear in the policy
|
||||
list API's results, and the written value shall remain the built-in default:
|
||||
it shall stay unattended-only under `AC-OFFICE-BUDGET-003.3` and shall
|
||||
continue to be reported as the built-in default under
|
||||
`AC-OFFICE-BUDGET-003.6`. Editing the limit shall not cause the default to be
|
||||
superseded under `AC-OFFICE-BUDGET-003.4`.
|
||||
- **AC-OFFICE-BUDGET-003.8:** When an operator writes a built-in default limit
|
||||
less than or equal to zero, the system shall reject the write with a
|
||||
validation error and leave the previous effective value in force.
|
||||
- **AC-OFFICE-BUDGET-003.9:** When no operator has written a limit for a
|
||||
workspace, that workspace's effective built-in default shall be the value in
|
||||
`AC-OFFICE-BUDGET-003.2`. Reading the effective value shall return a limit
|
||||
for every workspace, and shall never report the ceiling as absent.
|
||||
- **AC-OFFICE-BUDGET-003.10:** When two operators write the built-in default's
|
||||
limit for the same workspace concurrently, the last write ordered by the
|
||||
setting's own commit shall be the effective value, and no write shall leave
|
||||
the workspace with no effective limit.
|
||||
|
||||
- **AC-OFFICE-BUDGET-003.11:** The built-in default shall be evaluated by the
|
||||
same criteria as a workspace-scoped `daily` policy whose action is
|
||||
`block_new_tasks`, with its effective limit standing in for the policy limit
|
||||
wherever those criteria name one. In particular the measurement-integrity
|
||||
criteria apply to it: its window is `daily` under
|
||||
`AC-OFFICE-BUDGET-002.1`, its spend is priced spend under
|
||||
`AC-OFFICE-BUDGET-004.1`, and a pricing-degraded window blocks an unattended
|
||||
run against it under `AC-OFFICE-BUDGET-004.3` and carries
|
||||
`AC-OFFICE-BUDGET-005.7`'s outcome. Without this, a fresh install — whose
|
||||
only ceiling is the built-in default — would never test for pricing
|
||||
degradation at all, and measurement integrity would not in fact be a
|
||||
precondition for shipping the default.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Turning the ceiling off entirely.** There is no "disable" switch. An
|
||||
operator who wants no effective unattended bound raises the limit, or creates
|
||||
a workspace-scoped `daily` policy with a blocking action and a limit high
|
||||
enough not to bind, which supersedes the default under
|
||||
`AC-OFFICE-BUDGET-003.4`. Named so the absence of an off switch is a decision
|
||||
rather than an omission.
|
||||
- **Per-run, per-routine, per-agent and per-project defaults.** The built-in
|
||||
default is per workspace per UTC day only. Operator policies already carry
|
||||
`agent` and `project` scopes; nothing here ships a default for them.
|
||||
- **Changing the default's value per install, per profile, or per environment
|
||||
variable.** The shipped value is a constant, overridable only per workspace
|
||||
through `AC-OFFICE-BUDGET-003.5`.
|
||||
- **Notifying an operator that the built-in default is in force.**
|
||||
`AC-OFFICE-BUDGET-003.6` requires attribution on a block; nothing here
|
||||
announces the ceiling before it first binds.
|
||||
- **Retention or pruning of the activity entries this capability writes.**
|
||||
@@ -0,0 +1,316 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
created: 2026-09-06
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Pre-Launch Budget Enforcement Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
[Office: Cost Tracking & Budget Management](costs.md) establishes that budget
|
||||
policies exist and that `notify_only`, `pause_agent` and `block_new_tasks` are
|
||||
their actions. It does not say what happens when the mechanism itself is absent,
|
||||
broken, or measuring the wrong window. All three currently resolve to "launch
|
||||
the agent anyway" — no evaluator wired returns allowed, an evaluator error
|
||||
returns allowed behind an explicit `// fail-open on error` comment, and
|
||||
`office_budget_policies` holds zero rows on the reference install — so an Office
|
||||
run has no spend ceiling under any circumstance.
|
||||
|
||||
Fail-open is right while a human is watching a run start: a transient fault
|
||||
should not block work somebody is waiting on. That does not extend to an
|
||||
unattended schedule. A `*/5` routine that fails open on an evaluator error is a
|
||||
loop with no upper bound on cost, running while nobody is looking, whose only
|
||||
feedback arrives on a bill.
|
||||
|
||||
That argument survives here in one place only. An evaluator that is entirely
|
||||
**absent** is a deployment fact no run can change, so an attended run launches
|
||||
against it (`AC-OFFICE-BUDGET-001.6`). An evaluator that **errors** is not: the
|
||||
error may clear, so every run defers and retries regardless of provenance
|
||||
(`AC-OFFICE-BUDGET-001.3`), and a fault outliving the retry budget fails the run
|
||||
rather than launching it, again regardless of provenance
|
||||
(`AC-OFFICE-BUDGET-001.4`). Deferring is what keeps a transient fault from
|
||||
blocking attended work; this spec does not fail open on an evaluator error for
|
||||
anybody.
|
||||
|
||||
This capability gives the unattended loop a ceiling enforced **before** launch
|
||||
and makes the inert states observable instead of silent. Office owns the
|
||||
contract because the states are defined by Office primitives: the run queue,
|
||||
reason, outcome and cost ledger. It bounds spend; it does not price models,
|
||||
change how cost events are produced, or recover an overspent workspace.
|
||||
|
||||
The capability spans six documents. This one owns the admission decision;
|
||||
[Run Provenance Classification](budget-run-provenance.md) the attended/
|
||||
unattended split every gate here reads; [Budget Admission
|
||||
Integrity](budget-admission-integrity.md) that the decision sees every
|
||||
applicable policy and changes nothing on its way to one; [Built-In Default Spend
|
||||
Ceiling](budget-default-ceiling.md) the bound that ships enabled; [Budget
|
||||
Measurement Integrity](budget-measurement-integrity.md) the number the ceiling
|
||||
is compared against, a precondition for both; and [Budget Enforcement
|
||||
Observability](budget-observability.md) which state fired.
|
||||
|
||||
## Prior art
|
||||
|
||||
**Receipt, internal wiki leg: NOT RUN, tooling unavailable.** Config resolved via
|
||||
`@henry` to `OBSIDIAN_VAULT_PATH=/Users/henry/Documents/henry/wiki`,
|
||||
`QMD_WIKI_COLLECTION=wiki`. Every read of that path returns `EPERM` (macOS TCC on
|
||||
`~/Documents`), confirmed two ways: `index.md` and `hot.md` EPERM while a
|
||||
nonexistent sibling returns not-found, so the vault is present and the denial is
|
||||
access control. No `qmd`, `obsidian-wiki` or `obsidian-cli` on PATH, no QMD MCP
|
||||
tool exposed. Re-run before treating this spec as settled: a recorded standing
|
||||
position on fail-open gates would outrank the reasoning here.
|
||||
|
||||
**Receipt, vendor leg: SUBSTITUTED.** `saas-kb` and its `search_fsm_docs` are not
|
||||
exposed in this session, so the `ai_sdlc` slice could not be queried; a public web
|
||||
search ran instead. Vendor claims, not evidence. Self-hosted **OpenHands** ships
|
||||
no built-in hard cost cap while its cloud product offers exactly the scheduled
|
||||
runs this spec is about; **Devin** bills opaque ACU consumption with no published
|
||||
pre-launch ceiling; provider caps are reported as advisory or too coarse to catch
|
||||
a loop running for hours. The recurring practitioner finding is that
|
||||
observability is not enforcement. One credible **dissenting** view holds
|
||||
monitoring should precede hard caps, since a cap can stop a high-priority
|
||||
workflow midstream — which is why the [built-in
|
||||
default](budget-default-ceiling.md) gates unattended runs only.
|
||||
|
||||
**Receipt, in-repo prior art: READ.** `shared.IsPeriodicTasklessWake`
|
||||
(`office/shared/runreasons.go`) already classifies provenance from `runs.reason`
|
||||
with a deliberate safe default for the ambiguous legacy literal; this spec reuses
|
||||
its shape and inverts its polarity, per the glossary's warning. [Office Stall
|
||||
Visibility](stall-visibility.md) sets the precedent for a detect-only safety
|
||||
capability. The Office run-outcome vocabulary
|
||||
([task-delivery-ledger](../../task-delivery-ledger/spec.md)) already gives each
|
||||
terminal shape a distinct `runs.outcome`, including `budget_blocked` — so this
|
||||
spec extends that vocabulary rather than establishing it, correcting the
|
||||
originating card's claim that the shape is not yet distinguishable.
|
||||
|
||||
**What we are doing differently.** Every vendor position found is either "no cap"
|
||||
or "opaque cap". This spec makes the ceiling explicit, pins its window and
|
||||
currency, ships it enabled for the unattended path only, and makes each inert
|
||||
state individually observable rather than collapsed into one boolean.
|
||||
|
||||
## Terminology
|
||||
|
||||
This capability's shared vocabulary — *run provenance*, *attended run*,
|
||||
*unattended run*, *subcent*, *priced spend*, *unpriced event*, *pricing-degraded
|
||||
window*, *evaluator fault*, *evaluation window*, *admission gate*, *applicable
|
||||
policy*, and the polarity warning about `IsPeriodicTasklessWake` — is defined
|
||||
once in the [Office glossary](../glossary.md) under **Budget enforcement**, and
|
||||
is normative for every document of this capability.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-OFFICE-BUDGET-001: Unattended runs have a pre-launch spend ceiling
|
||||
|
||||
**Intent:** Remove the fail-open paths so that no Office run launches without a
|
||||
ceiling having been evaluated, while keeping a *transient* evaluator fault from
|
||||
blocking work a person is waiting on — without letting a persistent one launch
|
||||
an unbounded run.
|
||||
|
||||
**User story:** As an operator running Office unattended, I want a schedule to
|
||||
stop launching when it has spent its ceiling or when the ceiling cannot be
|
||||
evaluated, so that a runaway loop costs a bounded amount rather than an
|
||||
unbounded one.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-001.1:** The provenance every criterion below relies on
|
||||
shall be the one `REQ-OFFICE-BUDGET-007` in [Run Provenance
|
||||
Classification](budget-run-provenance.md) produces, computed once before any
|
||||
policy is read. No gate in this document shall recompute or revise it, so two
|
||||
gates evaluating the same run cannot disagree about whether it is attended.
|
||||
- **AC-OFFICE-BUDGET-001.2:** Wherever this document says *attended* or
|
||||
*unattended* it means exactly `AC-OFFICE-BUDGET-007.2`'s classification of the
|
||||
run's reason, including that criterion's rule that an unrecognized value is
|
||||
unattended. No criterion here shall introduce a third state, and none shall
|
||||
treat an unclassifiable run as exempt from a gate.
|
||||
- **AC-OFFICE-BUDGET-001.3:** When the evaluator reports an error, the system
|
||||
shall not launch the agent, shall release any task checkout the run holds,
|
||||
and shall schedule the run for retry, for both attended and unattended runs.
|
||||
- **AC-OFFICE-BUDGET-001.4:** When a run scheduled for retry under
|
||||
`AC-OFFICE-BUDGET-001.3` has already reached `MaxRetryCount`, the system
|
||||
shall fail the run and record an operator-visible activity entry naming the
|
||||
evaluator error.
|
||||
- **AC-OFFICE-BUDGET-001.5:** When no budget evaluator is wired and the run is
|
||||
unattended, the system shall not launch the agent, shall cancel the run rather
|
||||
than retry or fail it, and shall record an operator-visible activity entry
|
||||
stating that budget enforcement is unavailable. An absent evaluator is a
|
||||
deployment state and not a transient fault: it cannot resolve without an
|
||||
operator changing the deployment, so retrying under
|
||||
`AC-OFFICE-BUDGET-001.3` would spend the run's whole retry budget on a
|
||||
condition no retry can clear. A cancelled run shall not re-enter the queue, so
|
||||
the entries this criterion writes are bounded by the number of runs queued
|
||||
rather than by scheduler ticks.
|
||||
- **AC-OFFICE-BUDGET-001.6:** When no budget evaluator is wired and the run is
|
||||
attended, the system shall launch the agent.
|
||||
- **AC-OFFICE-BUDGET-001.7:** When an applicable policy's action is
|
||||
`pause_agent` or `block_new_tasks` and priced spend in its evaluation window
|
||||
is greater than or equal to its limit, the system shall not launch the agent
|
||||
and shall finish the run with outcome `budget_blocked`.
|
||||
- **AC-OFFICE-BUDGET-001.8:** When an applicable policy's action is
|
||||
`notify_only`, the system shall launch the agent regardless of that policy's
|
||||
spend, for both attended and unattended runs, **except where
|
||||
`AC-OFFICE-BUDGET-004.3` in
|
||||
[budget-measurement-integrity.md](budget-measurement-integrity.md) blocks the
|
||||
run**. A `notify_only` action is a statement about a known spend figure; a
|
||||
pricing-degraded window has no trustworthy figure for it to be a statement
|
||||
about, so `notify_only` does not extend to that case.
|
||||
- **AC-OFFICE-BUDGET-001.9:** When more than one policy applies, the system
|
||||
shall evaluate policies ordered by `created_at` ascending, tie-broken by
|
||||
`id` ascending, and shall block on the first policy that satisfies
|
||||
`AC-OFFICE-BUDGET-001.7` or `AC-OFFICE-BUDGET-004.3`. Every applicable policy
|
||||
shall be evaluated against one captured evaluation instant, so that two
|
||||
policies in the same run cannot observe different windows. Gate 5 of
|
||||
`AC-OFFICE-BUDGET-001.14` shall evaluate the built-in default against that
|
||||
same instant, so a policy and the default cannot fall on opposite sides of a
|
||||
UTC midnight within one run. This ordering selects which policy *decides*; it
|
||||
never limits which policies are *evaluated*. Every applicable policy shall
|
||||
have both its limit test and its pricing-degradation determination completed
|
||||
before this ordering selects one, per `AC-OFFICE-BUDGET-006.1`, so blocking on
|
||||
the first such policy cannot leave a later one unevaluated. The rule is
|
||||
internal to gate 4: the gate sequence of `AC-OFFICE-BUDGET-001.14` still stops
|
||||
at the first gate yielding a non-launch decision.
|
||||
- **AC-OFFICE-BUDGET-001.10:** When two runs are evaluated concurrently against
|
||||
the same policy, each shall observe the spend committed at its own evaluation
|
||||
instant; the check is an admission test and not a reservation, so the ceiling
|
||||
can be exceeded by the cost of the runs already in flight when it was
|
||||
crossed. The system shall not hold a lock across launch to prevent this.
|
||||
- **AC-OFFICE-BUDGET-001.11:** When a run is blocked or deferred by any
|
||||
criterion in this capability, the system shall not have launched an agent
|
||||
process, minted a runtime token, or assembled a prompt for that run.
|
||||
- **AC-OFFICE-BUDGET-001.12:** When a run is blocked or deferred by any
|
||||
criterion in this capability — including a block by
|
||||
`AC-OFFICE-BUDGET-004.3` or by the built-in default — the system shall
|
||||
release the task checkout that run holds, scoped to that run as its owner,
|
||||
before the run reaches its terminal or retry-scheduled state. A run that
|
||||
never held a checkout shall not clear another run's checkout.
|
||||
- **AC-OFFICE-BUDGET-001.13:** A run carries no workspace identifier of its
|
||||
own; its workspace is that of the agent instance the run names. Resolving the
|
||||
workspace therefore means resolving that agent instance, and this criterion
|
||||
constrains the disposition of that resolution wherever it already happens
|
||||
rather than adding a second one. When the workspace cannot be resolved, the
|
||||
system shall not launch the agent, for both attended and unattended runs. An
|
||||
unresolvable workspace shall not be evaluated as a workspace with no policies
|
||||
and no spend, and shall not change the run's provenance. The two ways
|
||||
resolution can fail have different dispositions. When the lookup returns an
|
||||
error, the run shall be deferred and retried on the same terms as an evaluator
|
||||
fault (`AC-OFFICE-BUDGET-001.3`, `AC-OFFICE-BUDGET-001.16`,
|
||||
`AC-OFFICE-BUDGET-001.18`, and at `MaxRetryCount`
|
||||
`AC-OFFICE-BUDGET-006.4`), an I/O failure being transient. When the lookup
|
||||
succeeds and yields no agent instance, or yields one carrying no workspace
|
||||
identifier, the run shall be cancelled rather than retried or failed, an
|
||||
orphaned run having no ceiling that could ever be evaluated. Each cancellation
|
||||
shall record its own operator-visible activity entry, and a cancelled run shall
|
||||
not re-enter the queue. Neither disposition shall queue a run for any other
|
||||
agent, per `AC-OFFICE-BUDGET-001.17`.
|
||||
- **AC-OFFICE-BUDGET-001.14:** The admission gates shall be evaluated in this
|
||||
order, and the first gate that yields a non-launch decision shall determine
|
||||
the run's disposition, with no later gate evaluated: (1) workspace resolution
|
||||
(`AC-OFFICE-BUDGET-001.13`); (2) evaluator presence
|
||||
(`AC-OFFICE-BUDGET-001.5`, `AC-OFFICE-BUDGET-001.6`); (3) evaluator
|
||||
invocation (`AC-OFFICE-BUDGET-001.3`); (4) applicable policies in
|
||||
`AC-OFFICE-BUDGET-001.9` order, each tested for limit
|
||||
(`AC-OFFICE-BUDGET-001.7`) then for pricing degradation
|
||||
(`AC-OFFICE-BUDGET-004.3`); (5) the built-in default
|
||||
(`AC-OFFICE-BUDGET-003.1`), tested for limit then for pricing degradation in
|
||||
the same order as gate 4, per `AC-OFFICE-BUDGET-003.11`. A run that reaches
|
||||
the end of the sequence without a non-launch decision shall launch.
|
||||
This ordering is ordinal among *these* gates only: it does not reorder the
|
||||
checks Office already performs before launch and this capability does not
|
||||
govern, and gate 1 constrains the disposition of the workspace resolution
|
||||
wherever that resolution already occurs rather than requiring a second one.
|
||||
The run's project identifier is resolved at the start of gate 4, after gate 3
|
||||
has succeeded, per `AC-OFFICE-BUDGET-006.7`.
|
||||
"Tested for limit then for pricing degradation" at gates 4 and 5 fixes which
|
||||
criterion decides the disposition, not what gets computed: the
|
||||
pricing-degradation determination of `AC-OFFICE-BUDGET-004.2` shall be made for
|
||||
every policy this sequence evaluates, including one whose limit test has
|
||||
already decided to block, because `AC-OFFICE-BUDGET-004.6` requires the
|
||||
activity entry carry it in exactly that case.
|
||||
- **AC-OFFICE-BUDGET-001.15:** A policy applies to a run when its scope matches
|
||||
that run: a `workspace`-scoped policy applies to every run in its workspace;
|
||||
an `agent`-scoped policy applies when its `scope_id` equals the run's agent
|
||||
instance identifier; a `project`-scoped policy applies when its `scope_id`
|
||||
equals the run's project identifier. When the run carries no project
|
||||
identifier, no `project`-scoped policy applies to it; when it carries no
|
||||
agent instance identifier, no `agent`-scoped policy applies to it. A policy
|
||||
shall never apply by both identifiers being empty. A failure to *determine*
|
||||
either identifier is not the same as the run lacking it: for the agent
|
||||
instance see `AC-OFFICE-BUDGET-001.13`, for the project
|
||||
`AC-OFFICE-BUDGET-006.3`.
|
||||
- **AC-OFFICE-BUDGET-001.16:** A deferral under `AC-OFFICE-BUDGET-001.3` shall
|
||||
increment the same `runs.retry_count` the run's other retry classes use, so
|
||||
that `MaxRetryCount` bounds a run's total retries across all causes rather
|
||||
than granting evaluator faults their own budget, and shall schedule the retry
|
||||
no sooner than the first delay in the existing retry backoff schedule. The
|
||||
system shall not requeue a deferred run within the same scheduler tick.
|
||||
- **AC-OFFICE-BUDGET-001.17:** Failing a run under `AC-OFFICE-BUDGET-001.4`
|
||||
shall not queue any new run, and in particular shall not queue an escalation
|
||||
run for another agent. A broken evaluator shall not cause an agent launch by
|
||||
any path.
|
||||
- **AC-OFFICE-BUDGET-001.18:** When a run deferred under
|
||||
`AC-OFFICE-BUDGET-001.3` is too old to retry under the existing retry
|
||||
staleness bound, the system shall cancel it rather than retry or fail it, and
|
||||
shall record an operator-visible activity entry naming budget deferral as the
|
||||
cause of the cancellation.
|
||||
|
||||
|
||||
### Companion requirements
|
||||
|
||||
`REQ-OFFICE-BUDGET-005` (each state individually observable) is specified in
|
||||
[Budget Enforcement Observability](budget-observability.md), and
|
||||
`REQ-OFFICE-BUDGET-007` (provenance is a total function of the run's reason) in
|
||||
[Run Provenance Classification](budget-run-provenance.md), which
|
||||
`AC-OFFICE-BUDGET-001.1` and `AC-OFFICE-BUDGET-001.2` bind these gates to.
|
||||
`REQ-OFFICE-BUDGET-006` (the admission decision is complete and inert) is
|
||||
specified in [Budget Admission Integrity](budget-admission-integrity.md) and
|
||||
constrains the gates above: a partially evaluated policy set is an evaluator
|
||||
fault (`AC-OFFICE-BUDGET-006.1`), and reaching any decision here writes no alert
|
||||
entry and changes no agent's status (`AC-OFFICE-BUDGET-006.2`).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Reserving budget across concurrent launches.** `AC-OFFICE-BUDGET-001.10`
|
||||
deliberately admits overshoot bounded by in-flight concurrency; a true
|
||||
reservation needs a durable counter decremented at launch and reconciled at
|
||||
completion. Named so the overshoot is a decision, not an omission.
|
||||
- **Duplicate delivery of one run row to two consumers.** That single-consumer
|
||||
contract is the existing run-claim mechanism's. `AC-OFFICE-BUDGET-001.10`
|
||||
covers two *different* runs, not one run twice.
|
||||
- **Exactly-once delivery of activity entries and counters.** Every Office expvar
|
||||
counter is best-effort; a crash between a block and its increment loses it and
|
||||
does not reverse the block.
|
||||
- **Token-rate circuit breaking.** Watching consumption *rate* to catch a loop
|
||||
before it spends its ceiling is a complementary control; this spec bounds total
|
||||
spend per window only.
|
||||
- **Per-run and per-routine ceilings.** A per-window workspace ceiling bounds
|
||||
total cost, which is what NFR-5 requires; two more scopes would multiply the
|
||||
policy-precedence surface for no additional bound. A future requirement can add
|
||||
them within this evaluation model.
|
||||
- **Distinguishing an agent-caused event wake from a human-caused one.**
|
||||
`AC-OFFICE-BUDGET-007.2` classifies `task_comment`, `task_mentioned`,
|
||||
`task_children_completed` and `task_blockers_resolved` as attended, though an
|
||||
agent can cause all of them. Without a causation identifier the run row cannot
|
||||
tell them apart, and classifying them unattended would apply the built-in
|
||||
default to the bulk of ordinary event-driven work. A known gap; closing it
|
||||
depends on the causation-id work tracked as the runaway-chain card.
|
||||
- **Repairing the inbox "Mark fixed" action.** `manual_resume_after_failure` is
|
||||
attended because only an operator click queues it, but that click is separately
|
||||
broken: the agent stays paused and the requeue is rejected and swallowed as a
|
||||
warning, so a budget test passing on that reason is not evidence the recovery
|
||||
flow works. Card `497b1f63`; not fixed here.
|
||||
- **Unpausing an agent that a `pause_agent` policy paused.** The existing "mark
|
||||
fixed" path does not unpause. A separate known defect.
|
||||
- **Currencies other than United States dollars.** The storage unit is fixed at
|
||||
subcents of USD.
|
||||
- **Alert thresholds and the post-event evaluation path.**
|
||||
`alert_threshold_pct`, the `budget.alert` and `budget.exceeded` entries, and
|
||||
the agent-pause side effect of a post-event evaluation remain governed by
|
||||
[costs.md](costs.md). This spec constrains only the pre-launch admission
|
||||
decision, which `AC-OFFICE-BUDGET-006.2` requires produce none of them, so the
|
||||
two paths do not overlap.
|
||||
- **Retention or pruning of the activity entries this capability writes.**
|
||||
- **The system design.** The technical path, including where provenance
|
||||
classification lives and how the built-in default's setting is stored, belongs
|
||||
in a paired system-design document authored first.
|
||||
@@ -0,0 +1,277 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
created: 2026-09-06
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Budget Measurement Integrity Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies when a
|
||||
run is admitted against a spend ceiling. That contract is only as strong as the
|
||||
number the ceiling is compared against, and today that number is wrong in two
|
||||
independent ways: a policy's declared period does not select the window it
|
||||
names, and spend whose price is unknown is counted as zero. Both weaken
|
||||
enforcement silently, and both must be closed before the daily default ceiling
|
||||
in [Built-In Default Spend Ceiling](budget-default-ceiling.md) can ship.
|
||||
|
||||
This document owns the measurement. It does not change admission behavior,
|
||||
which stays in the companion documents, and it does not price models.
|
||||
|
||||
## Terminology
|
||||
|
||||
This document uses this capability's shared vocabulary, defined in the [Office
|
||||
glossary](../glossary.md) under **Budget enforcement** — in particular
|
||||
*subcent*, *priced spend*, *unpriced event*, *pricing-degraded window*,
|
||||
*attended run*, *unattended run*, and *evaluation window*.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-OFFICE-BUDGET-002: A policy means what it says
|
||||
|
||||
**Intent:** The period contract disagrees across four layers. The model enum
|
||||
declares `daily`, `monthly`, `yearly`, and both handlers validate against it
|
||||
(`office/costs/handler.go:144`, `:178`). The evaluator recognizes only
|
||||
`monthly` and returns the zero time otherwise, which its consumers read as "no
|
||||
filter", so a `daily` or `yearly` policy silently measures **lifetime** spend.
|
||||
On the reference install lifetime spend is 281,106,390 subcents against a
|
||||
busiest day of 23,813,441, so a daily policy would be permanently exceeded from
|
||||
creation, with no error and no log. Meanwhile the create form offers only
|
||||
`monthly` and `total`, and `total` is not in the enum, so choosing it returns
|
||||
HTTP 400 — the UI's second of two options cannot save. Backend tests
|
||||
(`office/costs/budgets_test.go:305`) exercise `total`, a value the product
|
||||
rejects. A shipped daily default is unsafe until this is closed.
|
||||
|
||||
The same requirement also covers policy *validity*, because a malformed policy
|
||||
disarms the ceiling by the same silent mechanism a wrong window does.
|
||||
`limit_subcents` carries no CHECK constraint, so a non-positive limit is
|
||||
storable, and an `agent`- or `project`-scoped policy with an empty `scope_id`
|
||||
matches every run whose corresponding identifier is also empty. Criteria
|
||||
`AC-OFFICE-BUDGET-002.6`, `-002.7` and `-002.11` close the write path and the
|
||||
rows stored before it closed. They belong to this requirement rather than a
|
||||
separate one because the failure mode is identical: a policy that appears to
|
||||
bound spend and does not.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-002.1:** When a policy's period is `daily`, its evaluation
|
||||
window shall start at the most recent UTC midnight at or before the
|
||||
evaluation instant.
|
||||
- **AC-OFFICE-BUDGET-002.2:** When a policy's period is `monthly`, its
|
||||
evaluation window shall start at 00:00:00 UTC on the first day of the
|
||||
evaluation instant's UTC month.
|
||||
- **AC-OFFICE-BUDGET-002.3:** When a policy's period is `yearly`, its evaluation
|
||||
window shall start at 00:00:00 UTC on 1 January of the evaluation instant's
|
||||
UTC year.
|
||||
- **AC-OFFICE-BUDGET-002.4:** Every evaluation window shall be computed in UTC,
|
||||
and shall not shift with the host's local time zone or its daylight-saving
|
||||
transitions.
|
||||
- **AC-OFFICE-BUDGET-002.5:** When a policy carries a period value the build
|
||||
does not recognize, the system shall not evaluate that policy as a lifetime
|
||||
window; it shall skip the policy and record an operator-visible activity
|
||||
entry naming the policy and the unrecognized value. A skipped policy shall
|
||||
not supersede the built-in default under `AC-OFFICE-BUDGET-003.4`, so
|
||||
skipping the only workspace-scoped `daily` policy restores the built-in
|
||||
ceiling rather than removing every bound.
|
||||
- **AC-OFFICE-BUDGET-002.6:** When a policy is created or updated with a limit
|
||||
less than or equal to zero, the system shall reject the write with a
|
||||
validation error rather than storing a policy that blocks every run.
|
||||
- **AC-OFFICE-BUDGET-002.7:** When a policy is created or updated with scope
|
||||
`agent` or `project` and an empty scope identifier, the system shall reject
|
||||
the write with a validation error, rather than storing a policy that matches
|
||||
every run whose corresponding identifier is also empty.
|
||||
- **AC-OFFICE-BUDGET-002.8:** `total` shall be a declared period value whose
|
||||
evaluation window is unbounded below, so that the lifetime window is
|
||||
selected by name rather than by falling through from an unrecognized value.
|
||||
- **AC-OFFICE-BUDGET-002.9:** Every period value the policy-management surface
|
||||
offers shall be accepted by the write API, and every declared period value
|
||||
shall be offered by that surface. Selecting any offered period and saving
|
||||
shall create a policy rather than return a validation error.
|
||||
- **AC-OFFICE-BUDGET-002.10:** Priced spend for an evaluation window shall be
|
||||
summed over cost events whose `office_cost_events.occurred_at` falls in that
|
||||
window, not over an insertion or ingestion timestamp, so that a delayed write
|
||||
is counted against the period in which the spend occurred. `occurred_at` is
|
||||
`NOT NULL` in the stored schema, so no null-timestamp branch is required. A
|
||||
cost event whose `occurred_at` is after the evaluation instant shall be
|
||||
excluded from that evaluation, so a clock-skewed or back-dated write cannot
|
||||
be counted against a window that has not begun.
|
||||
- **AC-OFFICE-BUDGET-002.11:** When a stored policy carries a limit less than or
|
||||
equal to zero, the system shall skip that policy and record an
|
||||
operator-visible activity entry naming the policy and its limit, in the same
|
||||
manner as `AC-OFFICE-BUDGET-002.5`, rather than blocking every run in the
|
||||
workspace. A policy skipped under this criterion shall not supersede the
|
||||
built-in default under `AC-OFFICE-BUDGET-003.4`, on the same reasoning
|
||||
`AC-OFFICE-BUDGET-002.5` states: a workspace-scoped `daily` policy carrying a
|
||||
blocking action and a non-positive limit would otherwise satisfy that
|
||||
supersession test while being skipped itself, leaving the workspace with no
|
||||
unattended ceiling at all — the exact failure this capability exists to
|
||||
remove. `AC-OFFICE-BUDGET-002.6` prevents new such rows; this criterion
|
||||
covers rows stored before it shipped.
|
||||
- **AC-OFFICE-BUDGET-002.12:** A test shall fail the build when the set of
|
||||
period values the policy-management surface offers differs from the set the
|
||||
write API declares. The test shall derive both sets by reading their
|
||||
respective sources rather than comparing against a list maintained alongside
|
||||
them, so that adding a period value on either side cannot silently reproduce
|
||||
the defect `AC-OFFICE-BUDGET-002.9` exists to fix. The check shall live in the
|
||||
backend Go test suite, so that `make -C apps/backend test` is its single gate
|
||||
rather than the parity being split across two pipelines and enforced by
|
||||
neither. It shall derive the declared set from the `BudgetPeriod` enum's own
|
||||
validation, and the offered set by reading the policy-creation form component
|
||||
under `apps/web/app/office/workspace/costs/`, and shall fail on any value
|
||||
present in one set and absent from the other.
|
||||
- **AC-OFFICE-BUDGET-002.13:** An activity entry required by
|
||||
`AC-OFFICE-BUDGET-002.5`, `AC-OFFICE-BUDGET-002.11` or
|
||||
`AC-OFFICE-BUDGET-002.14` shall be recorded at most once per policy per UTC
|
||||
day, rather than once per evaluation, so that a frequently scheduled routine
|
||||
re-evaluating one malformed policy does not write an unbounded stream of
|
||||
identical entries. The bound is per policy in aggregate, not per violated
|
||||
criterion: a policy violating more than one of those criteria shall produce one
|
||||
entry naming every violation detected, not one entry per violation. The bound
|
||||
is best-effort under concurrency, on the same reasoning as the counters — two
|
||||
runs evaluating the same policy concurrently may each observe that no entry
|
||||
exists yet and each write one, because `AC-OFFICE-BUDGET-001.10` forbids
|
||||
holding a lock across the decision. A duplicate entry is acceptable; this
|
||||
bound exists to stop a per-evaluation stream, not to guarantee uniqueness.
|
||||
- **AC-OFFICE-BUDGET-002.14:** When a stored policy carries a scope type the
|
||||
build does not recognize, an action the build does not recognize, or a scope
|
||||
of `agent` or `project` with an empty scope identifier, the system shall skip
|
||||
that policy and record an operator-visible activity entry naming the policy
|
||||
and the offending field, in the same manner as `AC-OFFICE-BUDGET-002.5`, and
|
||||
that policy shall not supersede the built-in default under
|
||||
`AC-OFFICE-BUDGET-003.4`. Skipping is the disposition for every stored policy
|
||||
the build cannot evaluate as written; together with `AC-OFFICE-BUDGET-002.5`
|
||||
and `AC-OFFICE-BUDGET-002.11` this makes that rule total over the policy row,
|
||||
so no malformed field is left to a code path that silently treats the policy
|
||||
as bounding nothing. For the empty-scope-identifier case this is the
|
||||
observable form of an exclusion `AC-OFFICE-BUDGET-001.15` already requires:
|
||||
the two agree that the policy does not bound the run, and this criterion adds
|
||||
the operator-visible record. `AC-OFFICE-BUDGET-002.6` and
|
||||
`AC-OFFICE-BUDGET-002.7` prevent new such rows; this criterion covers rows
|
||||
stored before they shipped and rows written by any path that bypasses the
|
||||
write API. A policy skipped here is not an unevaluated policy under
|
||||
`AC-OFFICE-BUDGET-006.1`, whose disposition could not be decided; this one's
|
||||
is decided here.
|
||||
|
||||
- **AC-OFFICE-BUDGET-002.15:** A policy's evaluation shall select the cost
|
||||
events it measures by scope, and the same selection shall serve both the
|
||||
priced-spend sum of `AC-OFFICE-BUDGET-004.1` and the pricing-degradation
|
||||
determination of `AC-OFFICE-BUDGET-004.2`. A `workspace`-scoped policy, and
|
||||
the built-in default under `AC-OFFICE-BUDGET-003.11`, shall select every cost
|
||||
event incurred by an agent instance belonging to that workspace — the same
|
||||
derivation `AC-OFFICE-BUDGET-001.13` uses to give a run its workspace.
|
||||
Selection shall not depend on the continued existence of the event's task: an
|
||||
event carrying no task identifier, or one whose task row has since been
|
||||
deleted, shall still count against its workspace. Otherwise deleting a task
|
||||
would retroactively lower spend already incurred, and a taskless periodic wake
|
||||
— the unattended shape this capability most exists to bound — would be exempt
|
||||
from the ceiling. An `agent`-scoped policy shall select events whose agent
|
||||
instance equals its `scope_id`. A `project`-scoped policy shall select events
|
||||
by the project recorded on the cost event itself when the spend occurred, not
|
||||
by the current project of the event's task, so that reparenting a task does
|
||||
not move historical spend between ceilings. Where an event cannot be
|
||||
attributed to the scope at all it is outside that policy's measurement and is
|
||||
not an unevaluated policy under `AC-OFFICE-BUDGET-006.1`, which concerns a
|
||||
policy the system could not evaluate rather than an event it did not select.
|
||||
|
||||
### REQ-OFFICE-BUDGET-004: Unpriced spend cannot silently raise the ceiling
|
||||
|
||||
**Intent:** When no price can be resolved for a turn's tokens, Office records
|
||||
the cost event with `cost_subcents = 0` and `cost_source = 'unpriced'`
|
||||
(`office/service/prompt_usage_cost.go`, the three `CostSourceUnpriced`
|
||||
branches of `resolveCostForUsage`), so tokens whose price is unknown are
|
||||
invisible to every sum the ceiling is computed from. Enforcement therefore
|
||||
weakens exactly when pricing breaks. Note that `cost_source` is the
|
||||
price-resolution flag and is deliberately distinct from `estimated`, which is a
|
||||
usage-authority flag. The two are independent, and the code is explicit about
|
||||
it: `resolveCostForUsage` copies `estimated` from the reported usage on every
|
||||
branch, the three unpriced branches included, so an unpriced row can carry
|
||||
`estimated` either way and neither flag implies the other. Degradation must
|
||||
therefore be determined from `cost_source`, never from `estimated`. The reference install
|
||||
shows this is real but rare — 3 unpriced events in 4,672 — which is why the
|
||||
rule below reacts to unpriced events only as the ceiling is approached, rather
|
||||
than blocking on a single stray row.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-004.1:** The ceiling comparison shall use priced spend, in
|
||||
subcents, denominated in United States dollars.
|
||||
- **AC-OFFICE-BUDGET-004.2:** When evaluating a policy, the system shall also
|
||||
determine whether the evaluation window is pricing-degraded, counting only
|
||||
events whose `cost_source` is `unpriced` and treating a NULL `cost_source` as
|
||||
priced. The determination shall not read the `estimated` column.
|
||||
- **AC-OFFICE-BUDGET-004.3:** When the evaluation window is pricing-degraded,
|
||||
priced spend is greater than or equal to 50 percent of the policy limit, and
|
||||
the run is unattended, the system shall not launch the agent. The 50 percent
|
||||
comparison shall be exact and shall not be computed by halving the limit with
|
||||
integer division: the threshold is reached when twice the priced spend is
|
||||
greater than or equal to the limit. Truncating an odd subcent limit would move
|
||||
the threshold down by half a subcent and fire the criterion early,
|
||||
deterministically and invisibly. This is the comparison every criterion in this
|
||||
document means by "50 percent of the policy limit". This criterion
|
||||
applies whatever the policy's action, and overrides
|
||||
`AC-OFFICE-BUDGET-001.8`'s admission of a `notify_only` policy: a
|
||||
`notify_only` action expresses a judgement about a known spend figure, and a
|
||||
pricing-degraded window has no trustworthy figure for it to be a judgement
|
||||
about.
|
||||
- **AC-OFFICE-BUDGET-004.4:** When the evaluation window is pricing-degraded and
|
||||
priced spend is below 50 percent of the policy limit, this criterion shall not
|
||||
block the run, and the system shall record that the window was
|
||||
pricing-degraded under `AC-OFFICE-BUDGET-004.8`. Whether the run launches is
|
||||
then determined by the remaining gates of `AC-OFFICE-BUDGET-001.14`: a later
|
||||
policy in `AC-OFFICE-BUDGET-001.9`'s order, or the built-in default at gate 5,
|
||||
may still block it.
|
||||
- **AC-OFFICE-BUDGET-004.5:** The system shall not substitute an assumed,
|
||||
averaged, or interpolated price for an unpriced event when computing spend.
|
||||
- **AC-OFFICE-BUDGET-004.6:** A pricing-degraded block shall be distinguishable
|
||||
from a limit-exceeded block by a queryable field on the activity entry, per
|
||||
`AC-OFFICE-BUDGET-005.3`. Where the blocked run's priced spend did not reach
|
||||
the policy limit, it shall additionally carry the distinct run outcome
|
||||
required by `AC-OFFICE-BUDGET-005.7`; where the limit was also reached, the
|
||||
outcome is `budget_blocked` and the degradation is carried by the activity
|
||||
entry alone.
|
||||
- **AC-OFFICE-BUDGET-004.7:** When the evaluation window is pricing-degraded,
|
||||
priced spend is greater than or equal to 50 percent of the policy limit, and
|
||||
the run is **attended**, this criterion shall not block the run, and the
|
||||
system shall record that the window was pricing-degraded under
|
||||
`AC-OFFICE-BUDGET-004.8`. Pricing degradation shall never block an attended
|
||||
run. Whether the run launches is determined by the remaining gates of
|
||||
`AC-OFFICE-BUDGET-001.14`; in particular a limit reached under
|
||||
`AC-OFFICE-BUDGET-001.7` still blocks the run at gate 4, which tests limit
|
||||
before degradation.
|
||||
|
||||
- **AC-OFFICE-BUDGET-004.8:** The record required by `AC-OFFICE-BUDGET-004.4`
|
||||
and `AC-OFFICE-BUDGET-004.7` shall be an operator-visible activity entry
|
||||
carrying the same queryable field `AC-OFFICE-BUDGET-005.3` uses to distinguish
|
||||
a pricing-degraded block, set to a value distinct from that block's, so an
|
||||
admitted degraded window and a blocked one cannot be confused by a query. One
|
||||
entry shall be written per policy whose window was pricing-degraded and which
|
||||
did not block, naming that policy identifier, or stating that the ceiling was
|
||||
the built-in default. It shall be recorded at most once per policy per UTC
|
||||
day, in the manner of `AC-OFFICE-BUDGET-002.13`, so that a frequently
|
||||
scheduled routine running in a persistently degraded window does not write an
|
||||
unbounded stream of identical entries.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Admission behavior.** Whether a run launches, defers, or is blocked is
|
||||
specified in [Office: Pre-Launch Budget Enforcement](budget-enforcement.md);
|
||||
the criteria here that stop a run do so by feeding that document's gates.
|
||||
- **Pricing lookup itself.** How a model's rate is resolved, and the
|
||||
`models.dev` cache behavior, remain governed by [costs.md](costs.md).
|
||||
- **Repairing the unpriced write path.** Nothing here changes how an unpriced
|
||||
cost event is recorded; `cost_subcents = 0` with `cost_source = 'unpriced'`
|
||||
remains the stored shape, and this document only stops that shape from
|
||||
silently raising a ceiling.
|
||||
- **Backfilling historical rows.** The reference install holds 1,135 cost
|
||||
events with a NULL `cost_source`, written before the column existed. They are
|
||||
treated as priced and are not re-derived.
|
||||
- **Migrating existing policies.** No requirement here rewrites a stored policy
|
||||
whose period is currently interpreted as lifetime, or whose limit is
|
||||
non-positive; the operator-visible entries in `AC-OFFICE-BUDGET-002.5` and
|
||||
`AC-OFFICE-BUDGET-002.11` are the migration signal.
|
||||
- **Making the 50 percent degradation threshold configurable.** It is a
|
||||
constant. A future requirement can make it a policy field within the same
|
||||
evaluation model.
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
created: 2026-09-06
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Budget Enforcement Observability Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies when a
|
||||
run is admitted against a spend ceiling, and can stop a run for several
|
||||
distinct reasons. This document owns making which reason fired legible to an
|
||||
operator. It does not change admission behavior.
|
||||
|
||||
The failure this capability exists to remove was silent. A ceiling that stops a
|
||||
loop without saying which of several things happened reproduces the same
|
||||
blindness one layer up.
|
||||
|
||||
## Terminology
|
||||
|
||||
This document uses this capability's shared vocabulary, defined in the [Office
|
||||
glossary](../glossary.md) under **Budget enforcement** — in particular *run
|
||||
provenance*, *attended run*, *unattended run*, *evaluator fault*,
|
||||
*pricing-degraded window*, and *admission gate*.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-OFFICE-BUDGET-005: Each inert or blocking state is individually observable
|
||||
|
||||
**Intent:** The failure this capability exists to remove was silent. A ceiling
|
||||
that stops a loop without saying which of several things happened reproduces
|
||||
the same blindness one layer up. `runs.outcome` already distinguishes
|
||||
`budget_blocked` from the other terminal shapes; the states this spec adds
|
||||
need the same treatment rather than being folded into it.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-005.1:** A run blocked because a policy limit or the
|
||||
built-in default's limit was reached shall carry outcome `budget_blocked`.
|
||||
That outcome shall mean the limit was actually reached, and no other state in
|
||||
this capability shall use it.
|
||||
- **AC-OFFICE-BUDGET-005.2:** A run deferred by an evaluator fault
|
||||
(`AC-OFFICE-BUDGET-001.3`) shall not carry outcome `budget_blocked`, because
|
||||
no ceiling was determined to have been reached.
|
||||
- **AC-OFFICE-BUDGET-005.3:** Each of the following shall be distinguishable
|
||||
from `budget_blocked` and from each other by a field on its activity entry
|
||||
that is queryable without parsing free text: a block because no evaluator was
|
||||
wired (`AC-OFFICE-BUDGET-001.5`); a deferral because the workspace lookup
|
||||
errored and a cancellation because the lookup yielded no workspace, which
|
||||
`AC-OFFICE-BUDGET-001.13` gives different dispositions and which shall
|
||||
therefore be distinguishable from each other and not collapsed into one
|
||||
unresolvable-workspace state; a deferral by evaluator fault
|
||||
(`AC-OFFICE-BUDGET-001.3`), distinguishable from the workspace-lookup deferral
|
||||
even though the two share a retry path; a cancellation of a stale deferral
|
||||
(`AC-OFFICE-BUDGET-001.18`); and a block by a pricing-degraded window
|
||||
(`AC-OFFICE-BUDGET-004.3`, in
|
||||
[budget-measurement-integrity.md](budget-measurement-integrity.md)). A
|
||||
queryable activity-entry field is the uniform mechanism; an outcome value is
|
||||
required only where `AC-OFFICE-BUDGET-005.7` names one.
|
||||
`AC-OFFICE-BUDGET-006.5` adds five further states to this list, on the same
|
||||
terms.
|
||||
- **AC-OFFICE-BUDGET-005.4:** The system shall expose counters, in the same
|
||||
`/debug/vars` surface as the existing Office metrics, for: runs blocked by
|
||||
limit, runs deferred by evaluator fault, runs blocked by absent evaluator,
|
||||
runs deferred by a workspace-lookup error, runs cancelled as having no
|
||||
resolvable workspace, runs cancelled as stale deferrals,
|
||||
runs blocked by pricing degradation, runs admitted against the built-in
|
||||
default, and runs admitted against a pricing-degraded window
|
||||
(`AC-OFFICE-BUDGET-004.8`). Each counter shall be labelled by run provenance,
|
||||
using the provenance `AC-OFFICE-BUDGET-007.1` produced. Each counter shall
|
||||
count runs, once per run, with one exception: every deferral counter shall
|
||||
count deferral *attempts*, matching `AC-OFFICE-BUDGET-005.6`'s
|
||||
one-entry-per-attempt rule, so a run deferred four times before failing
|
||||
increments it four times. Without that exception stated, the same run could be
|
||||
counted once or four times and neither reading would be wrong.
|
||||
The counter for runs admitted against a pricing-degraded window shall increment
|
||||
only for a run whose final disposition was launch, and not once per
|
||||
`AC-OFFICE-BUDGET-004.8` entry. That entry is written per non-blocking degraded
|
||||
policy, and a later policy in `AC-OFFICE-BUDGET-001.9`'s order — or the
|
||||
built-in default at gate 5 — may still block the run, so counting entries would
|
||||
report a blocked run as admitted.
|
||||
- **AC-OFFICE-BUDGET-005.5:** Every activity entry this capability writes that
|
||||
acted on a policy or on the built-in default shall name the policy identifier
|
||||
it acted on, or state explicitly that the ceiling was the built-in default.
|
||||
An entry written before any ceiling was determined — the evaluator-fault
|
||||
deferral, the absent-evaluator cancellation, both workspace-resolution
|
||||
outcomes of `AC-OFFICE-BUDGET-001.13`, the stale-deferral cancellation, the
|
||||
failed-project-lookup deferral (`AC-OFFICE-BUDGET-006.3`) and a deferral failed
|
||||
at `MaxRetryCount` under `AC-OFFICE-BUDGET-006.4`, and both cancellations of
|
||||
`AC-OFFICE-BUDGET-006.7` —
|
||||
shall instead state explicitly that no ceiling was determined, and shall not
|
||||
name a policy. The deferral an unevaluated policy raises
|
||||
(`AC-OFFICE-BUDGET-006.1`) is the single exception, and so is its failure at
|
||||
`MaxRetryCount`: no ceiling was determined in either, but the policy that could
|
||||
not be evaluated is known and shall be named, because it is the only pointer an
|
||||
operator has to the row to inspect.
|
||||
- **AC-OFFICE-BUDGET-005.6:** When the same run is deferred more than once —
|
||||
whether by repeated evaluator faults, by repeated workspace-lookup errors
|
||||
(`AC-OFFICE-BUDGET-001.13`), or by the faults `AC-OFFICE-BUDGET-006.1` and
|
||||
`AC-OFFICE-BUDGET-006.3` raise — the system shall record one activity entry per
|
||||
deferral attempt, each naming the attempt number and which cause produced it,
|
||||
and shall not coalesce them into a single entry. This rule covers every
|
||||
deferral this capability schedules, so no deferral cause is left to a builder's
|
||||
choice between one entry per attempt and one per run.
|
||||
- **AC-OFFICE-BUDGET-005.7:** A run blocked by `AC-OFFICE-BUDGET-004.3` whose
|
||||
priced spend did not reach the applicable limit shall carry the
|
||||
`runs.outcome` value `budget_unmeasurable`, reserved for a block caused by
|
||||
unmeasurable spend rather than by a limit being reached, and shall not carry
|
||||
`budget_blocked`.
|
||||
Adding that value extends the Office run-outcome vocabulary owned by
|
||||
[task-delivery-ledger](../../task-delivery-ledger/spec.md), whose enumeration
|
||||
shall be updated in the same change rather than gaining an undeclared value.
|
||||
Updating the enumeration alone is not sufficient: that document also states,
|
||||
unqualified, that a run blocked by the pre-execution budget check finishes
|
||||
with `budget_blocked`, both as an acceptance statement for the Office run
|
||||
outcome and as a row in its mapping table from the `checkBudget` code site.
|
||||
Both become false for a `budget_unmeasurable` block, and both remain live
|
||||
canon. Every statement in that document that maps a pre-execution budget block
|
||||
to `budget_blocked` shall be narrowed to the limit-reached case in the same
|
||||
change, so no reader of the ledger alone concludes that every budget block
|
||||
carries `budget_blocked`. The same applies to any statement in that document
|
||||
that fixes the *cardinality* of the enumeration rather than mapping a block to
|
||||
a value — it states that the writer writes one of five values on the finished
|
||||
path — which this addition also makes false, and which a change that updated
|
||||
only the enumeration and the mapping statements would leave stale.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Exactly-once delivery of activity entries and counters.** Every Office
|
||||
expvar counter is best-effort by construction; a crash between a block and
|
||||
its counter increment loses the increment and does not reverse the block.
|
||||
`AC-OFFICE-BUDGET-005.4` requires the counters exist and are labelled, not
|
||||
that they are transactional with the run's state change.
|
||||
- **A dashboard, alert, or digest over these counters and entries.** This
|
||||
document requires the states be individually queryable; presenting them is
|
||||
governed by [costs.md](costs.md) and the inbox surfaces.
|
||||
- **Retention or pruning of the activity entries this capability writes.**
|
||||
- **Renaming or restructuring the existing `budget_blocked` outcome or the
|
||||
`run_budget_blocked` activity entry.** `AC-OFFICE-BUDGET-005.1` constrains
|
||||
what they mean; it does not rename them.
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
created: 2026-09-06
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Run Provenance Classification Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) decides whether a
|
||||
run launches. Four of its criteria, and the whole of [Built-In Default Spend
|
||||
Ceiling](budget-default-ceiling.md), turn on whether the run is *attended* or
|
||||
*unattended*. This document owns that classification: what it reads, what it
|
||||
returns for every possible input, and the build-time test that stops a new run
|
||||
reason from silently changing a run's provenance.
|
||||
|
||||
It is separated from the admission decision because it is the decision's
|
||||
**input**, not one of its gates: classification happens once, before any policy
|
||||
is read, and no gate may revise it. Keeping it here also keeps the admission
|
||||
document inside its size limit, which three consecutive rounds of edits have
|
||||
pressed against.
|
||||
|
||||
## Terminology
|
||||
|
||||
This capability's shared vocabulary, including *run provenance*, *attended run*,
|
||||
*unattended run* and the polarity warning about `IsPeriodicTasklessWake`, is
|
||||
defined in the [Office glossary](../glossary.md) under **Budget enforcement**.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-OFFICE-BUDGET-007: A run's provenance is a total function of its reason
|
||||
|
||||
**Intent:** Every criterion that treats attended and unattended runs differently
|
||||
needs an answer for every run, including a run carrying a reason the build has
|
||||
never seen. A classifier with a gap would hand those runs to whichever branch the
|
||||
implementation happened to fall through to, which is how a safety gate acquires
|
||||
an unexamined default.
|
||||
|
||||
The safe default here is the opposite of the one the idle-skip gate uses on the
|
||||
same column, and that inversion is the single most likely implementation
|
||||
mistake; it is recorded as a warning in the glossary rather than left to be
|
||||
rediscovered.
|
||||
|
||||
**User story:** As an operator running Office unattended, I want a run's
|
||||
provenance decided by an explicit list rather than by a fallthrough, so that
|
||||
adding a wake reason cannot quietly exempt it from the ceiling.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-OFFICE-BUDGET-007.1:** When a run is dequeued for processing, the system
|
||||
shall classify its provenance as attended or unattended from `runs.reason`,
|
||||
before evaluating any policy. Classification is a total function of the
|
||||
reason string: it shall succeed for every value, and no later gate shall
|
||||
change the provenance it produced.
|
||||
- **AC-OFFICE-BUDGET-007.2:** The attended allowlist shall be exactly:
|
||||
`task_assigned`, `task_comment`, `task_review_requested`,
|
||||
`task_changes_requested`, `task_blockers_resolved`,
|
||||
`task_children_completed`, `approval_resolved`, `routine_dispatch_event`,
|
||||
`manual_resume_after_failure`, `task_mentioned`, `task_reopened`,
|
||||
`task_reopened_via_comment`, `task_unblocked`, `task_ready_to_close`,
|
||||
`stage_pending`, `stage_changes_requested`, and the legacy literals
|
||||
`review_started`, `approval_started`, `blockers_resolved`,
|
||||
`children_completed`. Every other value, **including a value the build does
|
||||
not recognize**, shall classify as unattended.
|
||||
- **AC-OFFICE-BUDGET-007.3:** A test shall fail the build when a run-reason
|
||||
string literal exists in the Office source that the provenance classifier
|
||||
places in neither the attended allowlist of `AC-OFFICE-BUDGET-007.2` nor the
|
||||
explicit unattended list of `AC-OFFICE-BUDGET-007.4`. The test shall derive
|
||||
its inventory by reading the source, not from a list of literals maintained
|
||||
alongside it, and shall fail on an unclassified literal at build time rather
|
||||
than on an unrecognized value at run time.
|
||||
**The inventory shall be derived from an enumerated set of declaration
|
||||
blocks, and never by matching constant identifiers.** Identifier matching
|
||||
cannot work here and shall not be reintroduced: a live run reason is declared
|
||||
today under three unrelated naming conventions — `RunReason*`, `WakeReason*`
|
||||
and `TaskCommentReason` — so no identifier pattern narrow enough to exclude
|
||||
non-run-reason constants also covers all three. The enumerated blocks shall
|
||||
be exactly: (a) the run-reason constant block in
|
||||
`internal/office/scheduler/run.go`; (b) both constant blocks in
|
||||
`internal/office/service/run.go`, the `RunReason*` block and the separate
|
||||
`legacyRunReason*` block; (c) the run-reason constant block in
|
||||
`internal/office/shared/runreasons.go`; (d) the `WakeReason*` constant block
|
||||
in `internal/office/routing/types.go`, which declares three of
|
||||
`AC-OFFICE-BUDGET-007.4`'s six unattended literals under a doc comment
|
||||
stating that its values must stay in sync with the scheduler constants;
|
||||
(e) the constant block in `internal/runs/commentkeys` declaring
|
||||
`TaskCommentReason`, a live run reason declared outside `internal/office`;
|
||||
(f) the `runReasonTaskAssigned` constant in
|
||||
`internal/office/onboarding`; and (g) the constant block in
|
||||
`internal/office/service/failure.go` declaring
|
||||
`RunReasonManualResumeAfterFailure`. Block (g) is in the same package as
|
||||
block (b) but a different file, so enumerating a package's run reasons by one
|
||||
file does not reach it. Each block shall be identified by package and
|
||||
declaration and never by line number. When an enumerated block cannot be
|
||||
located, because it was renamed, moved or deleted, the test shall fail rather
|
||||
than pass on the smaller inventory, so that a refactor cannot silently empty
|
||||
the net.
|
||||
**Within an enumerated block every constant is inventoried by default.** A
|
||||
constant in one of those blocks that is not a run reason shall be excluded
|
||||
only by being named in an exclusion list carried with the test, which today
|
||||
shall be exactly `shared.RoutineSourceCron`, `commentkeys.TaskCommentPrefix`,
|
||||
`commentkeys.EngineDispatchedValue`, `InboxKindAgentRunFailed`,
|
||||
`InboxKindAgentPausedAfterFails` and `autoPauseReasonPrefix`. The last three
|
||||
share block (g) with its one run reason; `InboxKindAgentRunFailed` is an inbox
|
||||
kind whose value reads exactly like a run reason, which is why exclusion is by
|
||||
name rather than by inferring intent from the value. Inclusion is the default
|
||||
so that a reason added to an existing block fails the build until somebody
|
||||
classifies it, which is the purpose of this criterion; exclusion is by name so
|
||||
that removing a literal from the inventory is a deliberate and reviewable act
|
||||
rather than a consequence of how it was spelled. A constant declared as an
|
||||
alias of another enumerated constant contributes no new literal.
|
||||
**A declaration block outside the enumeration is not covered**, which is the
|
||||
cost of enumerating rather than matching, and the test shall carry a comment
|
||||
saying so: a run reason declared in an unlisted block will not be caught, and
|
||||
extending the enumeration is part of adding such a block to the tree.
|
||||
`AC-OFFICE-BUDGET-007.2`'s unattended catch-all remains the runtime safe
|
||||
default for exactly that case.
|
||||
Membership shall be decided by exact string equality and never by substring,
|
||||
so that `task_reopened` is not conflated with `task_reopened_via_comment`,
|
||||
and a literal declared in more than one block shall count once. A literal
|
||||
appearing in both `AC-OFFICE-BUDGET-007.2`'s allowlist and
|
||||
`AC-OFFICE-BUDGET-007.4`'s list shall also fail the test, the two being
|
||||
disjoint by construction. This test exists so that adding a reason cannot
|
||||
silently change a run's provenance.
|
||||
- **AC-OFFICE-BUDGET-007.4:** The explicit unattended list
|
||||
`AC-OFFICE-BUDGET-007.3` tests against shall be exactly: `agent_error`,
|
||||
`budget_alert`, `heartbeat`, `routine_dispatch`, `routine_dispatch_cron`,
|
||||
`routine_trigger`. It shall be maintained as an enumeration in its own right
|
||||
and shall never be computed as the complement of `AC-OFFICE-BUDGET-007.2`'s
|
||||
allowlist. A derived list would make `AC-OFFICE-BUDGET-007.3`'s test a
|
||||
tautology that no newly added reason could ever fail, since every literal
|
||||
would be a member of one list or the other by construction — which would leave
|
||||
the build-time net this requirement exists to provide with nothing to catch.
|
||||
This list is a build-time artifact only. It does not narrow
|
||||
`AC-OFFICE-BUDGET-007.2`'s runtime rule, under which a value in neither list,
|
||||
including one the build has never seen, still classifies as unattended.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Distinguishing an agent-caused event wake from a human-caused one.** Named
|
||||
and reasoned about in [budget-enforcement.md](budget-enforcement.md)'s Out of
|
||||
scope; `AC-OFFICE-BUDGET-007.2`'s allowlist is what that exclusion constrains.
|
||||
- **Changing `IsPeriodicTasklessWake` or the idle-skip gate.** That classifier
|
||||
reads the same column with the opposite safe default and is left untouched.
|
||||
- **A causation identifier on the run row.** Provenance here is derived from
|
||||
`runs.reason` alone.
|
||||
@@ -0,0 +1,581 @@
|
||||
---
|
||||
status: draft
|
||||
system: office
|
||||
requirements:
|
||||
- REQ-OFFICE-BUDGET-001
|
||||
- REQ-OFFICE-BUDGET-002
|
||||
- REQ-OFFICE-BUDGET-003
|
||||
- REQ-OFFICE-BUDGET-004
|
||||
- REQ-OFFICE-BUDGET-005
|
||||
- REQ-OFFICE-BUDGET-006
|
||||
- REQ-OFFICE-BUDGET-007
|
||||
created: 2026-09-07
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Office: Pre-Launch Budget Enforcement System Design
|
||||
|
||||
## Purpose and boundaries
|
||||
|
||||
This design replaces the three fail-open paths named in
|
||||
[budget-enforcement.md](../requirements/budget-enforcement.md) with a five-gate
|
||||
admission decision that runs inside `SchedulerIntegration.processRun`
|
||||
(`internal/office/service/scheduler_integration.go`), immediately after task
|
||||
checkout and before executor resolution. It owns: run-provenance
|
||||
classification, the gate sequence and its dispositions, per-state activity
|
||||
entries and counters, measurement-window and pricing-degradation correctness,
|
||||
and a new durable per-workspace default-ceiling setting. It does not change the
|
||||
post-event evaluation path (`costs.CostService.EvaluateBudget`,
|
||||
`costs/budgets.go`), which continues to fire `budget.alert` / `budget.exceeded`
|
||||
and pause agents on its own schedule, unconstrained by this design.
|
||||
|
||||
Adjacent contracts used and not owned:
|
||||
|
||||
- `internal/office/service/retry.go` — `MaxRetryCount`, the backoff schedule,
|
||||
`isRetryStale`/`retryMaxAge`. Reused, not reimplemented.
|
||||
- `internal/office/service/scheduler_runs.go` — `FinishRun`, `FailRun`,
|
||||
`transitionRunTerminal`, `releaseTaskCheckoutForRun`.
|
||||
- `internal/office/service/activity.go` — `LogActivityWithRun`.
|
||||
- `internal/office/repository/sqlite/costs.go` — cost-event and
|
||||
budget-policy storage; extended, not replaced.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-OFFICE-BUDGET-007` | [Provenance classification](#provenance-classification) |
|
||||
| `REQ-OFFICE-BUDGET-001` | [The five-gate admission decision](#the-five-gate-admission-decision) |
|
||||
| `REQ-OFFICE-BUDGET-006` | [Two-phase policy evaluation](#two-phase-policy-evaluation), [Inertness](#inertness) |
|
||||
| `REQ-OFFICE-BUDGET-002` | [Measurement integrity](#measurement-integrity) |
|
||||
| `REQ-OFFICE-BUDGET-004` | [Pricing degradation](#pricing-degradation) |
|
||||
| `REQ-OFFICE-BUDGET-003` | [Built-in default ceiling](#built-in-default-ceiling) |
|
||||
| `REQ-OFFICE-BUDGET-005` | [Observability: activity entries and counters](#observability-activity-entries-and-counters) |
|
||||
|
||||
## Provenance classification
|
||||
|
||||
New file `internal/office/shared/runprovenance.go`, beside the existing
|
||||
`IsPeriodicTasklessWake` this design deliberately does not touch (per
|
||||
[budget-run-provenance.md](../requirements/budget-run-provenance.md)'s Out of
|
||||
scope and the glossary's polarity warning):
|
||||
|
||||
```go
|
||||
type RunProvenance int
|
||||
|
||||
const (
|
||||
RunProvenanceUnattended RunProvenance = iota
|
||||
RunProvenanceAttended
|
||||
)
|
||||
|
||||
func ClassifyRunProvenance(reason string) RunProvenance
|
||||
```
|
||||
|
||||
An unexported `map[string]struct{}` literal holds the 20-literal allowlist of
|
||||
`AC-OFFICE-BUDGET-007.2` verbatim (16 current + 4 legacy). `processRun` calls
|
||||
this exactly once, before gate 1, and threads the result through every gate
|
||||
via a small `admissionCtx` struct (see below) rather than recomputing it —
|
||||
satisfying `AC-OFFICE-BUDGET-001.1`'s "computed once, never revised".
|
||||
|
||||
### Build-time completeness test
|
||||
|
||||
`internal/office/shared/runprovenance_completeness_test.go`
|
||||
(`package shared_test`) implements `AC-OFFICE-BUDGET-007.3` using plain
|
||||
`go/parser`/`go/ast` per file, never a line-oriented regex — the X2 design
|
||||
note. This is an implementation-time refinement from the originally-planned
|
||||
`golang.org/x/tools/go/packages` + `go/types`: that combination is an
|
||||
unnecessary new direct dependency (currently only transitive in `go.sum`)
|
||||
and spawns `go list` subprocesses under the hood, which is a source of CI
|
||||
fragility this test doesn't need to accept. The AC's actual requirements —
|
||||
never regex/identifier-matching, fail hard on a missing block, an alias
|
||||
contributes no new literal — hold under the simpler approach without
|
||||
weakening what the test proves; see below for how alias handling differs.
|
||||
|
||||
For each of the seven blocks the test is hard-coded with **(file path
|
||||
relative to the test file via `runtime.Caller(0)`, anchor constant name)**:
|
||||
the anchor is one identifier already known to live in that block
|
||||
(`RunReasonTaskAssigned` for (a) in `scheduler/run.go`,
|
||||
`RunReasonTaskAssigned` for (b1) in `service/run.go`,
|
||||
`legacyRunReasonBlockersResolved` for (b2) in the same file,
|
||||
`RunReasonRoutineDispatch` for (c) in `shared/runreasons.go`,
|
||||
`WakeReasonHeartbeat` for (d) in `routing/types.go`, `TaskCommentReason` for
|
||||
(e) in `runs/commentkeys/commentkeys.go`, `runReasonTaskAssigned` for (f) in
|
||||
`onboarding/service.go`, `RunReasonManualResumeAfterFailure` for (g) in
|
||||
`service/failure.go`). For each anchor the test parses that one file with
|
||||
`go/parser` (`parser.ParseFile`, `SkipObjectResolution`), finds the
|
||||
top-level `*ast.GenDecl` with `Tok == token.CONST` containing a
|
||||
`*ast.ValueSpec` naming the anchor, and fails the test (not skips) when no
|
||||
such declaration exists — an enumerated block that was renamed, moved, or
|
||||
deleted must fail the build rather than silently shrink the inventory.
|
||||
Blocks (b1) and (b2) both resolve to `service/run.go`; naming the file per
|
||||
block (rather than per package) is also what disambiguates block (g), which
|
||||
shares a package with (b) but lives in a different file (`failure.go` vs
|
||||
`run.go`).
|
||||
|
||||
Once a block's `GenDecl` is located, every `ValueSpec` in it whose RHS is a
|
||||
string `*ast.BasicLit` contributes that literal (via `strconv.Unquote`); a
|
||||
`ValueSpec` whose RHS is anything else — a `*ast.SelectorExpr` or
|
||||
`*ast.Ident`, i.e. an alias like `RunReasonHeartbeat =
|
||||
shared.RunReasonHeartbeat` — is skipped rather than resolved. This is
|
||||
sufficient, not a weaker substitute for `go/types` resolution: an aliased
|
||||
constant's underlying literal is itself already covered by scanning its own
|
||||
enumerated block, so skipping the alias syntactically loses no literal from
|
||||
the union. Names present in the fixed six-entry exclusion list of
|
||||
`AC-OFFICE-BUDGET-007.3` are dropped before dedup/membership checks.
|
||||
|
||||
The test asserts, over the union of all seven blocks minus exclusions:
|
||||
every resolved string is a member of exactly one of two Go string sets
|
||||
declared directly in the test file — `attendedForTest` (the 20 literals of
|
||||
`AC-OFFICE-BUDGET-007.2`, kept textually identical to
|
||||
`shared.attendedRunReasons`, not derived from it, so the assertion is not
|
||||
checking the production map against itself) and `unattendedForTest` (the 6
|
||||
literals of `AC-OFFICE-BUDGET-007.4`, maintained as its own literal slice —
|
||||
never `allReasons - attendedForTest`, which is what makes the test capable of
|
||||
failing at all). A literal in both, or in neither, fails with the offending
|
||||
block and literal named in the message.
|
||||
|
||||
## The five-gate admission decision
|
||||
|
||||
New file `internal/office/service/budget_admission.go`. `processRun` calls
|
||||
one entry point immediately after `checkoutTask` succeeds, replacing today's
|
||||
`checkBudget`:
|
||||
|
||||
```go
|
||||
// admitRun runs AC-OFFICE-BUDGET-001.14's five gates in order and returns
|
||||
// true only when the run should launch. False means admitRun has already
|
||||
// driven the run to its terminal, retry, or cancelled disposition.
|
||||
func (si *SchedulerIntegration) admitRun(ctx context.Context, run *models.Run, taskID string) bool
|
||||
```
|
||||
|
||||
`admitRun` builds one `admissionCtx` carrying: the provenance
|
||||
(`shared.ClassifyRunProvenance(run.Reason)`, computed once), the captured
|
||||
evaluation instant (`time.Now().UTC()`, captured once — `AC-OFFICE-BUDGET-001.9`'s
|
||||
"one captured evaluation instant"), and threads it through gates 1-5. Each
|
||||
gate returns a small `(admit bool, terminal bool)` — `terminal=false` with
|
||||
`admit=false` means "deferred; caller must return", so a single `if !gate() {
|
||||
return false }` chain at the call site reproduces `AC-OFFICE-BUDGET-001.14`'s
|
||||
"first gate that yields a non-launch decision, no later gate evaluated"
|
||||
structurally, without a shared mutable "have we decided" flag that a future
|
||||
edit could reorder around.
|
||||
|
||||
1. **Workspace resolution** (`gateWorkspace`). Reuses the *existing*
|
||||
`GetAgentFromConfig` call already made earlier in `processRun` (per
|
||||
`AC-OFFICE-BUDGET-001.14`'s "constrains the disposition of the workspace
|
||||
resolution wherever it already occurs rather than requiring a second
|
||||
one") — `admitRun` receives the already-resolved `*models.AgentInstance`
|
||||
from its caller instead of re-fetching it. Per the **W2 human
|
||||
disposition**, `GetAgentFromConfig`'s error contract is not reshaped: an
|
||||
error from this call (already handled by `processRun` before `admitRun`
|
||||
is even reached — see [Control flow](#control-flow-inside-processrun))
|
||||
defers under the same terms as gate 3. `admitRun` itself only sees the
|
||||
success case and applies `AC-OFFICE-BUDGET-001.13`'s empty-workspace
|
||||
branch: `agent.WorkspaceID == ""` cancels (not deferred), writing the
|
||||
`run_budget_workspace_unresolvable` activity entry.
|
||||
2. **Evaluator presence** (`gateEvaluatorPresence`). `si.svc.budgetChecker ==
|
||||
nil`: unattended cancels
|
||||
(`run_budget_no_evaluator`), attended launches (falls through).
|
||||
3. **Evaluator invocation** (`gateEvaluatorInvocation`). Calls the evaluator
|
||||
once via the new richer method (below). A non-nil error is an evaluator
|
||||
fault: `admitBudgetDeferral` (shared with gates 4/5's fault paths, see
|
||||
below) defers under `AC-OFFICE-BUDGET-001.3`/`.16`, or fails at
|
||||
`MaxRetryCount` under `AC-OFFICE-BUDGET-001.4`, tagged
|
||||
`budgetDeferralCauseEvaluatorFault`.
|
||||
4. **Applicable policies** (`gateAppliedPolicies`). Resolves the run's
|
||||
project id per `AC-OFFICE-BUDGET-006.7` (see
|
||||
[Project resolution](#project-resolution)) then delegates the full
|
||||
evaluate-then-select to `costs.CostService.EvaluatePreLaunch` (see
|
||||
[Two-phase policy evaluation](#two-phase-policy-evaluation)).
|
||||
5. **Built-in default** (`gateBuiltInDefault`). Only reached for an
|
||||
unattended run whose gate 4 result says no workspace-scoped
|
||||
blocking-capable `daily` policy was evaluated (superseding it per
|
||||
`AC-OFFICE-BUDGET-003.4`). Evaluated by the same
|
||||
`costs.CostService.EvaluateDefaultCeiling` call gate 4 already used to
|
||||
decide supersession — see [Built-in default ceiling](#built-in-default-ceiling).
|
||||
|
||||
Steps 3-5 share one disposition helper,
|
||||
`(si *SchedulerIntegration) admitBudgetDeferral(ctx, run, cause
|
||||
budgetDeferralCause) bool`, which increments `run.RetryCount` through the
|
||||
*existing* `s.scheduleRetry`/`isRetryStale` machinery (so
|
||||
`AC-OFFICE-BUDGET-001.16`'s "same `runs.retry_count`" and "no sooner than the
|
||||
first backoff delay" hold for free) but, unlike `HandleRunFailure`, never
|
||||
calls `escalateFailure`. See [MaxRetryCount without
|
||||
escalation](#maxretrycount-without-escalation) for why.
|
||||
|
||||
### Control flow inside `processRun`
|
||||
|
||||
```text
|
||||
checkoutTask succeeds
|
||||
-> admitRun(ctx, run, taskID, agent) // replaces checkBudget
|
||||
gate1 workspace (reuses already-fetched agent)
|
||||
gate2 evaluator presence
|
||||
gate3 evaluator invocation
|
||||
gate4 applicable policies (resolves project id first, AC-006.7)
|
||||
gate5 built-in default
|
||||
-> (unchanged) resolveExecutorForRun, prepareAndLaunch
|
||||
```
|
||||
|
||||
`GetAgentFromConfig`'s pre-existing error branch in `processRun` (today:
|
||||
`HandleRunFailure`) is left as-is for the **non-budget** failure it already
|
||||
handles (agent truly not found); `AC-OFFICE-BUDGET-001.13`'s deferred-vs-cancel
|
||||
split for a workspace-lookup **error** specifically is therefore also
|
||||
satisfied by that existing branch, because `GetAgentFromConfig` returning an
|
||||
error already routes through `HandleRunFailure` → retry → escalate, which
|
||||
*is* the "same terms as an evaluator fault" `AC-OFFICE-BUDGET-001.13`
|
||||
requires — except escalation: `HandleRunFailure`'s existing
|
||||
`escalateFailure` call queues a CEO run, which
|
||||
[MaxRetryCount without escalation](#maxretrycount-without-escalation)
|
||||
requires this capability *not* do for a budget-caused permanent failure.
|
||||
Because a workspace-lookup error is indistinguishable, at this call site,
|
||||
from every other reason `GetAgentFromConfig` can fail (the W2 disposition:
|
||||
"do not reshape `GetAgentFromConfig`'s error contract"), this design accepts
|
||||
that a workspace lookup failing at `MaxRetryCount` escalates through the
|
||||
pre-existing generic path rather than the budget-specific
|
||||
non-escalating one — an intentional, narrow exception to
|
||||
`AC-OFFICE-BUDGET-001.17`'s "no path" language, justified by W2's own text
|
||||
("do not reshape... here") and recorded so a later reviewer does not
|
||||
"fix" it by widening `GetAgentFromConfig`'s contract mid-capability.
|
||||
|
||||
### Project resolution
|
||||
|
||||
`AC-OFFICE-BUDGET-006.7` needs four outcomes `extractProjectID` cannot
|
||||
produce (it collapses all four to `""`). New function in
|
||||
`budget_admission.go`:
|
||||
|
||||
```go
|
||||
type projectResolution int
|
||||
|
||||
const (
|
||||
projectResolutionNone projectResolution = iota // (a) no fault, no project
|
||||
projectResolutionFound
|
||||
projectResolutionLookupError // (b) defer, AC-006.3
|
||||
projectResolutionUnparseable // (c) cancel
|
||||
projectResolutionTaskNotFound // (d) cancel
|
||||
)
|
||||
|
||||
func (si *SchedulerIntegration) resolveRunProject(ctx context.Context, payload string) (projectID string, res projectResolution)
|
||||
```
|
||||
|
||||
Parses `payload` with `json.Unmarshal` directly (not `ParseRunPayload`, which
|
||||
swallows unmarshal errors — see budget-admission-integrity.md pinned
|
||||
evidence) into a small local struct with a `TaskID` field. A parse error is
|
||||
outcome (c). An empty/absent `task_id` is outcome (a). Otherwise calls
|
||||
`si.svc.repo.GetTaskBasicInfo`: an error is (b); `info == nil` is (d);
|
||||
`info.ProjectID` (possibly `""`, still (a)/(found)) otherwise.
|
||||
|
||||
## Two-phase policy evaluation
|
||||
|
||||
`costs.CostService` gains one new exported method,
|
||||
`EvaluatePreLaunch(ctx, workspaceID, agentInstanceID, projectID string, hasProject
|
||||
bool, at time.Time) (PreLaunchResult, error)`, in a new file
|
||||
`internal/office/costs/prelaunch.go`. It does **not** call the existing
|
||||
`CheckBudget`/`evaluatePolicy` (those remain the post-event path's, unchanged,
|
||||
per `AC-OFFICE-BUDGET-006.2`). It:
|
||||
|
||||
1. Lists policies for the workspace, filters to applicable ones per
|
||||
`AC-OFFICE-BUDGET-001.15` (workspace-scoped always applies; agent-scoped
|
||||
only when `scope_id == agentInstanceID`; project-scoped only when
|
||||
`hasProject && scope_id == projectID` — the caller's `hasProject` flag,
|
||||
from `resolveRunProject`, is what keeps a genuinely-project-less run from
|
||||
ever matching a project policy, distinct from a resolution failure that
|
||||
never reaches this call at all).
|
||||
2. For each applicable policy, validates it: period recognized (`daily`,
|
||||
`monthly`, `yearly`, `total`), `limit_subcents > 0`, `action_on_exceed`
|
||||
recognized, and (for `agent`/`project` scope) non-empty `scope_id`. A
|
||||
malformed policy is **skipped** — recorded via the caller's
|
||||
per-policy-per-day-deduped activity entry (see
|
||||
[Observability](#observability-activity-entries-and-counters)) — and
|
||||
excluded from both ordering and default-supersession. This is
|
||||
`AC-OFFICE-BUDGET-002.5`/`.11`/`.14`; it is explicitly not an "unevaluated
|
||||
policy".
|
||||
3. For each surviving (non-skipped) policy, computes priced spend and the
|
||||
pricing-degradation determination over the *same* scope-selected event set
|
||||
(`AC-OFFICE-BUDGET-002.15` — see [Measurement
|
||||
integrity](#measurement-integrity)) for its own period window ending at
|
||||
`at`. A query error here makes the **whole call** return a non-nil error —
|
||||
this is what makes `AC-OFFICE-BUDGET-006.1` (an unevaluated policy faults
|
||||
the run, not a partial admission) true by construction rather than by a
|
||||
caller remembering to check a length mismatch: there is no code path that
|
||||
returns a partial `[]PreLaunchPolicyResult` and `err == nil`.
|
||||
4. Orders the surviving policies by `(created_at ASC, id ASC)` and, in that
|
||||
order, finds the first whose limit test (`spend >= limit`, action ∈
|
||||
{`pause_agent`,`block_new_tasks`}) or degradation test (unattended,
|
||||
`2*spend >= limit`, degraded) fires — but **every** surviving policy's
|
||||
both tests are computed up front (step 3), so "first" is a selection over
|
||||
an already-fully-evaluated slice, never a short-circuiting loop.
|
||||
5. Returns `PreLaunchResult{Decision, Policies []PreLaunchPolicyResult,
|
||||
WorkspaceDailyBlockingSuperseded bool}` — the last field tells
|
||||
`gateBuiltInDefault` whether a workspace-scoped, non-skipped, blocking-capable
|
||||
(`pause_agent`/`block_new_tasks`) `daily` policy existed among the
|
||||
surviving set, independent of whether it fired
|
||||
(`AC-OFFICE-BUDGET-003.4` supersedes by existing, not by blocking).
|
||||
|
||||
`PreLaunchResult` never triggers `budget.alert`/`budget.exceeded` or an agent
|
||||
pause — it has no side effects at all, which is what makes
|
||||
`AC-OFFICE-BUDGET-006.2` (inertness) hold structurally: the method's only
|
||||
outputs are its two return values.
|
||||
|
||||
### Inertness
|
||||
|
||||
`EvaluatePreLaunch` and every function it calls are pure reads:
|
||||
`ListBudgetPolicies`, the two new spend-selection queries below, and
|
||||
(read-only) `GetWorkspaceBudgetDefault`. None of them writes
|
||||
`office_activity_log`, flips `agent_profiles.status`, or calls
|
||||
`UpdateAgentStatusFields`. `pauseAgentForBudget` and `logBudgetAlert`/
|
||||
`logBudgetExceeded` (existing `costs/budgets.go`) are not imported by
|
||||
`prelaunch.go`. Activity-entry writing for the *new* budget states happens
|
||||
one layer up, in `budget_admission.go`, after `EvaluatePreLaunch` returns —
|
||||
so a policy that decided the run's fate and a policy that merely degraded
|
||||
both get their entries from the caller, never from the evaluator itself.
|
||||
|
||||
## Measurement integrity
|
||||
|
||||
### Period fix
|
||||
|
||||
`costs/budgets.go`'s `periodCutoff` is replaced by a function on the new
|
||||
`prelaunch.go` (used by both the pre-launch path and, unchanged in
|
||||
signature, still callable from the existing post-event path if a later
|
||||
change wants it — not required here):
|
||||
|
||||
```go
|
||||
func windowStart(period models.BudgetPeriod, at time.Time) (start time.Time, ok bool)
|
||||
```
|
||||
|
||||
`daily` → most recent UTC midnight ≤ `at`; `monthly` → existing behavior;
|
||||
`yearly` → 1 Jan UTC of `at`'s year; `total` → `ok=true`,
|
||||
zero `time.Time` (unbounded below, `AC-OFFICE-BUDGET-002.8` — selected by
|
||||
name, not by falling through). An unrecognized period returns `ok=false`,
|
||||
which callers treat as "skip this policy" (`AC-OFFICE-BUDGET-002.5`), never
|
||||
as lifetime.
|
||||
|
||||
`models.BudgetPeriod` gains `BudgetPeriodTotal = "total"` in
|
||||
`internal/office/models/enums.go`, added to `Valid()`. `costs/handler.go`'s
|
||||
two existing `period.Valid()` checks (create/update) need no change — they
|
||||
already delegate to the enum.
|
||||
|
||||
### Scope-selection queries (`AC-OFFICE-BUDGET-002.15`)
|
||||
|
||||
Two new repository methods in `costs.go`, used by **both** the priced-spend
|
||||
sum and the degradation check (same `WHERE`, different `SELECT`), and by
|
||||
neither `SumCostsSince` nor `GetCostForProjectSince` — the **W4 human
|
||||
disposition** explicitly forbids reuse:
|
||||
|
||||
```go
|
||||
// SpendWindow reports priced spend and whether the window contains any
|
||||
// unpriced event, for one scope, in one query round-trip.
|
||||
type SpendWindow struct {
|
||||
PricedSubcents int64
|
||||
Degraded bool
|
||||
}
|
||||
|
||||
func (r *Repository) SpendWindowForWorkspace(ctx, workspaceID string, start time.Time, hasStart bool, before time.Time) (SpendWindow, error)
|
||||
func (r *Repository) SpendWindowForAgent(ctx, agentInstanceID string, start time.Time, hasStart bool, before time.Time) (SpendWindow, error)
|
||||
func (r *Repository) SpendWindowForProject(ctx, projectID string, start time.Time, hasStart bool, before time.Time) (SpendWindow, error)
|
||||
```
|
||||
|
||||
Workspace scope joins `office_cost_events e JOIN agent_profiles a ON
|
||||
a.id = e.agent_profile_id WHERE a.workspace_id = ?` — never `tasks`, closing
|
||||
the 138-orphan / 973.76 USD gap `SumCostsSince`'s inner join produces (W4
|
||||
pinned evidence). Agent scope filters `e.agent_profile_id = ?` directly
|
||||
(already correct in `GetCostForAgentSince`, but not reused, per W4). Project
|
||||
scope filters `e.project_id = ?` directly — the column already exists on
|
||||
`office_cost_events` (`base.go:281`), so unlike the legacy
|
||||
`GetCostForProject`'s live-task-project join, no query against `tasks` is
|
||||
needed at all, and reparenting a task cannot move historical spend between
|
||||
ceilings (`AC-OFFICE-BUDGET-002.15`'s "recorded on the cost event itself...
|
||||
not... the current project of the event's task"). `hasStart=false` (the
|
||||
`total` period) omits the lower bound. Every query also filters `e.occurred_at
|
||||
< ?` (`before`, the captured evaluation instant) — the half-open
|
||||
`[cutoff, now)` window of `AC-OFFICE-BUDGET-002.10`, closing the
|
||||
clock-skew/back-dated-write gap. `Degraded` is `COUNT(*) FILTER (WHERE
|
||||
e.cost_source = 'unpriced') > 0` (SQLite: `SUM(CASE WHEN cost_source =
|
||||
'unpriced' THEN 1 ELSE 0 END) > 0`), never reading `estimated`.
|
||||
|
||||
## Pricing degradation
|
||||
|
||||
`gate4`/`gate5`'s per-policy test, applied identically to policies and the
|
||||
default (`AC-OFFICE-BUDGET-003.11`):
|
||||
|
||||
```go
|
||||
func degradationBlocks(degraded bool, pricedSubcents, limitSubcents int64, provenance shared.RunProvenance) bool {
|
||||
return degraded && provenance == shared.RunProvenanceUnattended && 2*pricedSubcents >= limitSubcents
|
||||
}
|
||||
```
|
||||
|
||||
The `2*x >= limit` form is `AC-OFFICE-BUDGET-004.3`'s exact-50%-without-
|
||||
truncation requirement. `degradationBlocks` overrides `notify_only` (it is
|
||||
called regardless of action, per `AC-OFFICE-BUDGET-004.3`'s "applies whatever
|
||||
the policy's action"). When it fires and the plain limit test
|
||||
(`AC-OFFICE-BUDGET-001.7`) did **not** also fire, the run's outcome is
|
||||
`RunOutcomeBudgetUnmeasurable` (new constant, `"budget_unmeasurable"`,
|
||||
`internal/office/service/run.go`) rather than `RunOutcomeBudgetBlocked` —
|
||||
`AC-OFFICE-BUDGET-005.7`. When both fire, outcome stays `budget_blocked` and
|
||||
the activity entry alone carries the degradation flag
|
||||
(`AC-OFFICE-BUDGET-004.6`).
|
||||
|
||||
## Built-in default ceiling
|
||||
|
||||
New table, added to `createCostTables()` (`base.go`) beside
|
||||
`office_budget_policies` — a genuinely new table, not a column on an existing
|
||||
one, because `AC-OFFICE-BUDGET-003.7` requires the setting be addressed by a
|
||||
stable identifier distinct from any `office_budget_policies` row and never
|
||||
appear in that table's list results:
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS office_budget_default_settings (
|
||||
workspace_id TEXT PRIMARY KEY,
|
||||
limit_subcents INTEGER NOT NULL,
|
||||
updated_at TIMESTAMP NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
No migration needed — a brand-new table's `CREATE TABLE IF NOT EXISTS` is
|
||||
idempotent on both fresh and existing databases (backend `CLAUDE.md`'s
|
||||
migration rule applies to adding a *column* to an *existing* table, not to a
|
||||
new table). `costs.go` gains `GetWorkspaceBudgetDefault(ctx, workspaceID)
|
||||
(int64, error)` (returns `DefaultCeilingSubcents = 500_000` when no row
|
||||
exists — `AC-OFFICE-BUDGET-003.9`, never an error for "absent") and
|
||||
`SetWorkspaceBudgetDefault(ctx, workspaceID string, limitSubcents int64)
|
||||
error` (`INSERT ... ON CONFLICT(workspace_id) DO UPDATE SET
|
||||
limit_subcents = excluded.limit_subcents, updated_at = excluded.updated_at`
|
||||
— single-statement last-write-wins, `AC-OFFICE-BUDGET-003.10`, no
|
||||
read-modify-write race). `CostService` exposes both; `Handler` adds two
|
||||
routes on the existing budget route group:
|
||||
|
||||
```text
|
||||
GET /workspaces/:wsId/budgets/default -> {"limit_subcents": N}
|
||||
PUT /workspaces/:wsId/budgets/default -> validates > 0 (else 400, AC-003.8), writes, echoes
|
||||
```
|
||||
|
||||
`gateBuiltInDefault` calls `EvaluateDefaultCeiling(ctx, workspaceID, at
|
||||
time.Time) (PreLaunchPolicyResult, error)` (same file, same shape as a
|
||||
single-policy `EvaluatePreLaunch` result, `PolicyID=""`,
|
||||
`IsDefault=true`), which reads the effective limit, then evaluates it exactly
|
||||
like a `daily` + `block_new_tasks` policy using
|
||||
`SpendWindowForWorkspace` — the same query gate 4's workspace-scoped
|
||||
policies use, so a policy and the default cannot disagree about which events
|
||||
count in the same window (`AC-OFFICE-BUDGET-001.9`'s "same captured
|
||||
instant" applies transitively because both gates share `admissionCtx.at`).
|
||||
|
||||
## MaxRetryCount without escalation
|
||||
|
||||
`AC-OFFICE-BUDGET-001.17` forbids a budget-caused permanent failure from
|
||||
queuing any new run, "in particular... an escalation run for another agent".
|
||||
The existing `HandleRunFailure` → `escalateFailure` path queues exactly that
|
||||
(`queueCEOAgentError`). `admitBudgetDeferral`'s terminal branch therefore
|
||||
does **not** call `s.escalateFailure`; it calls a new
|
||||
`(s *Service) failRunNoEscalation(ctx, run *models.Run, cause
|
||||
budgetDeferralCause) error` (`retry.go` sibling in `budget_admission.go`)
|
||||
that performs exactly `escalateFailure`'s non-escalating half: `s.FailRun`
|
||||
plus one `LogActivityWithRun` naming the cause
|
||||
(`AC-OFFICE-BUDGET-006.4`/`.5`) — no `GetAgentFromConfig` re-fetch for
|
||||
escalation purposes, no `queueCEOAgentError` call. This is applied uniformly
|
||||
to all four budget-deferral causes reaching `MaxRetryCount` — the evaluator
|
||||
fault itself (`AC-OFFICE-BUDGET-001.4`) and the three `AC-OFFICE-BUDGET-006.4`
|
||||
causes (workspace-lookup error, unevaluated policy, failed project lookup) —
|
||||
because `AC-OFFICE-BUDGET-006.4` states they "defer... under
|
||||
`AC-OFFICE-BUDGET-001.3`'s terms", and `AC-OFFICE-BUDGET-001.4` is the
|
||||
`MaxRetryCount` disposition `AC-OFFICE-BUDGET-001.3` names; treating the
|
||||
escalation exclusion as applying only to the literally-numbered `.4` while
|
||||
letting the other three self-escalate a CEO agent would silently reopen the
|
||||
launch-on-persistent-fault gap this capability exists to close. Documented
|
||||
here as the resolving reading of an otherwise-textually-narrow cross-reference,
|
||||
per Build's instruction to record a documented assumption rather than route
|
||||
back to Spec for a wording gap.
|
||||
|
||||
## Observability: activity entries and counters
|
||||
|
||||
Every new state writes an `office_activity_log` row via
|
||||
`LogActivityWithRun` with a distinct `Action` value — `action` is the
|
||||
existing queryable, un-parsed column
|
||||
`AC-OFFICE-BUDGET-005.3`/`AC-OFFICE-BUDGET-006.5` require:
|
||||
|
||||
| State | `action` | Names policy? | Counter |
|
||||
| --- | --- | --- | --- |
|
||||
| Evaluator fault, deferred | `run_budget_evaluator_fault_deferred` | no | `office_budget_deferred_evaluator_fault_total{provenance}` |
|
||||
| Evaluator fault, failed at max retry | `run_budget_evaluator_fault_failed` | no | `office_budget_failed_evaluator_fault_total{provenance}` |
|
||||
| No evaluator wired (unattended) | `run_budget_no_evaluator` | no | `office_budget_blocked_no_evaluator_total{provenance}` |
|
||||
| Workspace lookup errored, deferred | `run_budget_workspace_lookup_deferred` | no | `office_budget_deferred_workspace_lookup_total{provenance}` |
|
||||
| Workspace lookup failed at max retry | `run_budget_workspace_lookup_failed` | no | `office_budget_failed_workspace_lookup_total{provenance}` |
|
||||
| Workspace unresolvable, cancelled | `run_budget_workspace_unresolvable` | no | `office_budget_cancelled_no_workspace_total{provenance}` |
|
||||
| Stale deferral, cancelled | `run_budget_deferral_stale_cancelled` | no | `office_budget_cancelled_stale_total{provenance}` |
|
||||
| Unevaluated policy, deferred | `run_budget_unevaluated_policy_deferred` | **yes** | `office_budget_deferred_unevaluated_policy_total{provenance}` |
|
||||
| Unevaluated policy failed at max retry | `run_budget_unevaluated_policy_failed` | **yes** | `office_budget_failed_unevaluated_policy_total{provenance}` |
|
||||
| Project lookup errored, deferred | `run_budget_project_lookup_deferred` | no | `office_budget_deferred_project_lookup_total{provenance}` |
|
||||
| Project lookup failed at max retry | `run_budget_project_lookup_failed` | no | `office_budget_failed_project_lookup_total{provenance}` |
|
||||
| Payload unparseable, cancelled | `run_budget_payload_unparseable` | no | `office_budget_cancelled_unparseable_payload_total{provenance}` |
|
||||
| Task not found, cancelled | `run_budget_task_not_found` | no | `office_budget_cancelled_task_not_found_total{provenance}` |
|
||||
| Limit reached, blocked | `run_budget_blocked` (existing) | yes/default | `office_budget_blocked_limit_total{provenance}` |
|
||||
| Pricing-degraded, blocked | `run_budget_pricing_degraded_blocked` | yes/default | `office_budget_blocked_pricing_degraded_total{provenance}` |
|
||||
| Pricing-degraded, admitted | `run_budget_pricing_degraded_admitted` | yes/default | `office_budget_admitted_pricing_degraded_total{provenance}`, incremented once per **run** admitted (not per entry), only when the run's final disposition is launch |
|
||||
| Admitted against built-in default | (no entry — launch is silent by design) | — | `office_budget_admitted_default_total{provenance}` |
|
||||
|
||||
Counters live in a new `internal/office/service/budget_metrics_vars.go`,
|
||||
following the `expvar.NewMap` + label convention of
|
||||
`internal/office/scheduler/metrics_vars.go` cited in
|
||||
`stall-visibility.md`. Every deferral counter increments once per deferral
|
||||
**attempt** (`AC-OFFICE-BUDGET-005.4`/`.6`); every other counter increments
|
||||
once per run. `AC-OFFICE-BUDGET-002.13`/`.4.8`'s per-policy-per-UTC-day
|
||||
activity-entry dedup is an in-memory `map[string]civilDay` guarded by a
|
||||
mutex on `CostService` (best-effort across restarts and concurrent
|
||||
evaluations, per the criteria's own "best-effort under concurrency" clause —
|
||||
no new table for a dedup key that is allowed to duplicate).
|
||||
|
||||
Every entry that fires before any ceiling was determined states so
|
||||
explicitly in its JSON `Details` (`"ceiling_determined": false`) and never
|
||||
sets a `policy_id` field, except the two unevaluated-policy states, which
|
||||
name the policy id that could not be evaluated (`AC-OFFICE-BUDGET-005.5`).
|
||||
Every deferral entry's `Details` also carries `"attempt": run.RetryCount + 1`
|
||||
(`AC-OFFICE-BUDGET-005.6`).
|
||||
|
||||
## `runs.outcome` vocabulary change
|
||||
|
||||
`RunOutcomeBudgetUnmeasurable = "budget_unmeasurable"` added to
|
||||
`internal/office/service/run.go`'s outcome block. Companion edit to
|
||||
[task-delivery-ledger/spec.md](../../task-delivery-ledger/spec.md), same
|
||||
change: the `runs.outcome` column doc's five-value list becomes six and its
|
||||
"one of the five values... it never writes ''" sentence becomes six; the
|
||||
`office/service/scheduler_integration.go:829` mapping-table row is narrowed
|
||||
to "pre-execution budget block, limit reached" with a new row for the
|
||||
pricing-degraded-unmeasurable block; the corresponding GIVEN/WHEN/THEN
|
||||
scenario is narrowed and a new scenario added for the unmeasurable case —
|
||||
per `AC-OFFICE-BUDGET-005.7`'s explicit requirement that both the
|
||||
enumeration and every statement fixing its cardinality change together.
|
||||
|
||||
## Frontend
|
||||
|
||||
`apps/web/app/office/workspace/costs/create-budget-form.tsx`'s period
|
||||
`Select` gains `daily` and `yearly` options (alongside the existing
|
||||
`monthly`/`total`) so the offered set matches `BudgetPeriod.Valid()` exactly
|
||||
— `AC-OFFICE-BUDGET-002.9`. A new Go test,
|
||||
`internal/office/costs/period_parity_test.go`, implements
|
||||
`AC-OFFICE-BUDGET-002.12`: it reads `enums.go`'s `BudgetPeriod` `Valid()`
|
||||
switch cases via `go/ast` (same technique as the provenance completeness
|
||||
test, smaller in scope — one file, one function) for the declared set, and
|
||||
reads `create-budget-form.tsx`'s literal `SelectItem value="..."` list under
|
||||
the period `FormField` via a regex scoped to that file for the offered set
|
||||
(TypeScript, not Go — `go/ast` cannot parse it), and fails on any
|
||||
asymmetric difference. This lives in the **Go** suite per
|
||||
`AC-OFFICE-BUDGET-002.12`'s explicit requirement ("the check shall live in
|
||||
the backend Go test suite").
|
||||
|
||||
`budgets-tab.tsx` gains a `DefaultCeilingCard` (new file,
|
||||
`default-ceiling-card.tsx`) above the policy list: reads
|
||||
`GET .../budgets/default`, renders the effective limit in dollars with an
|
||||
inline edit control that `PUT`s the new value — `AC-OFFICE-BUDGET-003.5`'s
|
||||
"visible... without inspecting the database". It is visually distinct from a
|
||||
`BudgetPolicyCard` (no scope/action/period controls — the default is always
|
||||
workspace-scoped, always `daily`, always blocking) and carries copy stating
|
||||
it applies to unattended runs only, so an operator does not mistake it for a
|
||||
policy that also gates attended work.
|
||||
|
||||
## Security
|
||||
|
||||
No new trust boundary. The two new routes reuse the existing
|
||||
`officeWorkspaceScopeMiddleware` resolution already applied to
|
||||
`/workspaces/:wsId/budgets*` (same route group, `registerBudgetRoutes`).
|
||||
|
||||
## Related decisions
|
||||
|
||||
None new. This design implements the human dispositions already recorded in
|
||||
the task plan (W2, W3, W4, X2, Y1) rather than introducing its own
|
||||
architectural choices beyond where noted above (the new table, and the
|
||||
MaxRetryCount-without-escalation scope reading).
|
||||
@@ -314,11 +314,11 @@ evidence** relies on.
|
||||
### `runs.outcome` (new column)
|
||||
|
||||
Nullable TEXT on the existing `runs` table:
|
||||
`processed | budget_blocked | idle_skipped | agent_inactive | task_tree_held`.
|
||||
`processed | budget_blocked | budget_unmeasurable | idle_skipped | agent_inactive | task_tree_held`.
|
||||
|
||||
`NULL` for every row written before activation, for any run that never reaches a terminal
|
||||
status, and for every run that reaches `status = 'failed'` (see **Office run outcome**,
|
||||
the `FailRun` bullet). On the **finished** path the writer writes one of the five values
|
||||
the `FailRun` bullet). On the **finished** path the writer writes one of the six values
|
||||
above; it never writes `''`. No database constraint is added —
|
||||
the reader is total over every possible value (see **Office run outcome**), so
|
||||
an unrecognised value degrades to `skipped` rather than breaking a query.
|
||||
@@ -1488,7 +1488,7 @@ line number is a pointer (see **Citation convention**).
|
||||
| `office/service/scheduler_integration.go:218` — agent not active | `agent_inactive` |
|
||||
| `office/service/scheduler_integration.go:247` — idle skip | `idle_skipped` |
|
||||
| `office/service/scheduler_integration.go:517` — task-tree hold | `task_tree_held` |
|
||||
| `office/service/scheduler_integration.go:829` — pre-execution budget block | `budget_blocked` |
|
||||
| `office/service/budget_admission.go:120` — admission | `budget_blocked`/`budget_unmeasurable` |
|
||||
| `office/service/event_subscribers.go:408` — agent-completed for a task-bearing run | `processed` |
|
||||
| `office/service/event_subscribers.go:512` — `handleTasklessAgentCompleted` | `processed` |
|
||||
|
||||
@@ -1531,9 +1531,9 @@ transaction or a guard, because it must not change `runs.status` semantics:
|
||||
(`:44`) passes `NULL`. `NULL` is correct rather than a placeholder — a run that reached
|
||||
`status = 'failed'` is bucketed by `RunCountsByDayForAgent` on its status alone and never
|
||||
reaches the `succeeded` / `skipped` / `unclassified` buckets, so no value from the
|
||||
five-value vocabulary would ever be read, and inventing one would assert a classification
|
||||
six-value vocabulary would ever be read, and inventing one would assert a classification
|
||||
nothing consumes. This also makes the sentence under `### runs.outcome` exact: the
|
||||
five-value claim describes the **finished** path; the failed path writes `NULL` in the
|
||||
six-value claim describes the **finished** path; the failed path writes `NULL` in the
|
||||
same statement.
|
||||
- **The second caller pair of the shared repository method, and what it passes.** Changing
|
||||
that signature necessarily reaches
|
||||
@@ -2085,9 +2085,8 @@ consulting `kandev_meta` — the activation instant remains the authoritative an
|
||||
|
||||
### Office run outcome
|
||||
|
||||
- **GIVEN** a run blocked by the pre-execution budget check, **WHEN** it
|
||||
finishes, **THEN** `runs.status = 'finished'` and `runs.outcome =
|
||||
'budget_blocked'`.
|
||||
- **GIVEN** a budget block, **WHEN** it finishes, **THEN** `runs.outcome`
|
||||
is `'budget_blocked'` if limit-reached else `'budget_unmeasurable'`.
|
||||
- **GIVEN** a run skipped because the agent is not active, **WHEN** it finishes,
|
||||
**THEN** `runs.outcome = 'agent_inactive'` — even though that path writes no
|
||||
`office_activity_log` row.
|
||||
@@ -2113,7 +2112,7 @@ consulting `kandev_meta` — the activation instant remains the authoritative an
|
||||
- **GIVEN** a run that fails, **WHEN** `FailRun` transitions it through the shared
|
||||
`transitionRunTerminal` statement, **THEN** `runs.status = 'failed'` and
|
||||
`runs.outcome IS NULL` — the failed path writes `NULL` in the same statement, and no
|
||||
value from the five-value vocabulary is invented for it.
|
||||
value from the six-value vocabulary is invented for it.
|
||||
- **GIVEN** a day containing one failed run written that way, **WHEN**
|
||||
`RunCountsByDayForAgent` reports that day, **THEN** it counts in `failed` and in
|
||||
neither `unclassified` nor `skipped` — the `NULL` outcome is never read, because the
|
||||
@@ -2135,7 +2134,7 @@ consulting `kandev_meta` — the activation instant remains the authoritative an
|
||||
**WHEN** `RunCountsByDayForAgent` reports that day, **THEN** it returns
|
||||
`succeeded = 1`, `skipped = 1`, `unclassified = 1`, `failed = 1` and
|
||||
`other = 0`.
|
||||
- **GIVEN** a `finished` run whose `outcome` holds a value outside the five
|
||||
- **GIVEN** a `finished` run whose `outcome` holds a value outside the six
|
||||
named ones, **WHEN** that day is reported, **THEN** it counts in `skipped` —
|
||||
the bucketing is total and no query errors.
|
||||
- **GIVEN** that same day, **WHEN** the agent dashboard renders it, **THEN**
|
||||
|
||||
Reference in New Issue
Block a user