diff --git a/apps/backend/internal/office/costs/budgets.go b/apps/backend/internal/office/costs/budgets.go index 279e726def..ec0d4549da 100644 --- a/apps/backend/internal/office/costs/budgets.go +++ b/apps/backend/internal/office/costs/budgets.go @@ -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) } diff --git a/apps/backend/internal/office/costs/budgets_test.go b/apps/backend/internal/office/costs/budgets_test.go index e2ede18840..f49781ece6 100644 --- a/apps/backend/internal/office/costs/budgets_test.go +++ b/apps/backend/internal/office/costs/budgets_test.go @@ -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() diff --git a/apps/backend/internal/office/costs/default_ceiling.go b/apps/backend/internal/office/costs/default_ceiling.go new file mode 100644 index 0000000000..b285f4b499 --- /dev/null +++ b/apps/backend/internal/office/costs/default_ceiling.go @@ -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 +} diff --git a/apps/backend/internal/office/costs/default_ceiling_test.go b/apps/backend/internal/office/costs/default_ceiling_test.go new file mode 100644 index 0000000000..366a42f270 --- /dev/null +++ b/apps/backend/internal/office/costs/default_ceiling_test.go @@ -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") + } +} diff --git a/apps/backend/internal/office/costs/degradation.go b/apps/backend/internal/office/costs/degradation.go new file mode 100644 index 0000000000..369141329e --- /dev/null +++ b/apps/backend/internal/office/costs/degradation.go @@ -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 +} diff --git a/apps/backend/internal/office/costs/degradation_test.go b/apps/backend/internal/office/costs/degradation_test.go new file mode 100644 index 0000000000..1e735d0548 --- /dev/null +++ b/apps/backend/internal/office/costs/degradation_test.go @@ -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) + } + }) + } +} diff --git a/apps/backend/internal/office/costs/dto.go b/apps/backend/internal/office/costs/dto.go index 70da417210..5fe3c303c1 100644 --- a/apps/backend/internal/office/costs/dto.go +++ b/apps/backend/internal/office/costs/dto.go @@ -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"` +} diff --git a/apps/backend/internal/office/costs/handler.go b/apps/backend/internal/office/costs/handler.go index cc44b5dae8..fd7be1f1f1 100644 --- a/apps/backend/internal/office/costs/handler.go +++ b/apps/backend/internal/office/costs/handler.go @@ -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)) +} diff --git a/apps/backend/internal/office/costs/handler_default_ceiling_test.go b/apps/backend/internal/office/costs/handler_default_ceiling_test.go new file mode 100644 index 0000000000..cfc80f7404 --- /dev/null +++ b/apps/backend/internal/office/costs/handler_default_ceiling_test.go @@ -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) + } +} diff --git a/apps/backend/internal/office/costs/period_parity_test.go b/apps/backend/internal/office/costs/period_parity_test.go new file mode 100644 index 0000000000..a001f96b1b --- /dev/null +++ b/apps/backend/internal/office/costs/period_parity_test.go @@ -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, "") + if closeIdx == -1 { + t.Fatalf("no closing 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) + } + } +} diff --git a/apps/backend/internal/office/costs/policy_skip.go b/apps/backend/internal/office/costs/policy_skip.go new file mode 100644 index 0000000000..55e2eccda3 --- /dev/null +++ b/apps/backend/internal/office/costs/policy_skip.go @@ -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 +} diff --git a/apps/backend/internal/office/costs/policy_skip_test.go b/apps/backend/internal/office/costs/policy_skip_test.go new file mode 100644 index 0000000000..587f471307 --- /dev/null +++ b/apps/backend/internal/office/costs/policy_skip_test.go @@ -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) + } + }) + } +} diff --git a/apps/backend/internal/office/costs/policy_validation.go b/apps/backend/internal/office/costs/policy_validation.go new file mode 100644 index 0000000000..7fb97eab5e --- /dev/null +++ b/apps/backend/internal/office/costs/policy_validation.go @@ -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 +} diff --git a/apps/backend/internal/office/costs/policy_validation_test.go b/apps/backend/internal/office/costs/policy_validation_test.go new file mode 100644 index 0000000000..3f82549486 --- /dev/null +++ b/apps/backend/internal/office/costs/policy_validation_test.go @@ -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) + } + }) + } +} diff --git a/apps/backend/internal/office/costs/prelaunch.go b/apps/backend/internal/office/costs/prelaunch.go new file mode 100644 index 0000000000..62442e65ef --- /dev/null +++ b/apps/backend/internal/office/costs/prelaunch.go @@ -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 +} diff --git a/apps/backend/internal/office/costs/prelaunch_evaluate_test.go b/apps/backend/internal/office/costs/prelaunch_evaluate_test.go new file mode 100644 index 0000000000..8fe6a0f5f2 --- /dev/null +++ b/apps/backend/internal/office/costs/prelaunch_evaluate_test.go @@ -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) + } +} diff --git a/apps/backend/internal/office/costs/prelaunch_test.go b/apps/backend/internal/office/costs/prelaunch_test.go new file mode 100644 index 0000000000..953fba8130 --- /dev/null +++ b/apps/backend/internal/office/costs/prelaunch_test.go @@ -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) + } +} diff --git a/apps/backend/internal/office/costs/service.go b/apps/backend/internal/office/costs/service.go index 3db2353062..26d6dd22eb 100644 --- a/apps/backend/internal/office/costs/service.go +++ b/apps/backend/internal/office/costs/service.go @@ -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. diff --git a/apps/backend/internal/office/models/enums.go b/apps/backend/internal/office/models/enums.go index e03e384cd9..cb048e794a 100644 --- a/apps/backend/internal/office/models/enums.go +++ b/apps/backend/internal/office/models/enums.go @@ -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 diff --git a/apps/backend/internal/office/models/enums_test.go b/apps/backend/internal/office/models/enums_test.go new file mode 100644 index 0000000000..1e18549b68 --- /dev/null +++ b/apps/backend/internal/office/models/enums_test.go @@ -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`) + } +} diff --git a/apps/backend/internal/office/models/models.go b/apps/backend/internal/office/models/models.go index fab91a2c17..8ba7175238 100644 --- a/apps/backend/internal/office/models/models.go +++ b/apps/backend/internal/office/models/models.go @@ -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"` diff --git a/apps/backend/internal/office/models/prelaunch.go b/apps/backend/internal/office/models/prelaunch.go new file mode 100644 index 0000000000..b085fe13f8 --- /dev/null +++ b/apps/backend/internal/office/models/prelaunch.go @@ -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 } diff --git a/apps/backend/internal/office/repository/sqlite/activity.go b/apps/backend/internal/office/repository/sqlite/activity.go index fa33204030..be32361ec6 100644 --- a/apps/backend/internal/office/repository/sqlite/activity.go +++ b/apps/backend/internal/office/repository/sqlite/activity.go @@ -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 { diff --git a/apps/backend/internal/office/repository/sqlite/agents.go b/apps/backend/internal/office/repository/sqlite/agents.go index 986b340439..602fec445d 100644 --- a/apps/backend/internal/office/repository/sqlite/agents.go +++ b/apps/backend/internal/office/repository/sqlite/agents.go @@ -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 } diff --git a/apps/backend/internal/office/repository/sqlite/base.go b/apps/backend/internal/office/repository/sqlite/base.go index d481113d58..d7b74cbd28 100644 --- a/apps/backend/internal/office/repository/sqlite/base.go +++ b/apps/backend/internal/office/repository/sqlite/base.go @@ -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 } diff --git a/apps/backend/internal/office/repository/sqlite/default_ceiling.go b/apps/backend/internal/office/repository/sqlite/default_ceiling.go new file mode 100644 index 0000000000..c73a7af2f2 --- /dev/null +++ b/apps/backend/internal/office/repository/sqlite/default_ceiling.go @@ -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 +} diff --git a/apps/backend/internal/office/repository/sqlite/default_ceiling_test.go b/apps/backend/internal/office/repository/sqlite/default_ceiling_test.go new file mode 100644 index 0000000000..8b70bcc47e --- /dev/null +++ b/apps/backend/internal/office/repository/sqlite/default_ceiling_test.go @@ -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") + } +} diff --git a/apps/backend/internal/office/repository/sqlite/spendwindow.go b/apps/backend/internal/office/repository/sqlite/spendwindow.go new file mode 100644 index 0000000000..e1b195333f --- /dev/null +++ b/apps/backend/internal/office/repository/sqlite/spendwindow.go @@ -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) +} diff --git a/apps/backend/internal/office/repository/sqlite/spendwindow_test.go b/apps/backend/internal/office/repository/sqlite/spendwindow_test.go new file mode 100644 index 0000000000..3edcaa410c --- /dev/null +++ b/apps/backend/internal/office/repository/sqlite/spendwindow_test.go @@ -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) + } +} diff --git a/apps/backend/internal/office/repository/sqlite/workspace_deletion.go b/apps/backend/internal/office/repository/sqlite/workspace_deletion.go index 7e2e151b4c..0a435287a7 100644 --- a/apps/backend/internal/office/repository/sqlite/workspace_deletion.go +++ b/apps/backend/internal/office/repository/sqlite/workspace_deletion.go @@ -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 ( diff --git a/apps/backend/internal/office/service/base_test.go b/apps/backend/internal/office/service/base_test.go index a81ae19041..cd74500580 100644 --- a/apps/backend/internal/office/service/base_test.go +++ b/apps/backend/internal/office/service/base_test.go @@ -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 (?, ?, ?, ?, ?, ?)`, diff --git a/apps/backend/internal/office/service/budget_admission.go b/apps/backend/internal/office/service/budget_admission.go new file mode 100644 index 0000000000..7a6fdbcd29 --- /dev/null +++ b/apps/backend/internal/office/service/budget_admission.go @@ -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) + } +} diff --git a/apps/backend/internal/office/service/budget_admission_test.go b/apps/backend/internal/office/service/budget_admission_test.go new file mode 100644 index 0000000000..a1b7d07f86 --- /dev/null +++ b/apps/backend/internal/office/service/budget_admission_test.go @@ -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 + } +} diff --git a/apps/backend/internal/office/service/budget_metrics.go b/apps/backend/internal/office/service/budget_metrics.go new file mode 100644 index 0000000000..62864cf578 --- /dev/null +++ b/apps/backend/internal/office/service/budget_metrics.go @@ -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) + } +} diff --git a/apps/backend/internal/office/service/budget_metrics_test.go b/apps/backend/internal/office/service/budget_metrics_test.go new file mode 100644 index 0000000000..1afa2a6262 --- /dev/null +++ b/apps/backend/internal/office/service/budget_metrics_test.go @@ -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) + } +} diff --git a/apps/backend/internal/office/service/budget_observability.go b/apps/backend/internal/office/service/budget_observability.go new file mode 100644 index 0000000000..257b5e7de6 --- /dev/null +++ b/apps/backend/internal/office/service/budget_observability.go @@ -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, "") +} diff --git a/apps/backend/internal/office/service/budget_observability_test.go b/apps/backend/internal/office/service/budget_observability_test.go new file mode 100644 index 0000000000..cee89cb8d5 --- /dev/null +++ b/apps/backend/internal/office/service/budget_observability_test.go @@ -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) + } +} diff --git a/apps/backend/internal/office/service/config_read.go b/apps/backend/internal/office/service/config_read.go index 08bfbdba59..19c627f426 100644 --- a/apps/backend/internal/office/service/config_read.go +++ b/apps/backend/internal/office/service/config_read.go @@ -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. diff --git a/apps/backend/internal/office/service/retry.go b/apps/backend/internal/office/service/retry.go index e3d23f2251..01662981cf 100644 --- a/apps/backend/internal/office/service/retry.go +++ b/apps/backend/internal/office/service/retry.go @@ -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 diff --git a/apps/backend/internal/office/service/run.go b/apps/backend/internal/office/service/run.go index f6078fcc5d..92808c1797 100644 --- a/apps/backend/internal/office/service/run.go +++ b/apps/backend/internal/office/service/run.go @@ -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. diff --git a/apps/backend/internal/office/service/scheduler_integration.go b/apps/backend/internal/office/service/scheduler_integration.go index 5e78eb707a..ff148143cb 100644 --- a/apps/backend/internal/office/service/scheduler_integration.go +++ b/apps/backend/internal/office/service/scheduler_integration.go @@ -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 diff --git a/apps/backend/internal/office/service/service.go b/apps/backend/internal/office/service/service.go index bd49809fb0..a9dc425f07 100644 --- a/apps/backend/internal/office/service/service.go +++ b/apps/backend/internal/office/service/service.go @@ -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) diff --git a/apps/backend/internal/office/service/test_helpers.go b/apps/backend/internal/office/service/test_helpers.go index c6d59d63d5..5c0e594b1d 100644 --- a/apps/backend/internal/office/service/test_helpers.go +++ b/apps/backend/internal/office/service/test_helpers.go @@ -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. diff --git a/apps/backend/internal/office/shared/runprovenance.go b/apps/backend/internal/office/shared/runprovenance.go new file mode 100644 index 0000000000..8b71eb6cad --- /dev/null +++ b/apps/backend/internal/office/shared/runprovenance.go @@ -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 +} diff --git a/apps/backend/internal/office/shared/runprovenance_completeness_test.go b/apps/backend/internal/office/shared/runprovenance_completeness_test.go new file mode 100644 index 0000000000..6a83d884ec --- /dev/null +++ b/apps/backend/internal/office/shared/runprovenance_completeness_test.go @@ -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 +} diff --git a/apps/backend/internal/office/shared/runprovenance_test.go b/apps/backend/internal/office/shared/runprovenance_test.go new file mode 100644 index 0000000000..a9320db5da --- /dev/null +++ b/apps/backend/internal/office/shared/runprovenance_test.go @@ -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") + } +} diff --git a/apps/web/app/office/lib/budget-labels.test.ts b/apps/web/app/office/lib/budget-labels.test.ts index e2abec2281..3ae6f1a2db 100644 --- a/apps/web/app/office/lib/budget-labels.test.ts +++ b/apps/web/app/office/lib/budget-labels.test.ts @@ -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", () => { diff --git a/apps/web/app/office/lib/label-keys.ts b/apps/web/app/office/lib/label-keys.ts index ba93ad6467..d00f64d5f7 100644 --- a/apps/web/app/office/lib/label-keys.ts +++ b/apps/web/app/office/lib/label-keys.ts @@ -89,7 +89,9 @@ export const CONCURRENCY_POLICY_LABEL_KEYS: Record = { * identifier. */ export const BUDGET_PERIOD_LABEL_KEYS: Record = { + daily: "office:budgetPeriodDaily", monthly: "office:budgetPeriodMonthly", + yearly: "office:budgetPeriodYearly", total: "office:budgetPeriodTotal", }; diff --git a/apps/web/app/office/workspace/costs/budgets-tab.tsx b/apps/web/app/office/workspace/costs/budgets-tab.tsx index 4e3552032d..d203cb55f4 100644 --- a/apps/web/app/office/workspace/costs/budgets-tab.tsx +++ b/apps/web/app/office/workspace/costs/budgets-tab.tsx @@ -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 }) { + + {showCreate && ( + + {t("office:daily")} + {t("office:monthly")} + + {t("office:yearly")} + {t("office:total")} @@ -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", }); diff --git a/apps/web/app/office/workspace/costs/default-ceiling-card.test.tsx b/apps/web/app/office/workspace/costs/default-ceiling-card.test.tsx new file mode 100644 index 0000000000..f3ca80fd1d --- /dev/null +++ b/apps/web/app/office/workspace/costs/default-ceiling-card.test.tsx @@ -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() { + let resolve!: (value: T) => void; + const promise = new Promise((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(); + await waitFor(() => expect(getDefaultCeilingMock).toHaveBeenCalledWith("ws-a")); + + rerender(); + 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(); + await screen.findByText("$10.00"); + + fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME })); + expect(screen.getByRole("spinbutton")).toBeTruthy(); + + rerender(); + + 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(); + 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(); + 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(); + 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(); + 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"); + }); +}); diff --git a/apps/web/app/office/workspace/costs/default-ceiling-card.tsx b/apps/web/app/office/workspace/costs/default-ceiling-card.tsx new file mode 100644 index 0000000000..0e83488715 --- /dev/null +++ b/apps/web/app/office/workspace/costs/default-ceiling-card.tsx @@ -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 ( +
+ onDraftChange(e.target.value)} + aria-label={t("office:defaultCeiling")} + autoFocus + /> + + +
+ ); +} + +// 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(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 ( + + + {t("office:defaultCeiling")} + {!editing && ( + + )} + + +

{t("office:defaultCeilingDescription")}

+ {editing ? ( + setEditing(false)} + /> + ) : ( +
+ {limitSubcents == null ? t("common:loading") : formatDollars(limitSubcents)} +
+ )} +
+
+ ); +} diff --git a/apps/web/e2e/tests/office/budget-enforcement.spec.ts b/apps/web/e2e/tests/office/budget-enforcement.spec.ts new file mode 100644 index 0000000000..e4ec9b492b --- /dev/null +++ b/apps/web/e2e/tests/office/budget-enforcement.spec.ts @@ -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", + }); + }); +}); diff --git a/apps/web/e2e/tests/office/mobile-budget-enforcement.spec.ts b/apps/web/e2e/tests/office/mobile-budget-enforcement.spec.ts new file mode 100644 index 0000000000..ff1a5f8dcb --- /dev/null +++ b/apps/web/e2e/tests/office/mobile-budget-enforcement.spec.ts @@ -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), + ); + }); +}); diff --git a/apps/web/lib/api/domains/office-api.ts b/apps/web/lib/api/domains/office-api.ts index dd9f72387e..b5463f1735 100644 --- a/apps/web/lib/api/domains/office-api.ts +++ b/apps/web/lib/api/domains/office-api.ts @@ -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(`${BASE}/workspaces/${workspaceId}/budgets/default`, options); } -export function createBudget( +export function setDefaultCeiling( workspaceId: string, - data: Partial, + limitSubcents: number, options?: ApiRequestOptions, ) { - return fetchJson(`${BASE}/workspaces/${workspaceId}/budgets`, { + return fetchJson(`${BASE}/workspaces/${workspaceId}/budgets/default`, { ...options, - init: { method: "POST", body: JSON.stringify(data), ...options?.init }, - }); -} - -export function updateBudget(id: string, data: Partial, options?: ApiRequestOptions) { - return fetchJson(`${BASE}/budgets/${id}`, { - ...options, - init: { method: "PATCH", body: JSON.stringify(data), ...options?.init }, - }); -} - -export function deleteBudget(id: string, options?: ApiRequestOptions) { - return fetchJson(`${BASE}/budgets/${id}`, { - ...options, - init: { method: "DELETE", ...options?.init }, + init: { + method: "PUT", + body: JSON.stringify({ limit_subcents: limitSubcents }), + ...options?.init, + }, }); } diff --git a/apps/web/lib/api/domains/office-budget-api.test.ts b/apps/web/lib/api/domains/office-budget-api.test.ts new file mode 100644 index 0000000000..50fefa1a93 --- /dev/null +++ b/apps/web/lib/api/domains/office-budget-api.test.ts @@ -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[0]; +type FetchInit = Parameters[1]; +const fetchSpy = vi.fn<(...args: [FetchInput, FetchInit?]) => Promise>(); +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", + }), + ]); + }); +}); diff --git a/apps/web/lib/api/domains/office-budget-api.ts b/apps/web/lib/api/domains/office-budget-api.ts new file mode 100644 index 0000000000..e1701b91a6 --- /dev/null +++ b/apps/web/lib/api/domains/office-budget-api.ts @@ -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; + +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): Record { + 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, + options?: ApiRequestOptions, +) { + return fetchJson(`${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, options?: ApiRequestOptions) { + return fetchJson(`${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(`${BASE}/budgets/${id}`, { + ...options, + init: { method: "DELETE", ...options?.init }, + }); +} diff --git a/apps/web/lib/api/domains/office-default-ceiling-api.test.ts b/apps/web/lib/api/domains/office-default-ceiling-api.test.ts new file mode 100644 index 0000000000..7677f12c74 --- /dev/null +++ b/apps/web/lib/api/domains/office-default-ceiling-api.test.ts @@ -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[0]; +type FetchInit = Parameters[1]; +const fetchSpy = vi.fn<(...args: [FetchInput, FetchInit?]) => Promise>(); +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); + }); +}); diff --git a/apps/web/lib/state/slices/office/types.ts b/apps/web/lib/state/slices/office/types.ts index bcc5f92b12..7e76cd5d08 100644 --- a/apps/web/lib/state/slices/office/types.ts +++ b/apps/web/lib/state/slices/office/types.ts @@ -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; diff --git a/apps/web/src/locales/en/office.json b/apps/web/src/locales/en/office.json index 6d9d0315a8..979a911147 100644 --- a/apps/web/src/locales/en/office.json +++ b/apps/web/src/locales/en/office.json @@ -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", diff --git a/apps/web/src/locales/pseudo/office.json b/apps/web/src/locales/pseudo/office.json index 661ce73cae..11b2004b59 100644 --- a/apps/web/src/locales/pseudo/office.json +++ b/apps/web/src/locales/pseudo/office.json @@ -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": "Źōōḿ ōũţ", diff --git a/apps/web/src/locales/pt-pt/office.json b/apps/web/src/locales/pt-pt/office.json index 6891d04684..5e55dfb8c9 100644 --- a/apps/web/src/locales/pt-pt/office.json +++ b/apps/web/src/locales/pt-pt/office.json @@ -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", diff --git a/apps/web/src/locales/zh-cn/office.json b/apps/web/src/locales/zh-cn/office.json index 58f4656a78..31633c395d 100644 --- a/apps/web/src/locales/zh-cn/office.json +++ b/apps/web/src/locales/zh-cn/office.json @@ -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": "缩小", diff --git a/apps/web/src/locales/zh-hk/office.json b/apps/web/src/locales/zh-hk/office.json index 2f3c55e475..e255a6810c 100644 --- a/apps/web/src/locales/zh-hk/office.json +++ b/apps/web/src/locales/zh-hk/office.json @@ -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": "縮小", diff --git a/apps/web/src/locales/zh-tw/executors.json b/apps/web/src/locales/zh-tw/executors.json index 8bf05d9bf9..f6b2c0039f 100644 --- a/apps/web/src/locales/zh-tw/executors.json +++ b/apps/web/src/locales/zh-tw/executors.json @@ -425,8 +425,8 @@ "portableConfigNotFound": "未找到", "portableConfigNotFoundHint": "這只是編輯提示。你可以先儲存設定,稍後再新增該檔案。", "portableConfigTitle": "代理程式設定檔", - "allowUserNamespacesTitle": "使用者名稱空間支援", - "allowUserNamespacesDescription": "允許在容器內建立無特權的使用者名稱空間和執行掛載操作。啟用類似 bwrap 的沙箱工具。", + "allowUserNamespacesTitle": "使用者命名空間支援", + "allowUserNamespacesDescription": "允許在容器內建立無特權的使用者命名空間和執行掛載操作。啟用類似 bwrap 的沙箱工具。", "allowUserNamespacesNote": "此設定僅影響新建立的容器。現有任務環境必須重置才能使更改生效。", - "allowUserNamespacesWarning": "這會為選擇啟用的容器停用 Docker 預設的 AppArmor 限制。僅為需要使用者名稱空間沙箱的可信代理執行環境啟用。" + "allowUserNamespacesWarning": "這會為選擇啟用的容器停用 Docker 預設的 AppArmor 限制。僅為需要使用者命名空間沙箱的可信代理執行環境啟用。" } diff --git a/apps/web/src/locales/zh-tw/office.json b/apps/web/src/locales/zh-tw/office.json index 8e3daaa4bf..0eb6474664 100644 --- a/apps/web/src/locales/zh-tw/office.json +++ b/apps/web/src/locales/zh-tw/office.json @@ -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": "縮小", diff --git a/docs/specs/office/glossary.md b/docs/specs/office/glossary.md new file mode 100644 index 0000000000..5395af74d7 --- /dev/null +++ b/docs/specs/office/glossary.md @@ -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. + diff --git a/docs/specs/office/requirements/budget-admission-integrity.md b/docs/specs/office/requirements/budget-admission-integrity.md new file mode 100644 index 0000000000..48ff5a6a24 --- /dev/null +++ b/docs/specs/office/requirements/budget-admission-integrity.md @@ -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. diff --git a/docs/specs/office/requirements/budget-default-ceiling.md b/docs/specs/office/requirements/budget-default-ceiling.md new file mode 100644 index 0000000000..6ebc5f5e04 --- /dev/null +++ b/docs/specs/office/requirements/budget-default-ceiling.md @@ -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.** diff --git a/docs/specs/office/requirements/budget-enforcement.md b/docs/specs/office/requirements/budget-enforcement.md new file mode 100644 index 0000000000..a69a43f375 --- /dev/null +++ b/docs/specs/office/requirements/budget-enforcement.md @@ -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. diff --git a/docs/specs/office/requirements/budget-measurement-integrity.md b/docs/specs/office/requirements/budget-measurement-integrity.md new file mode 100644 index 0000000000..44169adcb0 --- /dev/null +++ b/docs/specs/office/requirements/budget-measurement-integrity.md @@ -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. diff --git a/docs/specs/office/requirements/budget-observability.md b/docs/specs/office/requirements/budget-observability.md new file mode 100644 index 0000000000..7f01c8862a --- /dev/null +++ b/docs/specs/office/requirements/budget-observability.md @@ -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. diff --git a/docs/specs/office/requirements/budget-run-provenance.md b/docs/specs/office/requirements/budget-run-provenance.md new file mode 100644 index 0000000000..2d5b64b519 --- /dev/null +++ b/docs/specs/office/requirements/budget-run-provenance.md @@ -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. diff --git a/docs/specs/office/system-design/budget-enforcement-01.md b/docs/specs/office/system-design/budget-enforcement-01.md new file mode 100644 index 0000000000..cb74a8a770 --- /dev/null +++ b/docs/specs/office/system-design/budget-enforcement-01.md @@ -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). diff --git a/docs/specs/task-delivery-ledger/spec.md b/docs/specs/task-delivery-ledger/spec.md index 3b28d785c4..6173e75b9c 100644 --- a/docs/specs/task-delivery-ledger/spec.md +++ b/docs/specs/task-delivery-ledger/spec.md @@ -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**