feat(office): fail closed on budget admission for unattended runs (#3520)

Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Henry
2026-09-10 22:29:00 +08:00
committed by GitHub
parent 9a9634ad2a
commit 4d05148f7a
75 changed files with 7984 additions and 102 deletions
+12 -5
View File
@@ -126,13 +126,14 @@ func (s *CostService) evaluatePolicy(
}
// periodCutoff returns the time.Time at which the policy's spend window
// starts. A zero time means "no filter" (lifetime / total).
// starts. A zero time means "no filter" (lifetime / total) or an unknown
// period retained for compatibility with stored policies.
func periodCutoff(period string, now time.Time) time.Time {
if period == budgetPeriodMonthly {
n := now.UTC()
return time.Date(n.Year(), n.Month(), 1, 0, 0, 0, 0, time.UTC)
start, ok := windowStart(models.BudgetPeriod(period), now)
if !ok {
return time.Time{}
}
return time.Time{}
return start
}
func (s *CostService) getSpendForPolicy(
@@ -272,6 +273,9 @@ func (s *CostService) pauseAgentForBudget(ctx context.Context, agentID string) b
// CreateBudgetPolicy creates a new budget policy.
func (s *CostService) CreateBudgetPolicy(ctx context.Context, policy *BudgetPolicy) error {
if err := validateBudgetPolicyWrite(policy); err != nil {
return err
}
return s.repo.CreateBudgetPolicy(ctx, policy)
}
@@ -287,6 +291,9 @@ func (s *CostService) GetBudgetPolicy(ctx context.Context, id string) (*BudgetPo
// UpdateBudgetPolicy updates a budget policy.
func (s *CostService) UpdateBudgetPolicy(ctx context.Context, policy *BudgetPolicy) error {
if err := validateBudgetPolicyWrite(policy); err != nil {
return err
}
return s.repo.UpdateBudgetPolicy(ctx, policy)
}
@@ -149,11 +149,72 @@ func insertBudgetTestCostEvent(t *testing.T, execSQL func(string, ...interface{}
now := time.Now().UTC().Format(time.RFC3339)
execSQL(
`INSERT INTO office_cost_events (id, agent_profile_id, task_id, cost_subcents, occurred_at, created_at)
VALUES (?, ?, ?, ?, ?, ?)`,
VALUES (?, ?, ?, ?, ?, ?)`,
uuid.NewString(), agentID, taskID, costSubcents, now, now,
)
}
func insertBudgetTestCostEventAt(
t *testing.T,
execSQL func(string, ...interface{}),
agentID, taskID string,
costSubcents int64,
at time.Time,
) {
t.Helper()
occurredAt := at.UTC().Format(time.RFC3339)
execSQL(
`INSERT INTO office_cost_events (id, agent_profile_id, task_id, cost_subcents, occurred_at, created_at)
VALUES (?, ?, ?, ?, ?, ?)`,
uuid.NewString(), agentID, taskID, costSubcents, occurredAt, occurredAt,
)
}
func TestCheckBudget_PeriodWindowsExcludeOlderSpend(t *testing.T) {
cases := []struct {
name string
period models.BudgetPeriod
olderBy time.Duration
wantLimit bool
}{
{name: "daily", period: models.BudgetPeriodDaily, olderBy: 48 * time.Hour},
{name: "yearly", period: models.BudgetPeriodYearly, olderBy: 400 * 24 * time.Hour},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
policy := &models.BudgetPolicy{
WorkspaceID: "ws-1",
ScopeType: models.BudgetScopeAgent,
ScopeID: "agent-1",
LimitSubcents: 500,
Period: tc.period,
AlertThresholdPct: 80,
ActionOnExceed: models.BudgetActionNotifyOnly,
}
if err := svc.CreateBudgetPolicy(ctx, policy); err != nil {
t.Fatalf("create policy: %v", err)
}
insertBudgetTestCostEventAt(t, execSQL, "agent-1", "task-1", 600, time.Now().UTC().Add(-tc.olderBy))
results, err := svc.CheckBudget(ctx, "ws-1", "agent-1", "project-1")
if err != nil {
t.Fatalf("CheckBudget: %v", err)
}
if len(results) != 1 {
t.Fatalf("results = %d, want 1", len(results))
}
if results[0].LimitExceed != tc.wantLimit {
t.Errorf("LimitExceed = %t, want %t", results[0].LimitExceed, tc.wantLimit)
}
})
}
}
func TestCheckBudget_UnderThreshold(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
@@ -0,0 +1,78 @@
package costs
import (
"context"
"fmt"
"time"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/shared"
)
// DefaultCeilingSubcents is the built-in default ceiling's shipped value:
// 500,000 subcents (50.00 USD) of priced spend per workspace per UTC day
// (AC-OFFICE-BUDGET-003.2), in force for any workspace with no written
// override (AC-OFFICE-BUDGET-003.9).
const DefaultCeilingSubcents int64 = 500_000
// GetWorkspaceBudgetDefault returns workspaceID's effective built-in default
// ceiling: the written override if one exists, otherwise the shipped
// constant. Reading the effective value never reports the ceiling as absent
// (AC-OFFICE-BUDGET-003.9).
func (s *CostService) GetWorkspaceBudgetDefault(ctx context.Context, workspaceID string) (int64, error) {
limitSubcents, found, err := s.repo.GetWorkspaceBudgetDefault(ctx, workspaceID)
if err != nil {
return 0, err
}
if !found {
return DefaultCeilingSubcents, nil
}
return limitSubcents, nil
}
// SetWorkspaceBudgetDefault writes workspaceID's built-in default ceiling.
// A non-positive limit is rejected and the previous effective value stays
// in force (AC-OFFICE-BUDGET-003.8).
func (s *CostService) SetWorkspaceBudgetDefault(ctx context.Context, workspaceID string, limitSubcents int64) error {
if limitSubcents <= 0 {
return fmt.Errorf("%w: limit_subcents must be positive, got %d", ErrInvalidBudgetPolicy, limitSubcents)
}
return s.repo.SetWorkspaceBudgetDefault(ctx, workspaceID, limitSubcents)
}
// EvaluateDefaultCeiling evaluates workspaceID's built-in default ceiling as
// though it were a workspace-scoped daily block_new_tasks policy
// (AC-OFFICE-BUDGET-003.11), using the same SpendWindowForWorkspace query
// gate 4's workspace-scoped policies use so a policy and the default can
// never disagree about which events count in the same window. Callers only
// invoke this for an unattended run (REQ-OFFICE-BUDGET-003's gate 5 is only
// reached after AC-OFFICE-BUDGET-001.6 has already let an attended run
// through), so the degradation test is evaluated as unattended here rather
// than taking a provenance parameter that every caller would pass the same
// value for.
func (s *CostService) EvaluateDefaultCeiling(ctx context.Context, workspaceID string, at time.Time) (PreLaunchPolicyResult, error) {
limitSubcents, err := s.GetWorkspaceBudgetDefault(ctx, workspaceID)
if err != nil {
return PreLaunchPolicyResult{}, err
}
start, _ := windowStart(models.BudgetPeriodDaily, at)
window, err := s.repo.SpendWindowForWorkspace(ctx, workspaceID, start, true, at)
if err != nil {
return PreLaunchPolicyResult{}, fmt.Errorf("spend window for default ceiling: %w", err)
}
return PreLaunchPolicyResult{
IsDefault: true,
ScopeType: models.BudgetScopeWorkspace,
Period: models.BudgetPeriodDaily,
ActionOnExceed: models.BudgetActionBlockNewTasks,
LimitSubcents: limitSubcents,
PricedSubcents: window.PricedSubcents,
Degraded: window.Degraded,
LimitExceeded: window.PricedSubcents >= limitSubcents,
DegradationBlocked: degradationBlocks(
window.Degraded, window.PricedSubcents, limitSubcents, shared.RunProvenanceUnattended,
),
}, nil
}
@@ -0,0 +1,162 @@
package costs_test
import (
"context"
"testing"
"time"
"github.com/kandev/kandev/internal/office/costs"
"github.com/kandev/kandev/internal/office/models"
)
func TestGetWorkspaceBudgetDefault_NoWriteReturnsShippedConstant(t *testing.T) {
svc, _, _ := newBudgetTestService(t)
ctx := context.Background()
got, err := svc.GetWorkspaceBudgetDefault(ctx, "ws-1")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
}
if got != costs.DefaultCeilingSubcents {
t.Errorf("got = %d, want the shipped constant %d", got, costs.DefaultCeilingSubcents)
}
}
func TestSetWorkspaceBudgetDefault_ThenGetReturnsWrittenValue(t *testing.T) {
svc, _, _ := newBudgetTestService(t)
ctx := context.Background()
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 750_000); err != nil {
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
}
got, err := svc.GetWorkspaceBudgetDefault(ctx, "ws-1")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
}
if got != 750_000 {
t.Errorf("got = %d, want 750000", got)
}
}
// TestSetWorkspaceBudgetDefault_RejectsNonPositiveLimit pins
// AC-OFFICE-BUDGET-003.8: a non-positive write is rejected and the previous
// effective value stays in force.
func TestSetWorkspaceBudgetDefault_RejectsNonPositiveLimit(t *testing.T) {
svc, _, _ := newBudgetTestService(t)
ctx := context.Background()
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 300_000); err != nil {
t.Fatalf("initial SetWorkspaceBudgetDefault: %v", err)
}
for _, bad := range []int64{0, -1} {
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", bad); err == nil {
t.Errorf("SetWorkspaceBudgetDefault(%d) = nil error, want a validation error", bad)
}
}
got, err := svc.GetWorkspaceBudgetDefault(ctx, "ws-1")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
}
if got != 300_000 {
t.Errorf("got = %d, want the previous value 300000 left in force", got)
}
}
func TestEvaluateDefaultCeiling_UnderLimit_Admits(t *testing.T) {
svc, repo, _ := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 100, at.Add(-time.Hour), nil)
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
if err != nil {
t.Fatalf("EvaluateDefaultCeiling: %v", err)
}
if got.LimitExceeded {
t.Error("LimitExceeded = true, want false: spend is far under the 500000-subcent default")
}
if !got.IsDefault {
t.Error("IsDefault = false, want true")
}
if got.PolicyID != "" {
t.Errorf("PolicyID = %q, want empty: the default is not a office_budget_policies row", got.PolicyID)
}
if got.LimitSubcents != costs.DefaultCeilingSubcents {
t.Errorf("LimitSubcents = %d, want the shipped constant %d", got.LimitSubcents, costs.DefaultCeilingSubcents)
}
}
func TestEvaluateDefaultCeiling_AtLimit_Blocks(t *testing.T) {
svc, repo, _ := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", costs.DefaultCeilingSubcents, at.Add(-time.Hour), nil)
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
if err != nil {
t.Fatalf("EvaluateDefaultCeiling: %v", err)
}
if !got.LimitExceeded {
t.Error("LimitExceeded = false, want true: spend reached the default ceiling")
}
}
// TestEvaluateDefaultCeiling_UsesWrittenLimit pins AC-OFFICE-BUDGET-003.5/.7:
// the operator-writable limit, not the shipped constant, is what gets
// evaluated once it has been written.
func TestEvaluateDefaultCeiling_UsesWrittenLimit(t *testing.T) {
svc, repo, _ := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 1_500, at.Add(-time.Hour), nil)
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 1_000); err != nil {
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
}
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
if err != nil {
t.Fatalf("EvaluateDefaultCeiling: %v", err)
}
if !got.LimitExceeded {
t.Error("LimitExceeded = false, want true: spend exceeds the written 1000-subcent limit")
}
if got.LimitSubcents != 1_000 {
t.Errorf("LimitSubcents = %d, want the written value 1000", got.LimitSubcents)
}
}
// TestEvaluateDefaultCeiling_PricingDegradedBlocks pins AC-OFFICE-BUDGET-
// 003.11: the default is evaluated by the same pricing-degradation
// criterion as a policy.
func TestEvaluateDefaultCeiling_PricingDegradedBlocks(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
_ = execSQL
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 400, at.Add(-time.Hour), nil)
unpriced := models.CostSourceUnpriced
mustCreateCostEvent(t, repo, "agent-1", "", 0, at.Add(-30*time.Minute), &unpriced)
if err := svc.SetWorkspaceBudgetDefault(ctx, "ws-1", 700); err != nil {
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
}
got, err := svc.EvaluateDefaultCeiling(ctx, "ws-1", at)
if err != nil {
t.Fatalf("EvaluateDefaultCeiling: %v", err)
}
if got.LimitExceeded {
t.Error("LimitExceeded = true, want false: priced spend alone is under the limit")
}
if !got.DegradationBlocked {
t.Error("DegradationBlocked = false, want true: 2*400 >= 700 with an unpriced event present")
}
}
@@ -0,0 +1,20 @@
package costs
import "github.com/kandev/kandev/internal/office/shared"
// degradationBlocks implements REQ-OFFICE-BUDGET-004: an unpriced event
// inside an unattended run's window means priced spend alone can no longer
// be trusted as a ceiling, so this blocks once priced spend alone already
// reaches half the limit — applied identically to a policy and the
// built-in default, regardless of the policy's configured action
// (AC-OFFICE-BUDGET-004.3).
//
// The `pricedSubcents >= limitSubcents-pricedSubcents` form is algebraically
// `2*pricedSubcents >= limitSubcents`, AC-OFFICE-BUDGET-004.3's
// exact-50%-without-truncation requirement (comparing against limit/2 would
// round down and miss an odd limit's exact threshold) -- written this way so
// it never doubles pricedSubcents, which can overflow int64 and wrap
// negative for extreme inputs.
func degradationBlocks(degraded bool, pricedSubcents, limitSubcents int64, provenance shared.RunProvenance) bool {
return degraded && provenance == shared.RunProvenanceUnattended && pricedSubcents >= limitSubcents-pricedSubcents
}
@@ -0,0 +1,87 @@
package costs
import (
"math"
"testing"
"github.com/kandev/kandev/internal/office/shared"
)
// TestDegradationBlocks pins REQ-OFFICE-BUDGET-004: an unpriced event inside
// an unattended run's window blocks admission once priced spend alone
// reaches 50% of the limit, applying regardless of the policy's configured
// action (AC-OFFICE-BUDGET-004.3).
func TestDegradationBlocks(t *testing.T) {
tests := []struct {
name string
degraded bool
pricedSubcents int64
limitSubcents int64
provenance shared.RunProvenance
want bool
}{
{
name: "degraded unattended at exactly 50% blocks (non-truncating threshold)",
degraded: true, pricedSubcents: 500, limitSubcents: 1000,
provenance: shared.RunProvenanceUnattended, want: true,
},
{
name: "degraded unattended above 50% blocks",
degraded: true, pricedSubcents: 600, limitSubcents: 1000,
provenance: shared.RunProvenanceUnattended, want: true,
},
{
name: "degraded unattended below 50% does not block",
degraded: true, pricedSubcents: 499, limitSubcents: 1000,
provenance: shared.RunProvenanceUnattended, want: false,
},
{
name: "not degraded never blocks regardless of spend",
degraded: false, pricedSubcents: 999999, limitSubcents: 1000,
provenance: shared.RunProvenanceUnattended, want: false,
},
{
name: "attended run is exempt even when degraded and over threshold",
degraded: true, pricedSubcents: 600, limitSubcents: 1000,
provenance: shared.RunProvenanceAttended, want: false,
},
// AC-OFFICE-BUDGET-004.3 requires the exact, non-truncating
// comparison 2*priced >= limit. Every row above uses an even
// limitSubcents (1000), under which the forbidden truncating form
// (priced >= limit/2, i.e. priced >= 500) produces the identical
// pass/fail pattern -- so this table alone would not catch a
// regression to that form. An odd limit is the only input shape
// that distinguishes the two: limit/2 truncates to 500 either way,
// but 2*priced >= 1001 disagrees with priced >= 500 at priced=500.
{
name: "odd limit: priced just below half (truncating form would wrongly block)",
degraded: true, pricedSubcents: 500, limitSubcents: 1001,
provenance: shared.RunProvenanceUnattended, want: false,
},
{
name: "odd limit: priced at the true (non-truncating) half blocks",
degraded: true, pricedSubcents: 501, limitSubcents: 1001,
provenance: shared.RunProvenanceUnattended, want: true,
},
// A doubling form (2*pricedSubcents >= limitSubcents) overflows
// int64 and wraps negative once pricedSubcents exceeds ~half of
// MaxInt64, silently failing open at exactly the inputs this check
// exists to catch. pricedSubcents here is just past MaxInt64's true
// (non-truncating) half, so the correct answer is still "blocks".
{
name: "near MaxInt64: priced just past the true half still blocks (regression for doubling overflow)",
degraded: true, pricedSubcents: math.MaxInt64/2 + 1, limitSubcents: math.MaxInt64,
provenance: shared.RunProvenanceUnattended, want: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := degradationBlocks(tt.degraded, tt.pricedSubcents, tt.limitSubcents, tt.provenance)
if got != tt.want {
t.Errorf("degradationBlocks(%v, %d, %d, %v) = %v, want %v",
tt.degraded, tt.pricedSubcents, tt.limitSubcents, tt.provenance, got, tt.want)
}
})
}
}
+12
View File
@@ -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"`
}
+49 -2
View File
@@ -1,6 +1,7 @@
package costs
import (
"errors"
"net/http"
"github.com/gin-gonic/gin"
@@ -8,6 +9,22 @@ import (
"github.com/kandev/kandev/internal/office/models"
)
// errorJSONKey is the JSON field name every handler in this file reports an
// error under. Named to avoid adding a fresh "error" string literal on top
// of this file's many pre-existing gin.H{"error": ...} call sites (goconst).
const errorJSONKey = "error"
// writeBudgetPolicyError maps validateBudgetPolicyWrite's rejection
// (AC-OFFICE-BUDGET-002.6/.7) to 400; any other error (e.g. a repository
// failure) stays 500.
func writeBudgetPolicyError(c *gin.Context, err error) {
if errors.Is(err, ErrInvalidBudgetPolicy) {
c.JSON(http.StatusBadRequest, gin.H{errorJSONKey: err.Error()})
return
}
c.JSON(http.StatusInternalServerError, gin.H{errorJSONKey: err.Error()})
}
// Handler provides HTTP handlers for cost and budget routes.
type Handler struct {
svc *CostService
@@ -39,6 +56,8 @@ func registerBudgetRoutes(api *gin.RouterGroup, h *Handler) {
api.POST("/workspaces/:wsId/budgets", h.createBudget)
api.PATCH("/budgets/:id", h.updateBudget)
api.DELETE("/budgets/:id", h.deleteBudget)
api.GET("/workspaces/:wsId/budgets/default", h.getDefaultCeiling)
api.PUT("/workspaces/:wsId/budgets/default", h.setDefaultCeiling)
}
// -- Cost handlers --
@@ -159,7 +178,7 @@ func (h *Handler) createBudget(c *gin.Context) {
ActionOnExceed: action,
}
if err := h.svc.CreateBudgetPolicy(c.Request.Context(), policy); err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
writeBudgetPolicyError(c, err)
return
}
c.JSON(http.StatusCreated, gin.H{"budget": policy})
@@ -190,7 +209,7 @@ func (h *Handler) updateBudget(c *gin.Context) {
}
applyBudgetPatch(policy, &req)
if err := h.svc.UpdateBudgetPolicy(c.Request.Context(), policy); err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
writeBudgetPolicyError(c, err)
return
}
c.JSON(http.StatusOK, gin.H{"budget": policy})
@@ -224,3 +243,31 @@ func (h *Handler) deleteBudget(c *gin.Context) {
}
c.JSON(http.StatusOK, gin.H{"ok": true})
}
// getDefaultCeiling reports the built-in default ceiling's current
// effective limit, visible without inspecting the database
// (AC-OFFICE-BUDGET-003.5).
func (h *Handler) getDefaultCeiling(c *gin.Context) {
limitSubcents, err := h.svc.GetWorkspaceBudgetDefault(c.Request.Context(), c.Param("wsId"))
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{errorJSONKey: err.Error()})
return
}
c.JSON(http.StatusOK, DefaultCeilingResponse{LimitSubcents: limitSubcents})
}
// setDefaultCeiling writes the built-in default ceiling's limit through the
// same surface that manages budget policies (AC-OFFICE-BUDGET-003.5), never
// touching office_budget_policies (AC-OFFICE-BUDGET-003.7).
func (h *Handler) setDefaultCeiling(c *gin.Context) {
var req SetDefaultCeilingRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{errorJSONKey: err.Error()})
return
}
if err := h.svc.SetWorkspaceBudgetDefault(c.Request.Context(), c.Param("wsId"), req.LimitSubcents); err != nil {
writeBudgetPolicyError(c, err)
return
}
c.JSON(http.StatusOK, DefaultCeilingResponse(req))
}
@@ -0,0 +1,103 @@
package costs_test
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/gin-gonic/gin"
"github.com/kandev/kandev/internal/office/costs"
)
func newDefaultCeilingTestRouter(t *testing.T) *gin.Engine {
t.Helper()
gin.SetMode(gin.TestMode)
svc, _, _ := newBudgetTestService(t)
router := gin.New()
costs.NewHandler(svc).RegisterRoutes(router.Group("/api/v1"))
return router
}
func doDefaultCeilingRequest(t *testing.T, router *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
t.Helper()
req := httptest.NewRequest(method, path, strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
rec := httptest.NewRecorder()
router.ServeHTTP(rec, req)
return rec
}
func TestGetDefaultCeiling_NoWriteReturnsShippedConstant(t *testing.T) {
router := newDefaultCeilingTestRouter(t)
rec := doDefaultCeilingRequest(t, router, http.MethodGet, "/api/v1/workspaces/ws-1/budgets/default", "")
if rec.Code != http.StatusOK {
t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body.String())
}
var got costs.DefaultCeilingResponse
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if got.LimitSubcents != costs.DefaultCeilingSubcents {
t.Errorf("LimitSubcents = %d, want the shipped constant %d", got.LimitSubcents, costs.DefaultCeilingSubcents)
}
}
func TestSetDefaultCeiling_ThenGetReturnsWrittenValue(t *testing.T) {
router := newDefaultCeilingTestRouter(t)
putRec := doDefaultCeilingRequest(
t, router, http.MethodPut, "/api/v1/workspaces/ws-1/budgets/default", `{"limit_subcents":750000}`,
)
if putRec.Code != http.StatusOK {
t.Fatalf("PUT status = %d, want 200: %s", putRec.Code, putRec.Body.String())
}
getRec := doDefaultCeilingRequest(t, router, http.MethodGet, "/api/v1/workspaces/ws-1/budgets/default", "")
var got costs.DefaultCeilingResponse
if err := json.Unmarshal(getRec.Body.Bytes(), &got); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if got.LimitSubcents != 750_000 {
t.Errorf("LimitSubcents = %d, want 750000", got.LimitSubcents)
}
}
// TestSetDefaultCeiling_RejectsNonPositiveLimit pins AC-OFFICE-BUDGET-003.8:
// a non-positive write is rejected with a validation error over HTTP.
func TestSetDefaultCeiling_RejectsNonPositiveLimit(t *testing.T) {
router := newDefaultCeilingTestRouter(t)
rec := doDefaultCeilingRequest(
t, router, http.MethodPut, "/api/v1/workspaces/ws-1/budgets/default", `{"limit_subcents":0}`,
)
if rec.Code != http.StatusBadRequest {
t.Errorf("status = %d, want 400: %s", rec.Code, rec.Body.String())
}
}
// TestSetDefaultCeiling_DoesNotAppearInBudgetList pins AC-OFFICE-BUDGET-
// 003.7: writing the default never creates a office_budget_policies row,
// so it never shows up in the policy list API's results.
func TestSetDefaultCeiling_DoesNotAppearInBudgetList(t *testing.T) {
router := newDefaultCeilingTestRouter(t)
putRec := doDefaultCeilingRequest(
t, router, http.MethodPut, "/api/v1/workspaces/ws-1/budgets/default", `{"limit_subcents":750000}`,
)
if putRec.Code != http.StatusOK {
t.Fatalf("PUT status = %d, want 200: %s", putRec.Code, putRec.Body.String())
}
listRec := doDefaultCeilingRequest(t, router, http.MethodGet, "/api/v1/workspaces/ws-1/budgets", "")
var got costs.BudgetListResponse
if err := json.Unmarshal(listRec.Body.Bytes(), &got); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if len(got.Budgets) != 0 {
t.Errorf("Budgets = %+v, want empty: the default must never appear in the policy list", got.Budgets)
}
}
@@ -0,0 +1,222 @@
package costs_test
import (
"go/ast"
"go/parser"
"go/token"
"os"
"path/filepath"
"regexp"
"runtime"
"strings"
"testing"
)
// This test implements AC-OFFICE-BUDGET-002.12: it fails the build when the
// set of period values the policy-management surface offers differs from
// the set the write API declares. Both sets are derived by reading their
// respective sources, never from a list maintained alongside them, so
// adding a period value on either side without the other cannot silently
// reproduce the defect AC-OFFICE-BUDGET-002.9 exists to fix.
//
// The declared set comes from models.BudgetPeriod's own Valid() method,
// read via go/ast (same technique as the run-provenance completeness test
// in internal/office/shared): the switch statement's case identifiers are
// resolved against the type's const block, so a value added to the const
// block but never wired into Valid() is correctly excluded from "declared".
//
// The offered set comes from create-budget-form.tsx's period FormField,
// scanned with a regexp scoped to that one block rather than go/ast (the
// file is TypeScript, which go/ast cannot parse).
func thisDir(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("runtime.Caller(0) failed; cannot locate test file for relative source paths")
}
return filepath.Dir(file)
}
// periodConstValues reads path's BudgetPeriod const block and returns a map
// from each declared identifier (e.g. "BudgetPeriodDaily") to its string
// literal value (e.g. "daily"), located by the anchor identifier
// "BudgetPeriodDaily" — never by line number.
func periodConstValues(t *testing.T, path string) map[string]string {
t.Helper()
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
if err != nil {
t.Fatalf("parse %s: %v", path, err)
}
for _, decl := range f.Decls {
gen, ok := decl.(*ast.GenDecl)
if !ok || gen.Tok != token.CONST {
continue
}
values := constBlockValues(gen)
if _, ok := values["BudgetPeriodDaily"]; ok {
return values
}
}
t.Fatalf("BudgetPeriod const block (anchor BudgetPeriodDaily) not found in %s — "+
"block moved, renamed, or deleted", path)
return nil
}
func constBlockValues(gen *ast.GenDecl) map[string]string {
out := map[string]string{}
for _, spec := range gen.Specs {
vs, ok := spec.(*ast.ValueSpec)
if !ok {
continue
}
for i, name := range vs.Names {
if i >= len(vs.Values) {
continue
}
lit, ok := vs.Values[i].(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
continue
}
val := lit.Value[1 : len(lit.Value)-1] // strip surrounding quotes
out[name.Name] = val
}
}
return out
}
// declaredPeriodSet derives BudgetPeriod's declared set from Valid()'s own
// switch statement, resolving each case identifier against the const
// block's values rather than assuming every declared constant is valid.
func declaredPeriodSet(t *testing.T) map[string]bool {
t.Helper()
dir := thisDir(t)
path := filepath.Join(dir, "..", "models", "enums.go")
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
if err != nil {
t.Fatalf("parse %s: %v", path, err)
}
constValues := periodConstValues(t, path)
for _, decl := range f.Decls {
fn, ok := decl.(*ast.FuncDecl)
if !ok || fn.Name.Name != "Valid" || fn.Recv == nil {
continue
}
if !receiverIsBudgetPeriod(fn) {
continue
}
return caseIdentValues(t, fn, constValues)
}
t.Fatalf("BudgetPeriod.Valid method not found in %s — method moved, renamed, or deleted", path)
return nil
}
func receiverIsBudgetPeriod(fn *ast.FuncDecl) bool {
if len(fn.Recv.List) != 1 {
return false
}
ident, ok := fn.Recv.List[0].Type.(*ast.Ident)
return ok && ident.Name == "BudgetPeriod"
}
// caseIdentValues walks fn's body for its switch statement and resolves
// every case identifier against constValues, failing the test outright if
// a case expression isn't a plain identifier this test knows how to
// resolve, per AC-OFFICE-BUDGET-002.12's "shall fail on any value present
// in one set and absent from the other" — an unresolved case must not
// silently shrink the declared set.
func caseIdentValues(t *testing.T, fn *ast.FuncDecl, constValues map[string]string) map[string]bool {
t.Helper()
out := map[string]bool{}
found := false
ast.Inspect(fn.Body, func(n ast.Node) bool {
sw, ok := n.(*ast.SwitchStmt)
if !ok {
return true
}
for _, stmt := range sw.Body.List {
clause, ok := stmt.(*ast.CaseClause)
if !ok {
continue
}
for _, expr := range clause.List {
ident, ok := expr.(*ast.Ident)
if !ok {
t.Fatalf("BudgetPeriod.Valid case expression %v is not a plain identifier "+
"this test can resolve", expr)
}
val, ok := constValues[ident.Name]
if !ok {
t.Fatalf("BudgetPeriod.Valid case identifier %q has no matching const declaration", ident.Name)
}
out[val] = true
}
}
found = true
return false
})
if !found {
t.Fatal("BudgetPeriod.Valid has no switch statement — cannot derive declared period set")
}
return out
}
// offeredPeriodSet reads create-budget-form.tsx's period FormField block —
// scoped between the label naming "office:period" and that FormField's
// closing tag, so the scopeType and actionOnExceed Selects' own
// SelectItem values are never counted — and returns every literal
// SelectItem value in it.
func offeredPeriodSet(t *testing.T) map[string]bool {
t.Helper()
dir := thisDir(t)
path := filepath.Join(dir, "..", "..", "..", "..", "web", "app", "office", "workspace", "costs", "create-budget-form.tsx")
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read %s: %v", path, err)
}
src := string(data)
labelRe := regexp.MustCompile(`label=\{t\("office:period"\)\}`)
loc := labelRe.FindStringIndex(src)
if loc == nil {
t.Fatalf(`period FormField label={t("office:period")} not found in %s — component restructured`, path)
}
rest := src[loc[1]:]
closeIdx := strings.Index(rest, "</FormField>")
if closeIdx == -1 {
t.Fatalf("no closing </FormField> found after the period label in %s", path)
}
block := rest[:closeIdx]
itemRe := regexp.MustCompile(`SelectItem value="([a-z]+)"`)
matches := itemRe.FindAllStringSubmatch(block, -1)
if len(matches) == 0 {
t.Fatalf("no SelectItem value=\"...\" literals found in the period FormField block in %s", path)
}
out := map[string]bool{}
for _, m := range matches {
out[m[1]] = true
}
return out
}
func TestBudgetPeriod_FrontendOfferedSetMatchesDeclaredSet(t *testing.T) {
declared := declaredPeriodSet(t)
offered := offeredPeriodSet(t)
for v := range declared {
if !offered[v] {
t.Errorf("period %q is declared by BudgetPeriod.Valid but not offered by "+
"create-budget-form.tsx's period select", v)
}
}
for v := range offered {
if !declared[v] {
t.Errorf("period %q is offered by create-budget-form.tsx's period select but not "+
"declared by BudgetPeriod.Valid", v)
}
}
}
@@ -0,0 +1,35 @@
package costs
import "github.com/kandev/kandev/internal/office/models"
// policyValidationIssues is every reason classifyStoredPolicy found to skip
// a stored policy (AC-OFFICE-BUDGET-002.5/.11/.14). All fields are detected
// in the same pass, never short-circuited at the first, so a policy
// violating more than one criterion can be named for all of them in a
// single activity entry (AC-OFFICE-BUDGET-002.13). Aliased from models so
// internal/office/service can read a PreLaunchPolicyResult's SkipIssues
// without importing this package.
type policyValidationIssues = models.PolicyValidationIssues
// classifyStoredPolicy implements AC-OFFICE-BUDGET-002.5/.11/.14: a stored
// policy the build cannot evaluate as written — an unrecognized period,
// scope type, or action, a non-positive limit, or an agent/project scope
// with no scope_id — is skipped by the caller rather than evaluated as a
// lifetime window or as matching every run whose corresponding identifier
// is also empty. Unlike validateBudgetPolicyWrite (AC-002.6/.7, which only
// guards new writes), this covers every stored row regardless of how it
// got there — a row written before validation shipped, or by any path that
// bypasses the write API.
func classifyStoredPolicy(policy *models.BudgetPolicy) policyValidationIssues {
issues := policyValidationIssues{
UnrecognizedPeriod: !policy.Period.Valid(),
NonPositiveLimit: policy.LimitSubcents <= 0,
UnrecognizedScope: !policy.ScopeType.Valid(),
UnrecognizedAction: !policy.ActionOnExceed.Valid(),
}
if (policy.ScopeType == models.BudgetScopeAgent || policy.ScopeType == models.BudgetScopeProject) &&
policy.ScopeID == "" {
issues.EmptyScopeID = true
}
return issues
}
@@ -0,0 +1,140 @@
package costs
import (
"testing"
"github.com/kandev/kandev/internal/office/models"
)
// TestClassifyStoredPolicy pins AC-OFFICE-BUDGET-002.5/.11/.14: a stored
// policy the build cannot evaluate as written is skipped, never treated as
// a lifetime window or as matching every run. Every violation on the row is
// detected in the same pass (AC-OFFICE-BUDGET-002.13 names all of them in
// one entry, so the classifier must not stop at the first).
func TestClassifyStoredPolicy(t *testing.T) {
validPolicy := func() *models.BudgetPolicy {
return &models.BudgetPolicy{
ScopeType: models.BudgetScopeWorkspace,
LimitSubcents: 1000,
Period: models.BudgetPeriodDaily,
ActionOnExceed: models.BudgetActionNotifyOnly,
}
}
tests := []struct {
name string
policy func() *models.BudgetPolicy
want policyValidationIssues
}{
{
name: "fully valid workspace policy has no issues",
policy: validPolicy,
want: policyValidationIssues{},
},
{
name: "unrecognized period",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.Period = models.BudgetPeriod("weekly")
return p
},
want: policyValidationIssues{UnrecognizedPeriod: true},
},
{
name: "non-positive limit",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.LimitSubcents = 0
return p
},
want: policyValidationIssues{NonPositiveLimit: true},
},
{
name: "unrecognized scope type",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.ScopeType = models.BudgetScopeType("team")
return p
},
want: policyValidationIssues{UnrecognizedScope: true},
},
{
name: "unrecognized action",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.ActionOnExceed = models.BudgetActionOnExceed("delete_everything")
return p
},
want: policyValidationIssues{UnrecognizedAction: true},
},
{
name: "agent scope with empty scope_id",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.ScopeType = models.BudgetScopeAgent
p.ScopeID = ""
return p
},
want: policyValidationIssues{EmptyScopeID: true},
},
{
name: "project scope with empty scope_id",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.ScopeType = models.BudgetScopeProject
p.ScopeID = ""
return p
},
want: policyValidationIssues{EmptyScopeID: true},
},
{
name: "agent scope with a scope_id has no issues",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.ScopeType = models.BudgetScopeAgent
p.ScopeID = "agent-1"
return p
},
want: policyValidationIssues{},
},
{
name: "workspace scope never needs a scope_id",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.ScopeID = ""
return p
},
want: policyValidationIssues{},
},
{
name: "every violation is detected in one pass, not just the first",
policy: func() *models.BudgetPolicy {
p := validPolicy()
p.Period = models.BudgetPeriod("weekly")
p.LimitSubcents = -5
p.ScopeType = models.BudgetScopeType("team")
p.ActionOnExceed = models.BudgetActionOnExceed("nope")
return p
},
want: policyValidationIssues{
UnrecognizedPeriod: true,
NonPositiveLimit: true,
UnrecognizedScope: true,
UnrecognizedAction: true,
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := classifyStoredPolicy(tt.policy())
if got != tt.want {
t.Errorf("classifyStoredPolicy() = %+v, want %+v", got, tt.want)
}
wantAny := tt.want != (policyValidationIssues{})
if got.Any() != wantAny {
t.Errorf("classifyStoredPolicy().Any() = %v, want %v", got.Any(), wantAny)
}
})
}
}
@@ -0,0 +1,28 @@
package costs
import (
"errors"
"fmt"
"github.com/kandev/kandev/internal/office/models"
)
// ErrInvalidBudgetPolicy wraps every rejection validateBudgetPolicyWrite
// returns, so a caller can distinguish "the write was malformed" from any
// other failure (e.g. a repository error) with errors.Is.
var ErrInvalidBudgetPolicy = errors.New("invalid budget policy")
// validateBudgetPolicyWrite implements AC-OFFICE-BUDGET-002.6/.7: reject a
// create or update before it reaches storage, rather than persisting a
// policy that blocks every run (non-positive limit) or matches every run
// whose corresponding identifier is also empty (agent/project scope with no
// scope_id).
func validateBudgetPolicyWrite(policy *models.BudgetPolicy) error {
if policy.LimitSubcents <= 0 {
return fmt.Errorf("%w: limit_subcents must be positive, got %d", ErrInvalidBudgetPolicy, policy.LimitSubcents)
}
if (policy.ScopeType == models.BudgetScopeAgent || policy.ScopeType == models.BudgetScopeProject) && policy.ScopeID == "" {
return fmt.Errorf("%w: scope_id is required for scope %q", ErrInvalidBudgetPolicy, policy.ScopeType)
}
return nil
}
@@ -0,0 +1,107 @@
package costs
import (
"errors"
"testing"
"github.com/kandev/kandev/internal/office/models"
)
// TestValidateBudgetPolicyWrite pins AC-OFFICE-BUDGET-002.6/.7: create/update
// rejects a non-positive limit and an agent/project scope with an empty
// scope identifier, rather than storing a policy that blocks every run or
// matches every run whose corresponding identifier is also empty.
func TestValidateBudgetPolicyWrite(t *testing.T) {
validBase := func() *models.BudgetPolicy {
return &models.BudgetPolicy{
WorkspaceID: "ws-1",
ScopeType: models.BudgetScopeType(scopeWorkspace),
LimitSubcents: 1000,
Period: models.BudgetPeriodDaily,
}
}
tests := []struct {
name string
policy func() *models.BudgetPolicy
wantErr bool
}{
{
name: "valid workspace-scoped policy is accepted",
policy: validBase,
wantErr: false,
},
{
name: "zero limit is rejected",
policy: func() *models.BudgetPolicy {
p := validBase()
p.LimitSubcents = 0
return p
},
wantErr: true,
},
{
name: "negative limit is rejected",
policy: func() *models.BudgetPolicy {
p := validBase()
p.LimitSubcents = -1
return p
},
wantErr: true,
},
{
name: "agent scope with empty scope_id is rejected",
policy: func() *models.BudgetPolicy {
p := validBase()
p.ScopeType = models.BudgetScopeType(scopeAgent)
p.ScopeID = ""
return p
},
wantErr: true,
},
{
name: "project scope with empty scope_id is rejected",
policy: func() *models.BudgetPolicy {
p := validBase()
p.ScopeType = models.BudgetScopeType(scopeProject)
p.ScopeID = ""
return p
},
wantErr: true,
},
{
name: "agent scope with a scope_id is accepted",
policy: func() *models.BudgetPolicy {
p := validBase()
p.ScopeType = models.BudgetScopeType(scopeAgent)
p.ScopeID = "agent-1"
return p
},
wantErr: false,
},
{
name: "workspace scope never needs a scope_id",
policy: func() *models.BudgetPolicy {
p := validBase()
p.ScopeID = ""
return p
},
wantErr: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := validateBudgetPolicyWrite(tt.policy())
if tt.wantErr && err == nil {
t.Fatal("validateBudgetPolicyWrite() = nil, want error")
}
if !tt.wantErr && err != nil {
t.Fatalf("validateBudgetPolicyWrite() = %v, want nil", err)
}
if tt.wantErr && !errors.Is(err, ErrInvalidBudgetPolicy) {
t.Errorf("validateBudgetPolicyWrite() = %v, want errors.Is(err, ErrInvalidBudgetPolicy)", err)
}
})
}
}
@@ -0,0 +1,252 @@
package costs
import (
"context"
"fmt"
"sort"
"time"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/shared"
)
// windowStart computes the UTC start of period's spend window ending at at,
// per REQ-OFFICE-BUDGET-002 (docs/specs/office/requirements/budget-measurement-integrity.md).
//
// ok is false for any period value not explicitly handled below, including
// one this build has never seen — callers treat that as "skip this policy"
// (AC-OFFICE-BUDGET-002.5), never as an unbounded lifetime window.
func windowStart(period models.BudgetPeriod, at time.Time) (start time.Time, ok bool) {
u := at.UTC()
switch period {
case models.BudgetPeriodDaily:
return time.Date(u.Year(), u.Month(), u.Day(), 0, 0, 0, 0, time.UTC), true
case models.BudgetPeriodMonthly:
return time.Date(u.Year(), u.Month(), 1, 0, 0, 0, 0, time.UTC), true
case models.BudgetPeriodYearly:
return time.Date(u.Year(), time.January, 1, 0, 0, 0, 0, time.UTC), true
case models.BudgetPeriodTotal:
return time.Time{}, true
default:
return time.Time{}, false
}
}
// PreLaunchDecision is EvaluatePreLaunch's admission outcome for one
// candidate run, per REQ-OFFICE-BUDGET-006. Aliased from models so
// internal/office/service can declare a BudgetEvaluator interface method
// returning it without importing this package.
type PreLaunchDecision = models.PreLaunchDecision
const (
PreLaunchDecisionLaunch = models.PreLaunchDecisionLaunch
PreLaunchDecisionBlockedByLimit = models.PreLaunchDecisionBlockedByLimit
PreLaunchDecisionBlockedByDegradation = models.PreLaunchDecisionBlockedByDegradation
)
// PreLaunchPolicyResult is one applicable policy's full evaluation, kept for
// observability. Activity-entry writing and dedup (AC-OFFICE-BUDGET-002.13)
// live one layer up, in the caller that owns side effects — EvaluatePreLaunch
// itself stays a pure read (AC-OFFICE-BUDGET-006.2). Aliased from models,
// see PreLaunchDecision above.
type PreLaunchPolicyResult = models.PreLaunchPolicyResult
// PreLaunchResult is EvaluatePreLaunch's full output. Aliased from models,
// see PreLaunchDecision above.
type PreLaunchResult = models.PreLaunchResult
// preLaunchApplicablePolicies implements AC-OFFICE-BUDGET-001.15:
// workspace-scoped always applies; agent-scoped only when scope_id matches
// the run's agent; project-scoped only when hasProject and scope_id matches
// the run's project. A policy whose scope_type or scope_id is malformed
// enough that no case below could ever match it, regardless of this run's
// agent or project, is included anyway (scopeUnclassifiable) rather than
// silently excluded: evaluateOnePolicy's classifyStoredPolicy call is what
// actually produces AC-OFFICE-BUDGET-002.14's skip entry, and it only runs
// on policies this function returns.
func preLaunchApplicablePolicies(
policies []*models.BudgetPolicy, agentInstanceID, projectID string, hasProject bool,
) []*models.BudgetPolicy {
var out []*models.BudgetPolicy
for _, p := range policies {
if scopeUnclassifiable(p) {
out = append(out, p)
continue
}
switch p.ScopeType {
case models.BudgetScopeWorkspace:
out = append(out, p)
case models.BudgetScopeAgent:
if p.ScopeID == agentInstanceID {
out = append(out, p)
}
case models.BudgetScopeProject:
if hasProject && p.ScopeID == projectID {
out = append(out, p)
}
}
}
return out
}
// scopeUnclassifiable reports whether p's scope_type or scope_id is
// malformed enough that preLaunchApplicablePolicies' switch above has no
// case that could ever match it, independent of this run's agent or
// project: an unrecognized scope_type, or an agent/project scope with no
// scope_id (which could never equal a real, non-empty agent/project
// identifier either way). These are exactly the two classifyStoredPolicy
// issues that are also applicability-blocking, so without this check they
// would be silently excluded here and classifyStoredPolicy would never run
// on them at all -- AC-OFFICE-BUDGET-002.14 requires them to be skipped
// with an operator-visible entry, not dropped with no trace.
func scopeUnclassifiable(p *models.BudgetPolicy) bool {
if !p.ScopeType.Valid() {
return true
}
if (p.ScopeType == models.BudgetScopeAgent || p.ScopeType == models.BudgetScopeProject) && p.ScopeID == "" {
return true
}
return false
}
// spendWindowForPolicy resolves the scope-selected spend window for policy's
// own period, ending at the given instant (AC-OFFICE-BUDGET-002.15). windowStart failing is
// unreachable once classifyStoredPolicy has already passed the policy (both
// switch on the same models.BudgetPeriod.Valid() set); erroring instead of
// panicking keeps that invariant enforced by AC-OFFICE-BUDGET-006.1 rather
// than by construction alone.
func (s *CostService) spendWindowForPolicy(
ctx context.Context, workspaceID string, p *models.BudgetPolicy, at time.Time,
) (models.SpendWindow, error) {
start, ok := windowStart(p.Period, at)
if !ok {
return models.SpendWindow{}, fmt.Errorf("unrecognized period %q for policy %s", p.Period, p.ID)
}
hasStart := p.Period != models.BudgetPeriodTotal
switch p.ScopeType {
case models.BudgetScopeAgent:
return s.repo.SpendWindowForAgent(ctx, p.ScopeID, start, hasStart, at)
case models.BudgetScopeProject:
return s.repo.SpendWindowForProject(ctx, p.ScopeID, start, hasStart, at)
default:
return s.repo.SpendWindowForWorkspace(ctx, workspaceID, start, hasStart, at)
}
}
// evaluateOnePolicy computes p's PreLaunchPolicyResult: skipped (with
// SkipIssues set) if classifyStoredPolicy finds anything wrong, otherwise
// its spend window, limit test, and degradation test. survives is false for
// a skipped policy -- callers exclude those from ordering/selection and
// default-supersession (AC-OFFICE-BUDGET-002.5/.11/.14).
func (s *CostService) evaluateOnePolicy(
ctx context.Context, workspaceID string, p *models.BudgetPolicy, at time.Time, provenance shared.RunProvenance,
) (result PreLaunchPolicyResult, survives bool, err error) {
result = PreLaunchPolicyResult{
PolicyID: p.ID,
ScopeType: p.ScopeType,
Period: p.Period,
ActionOnExceed: p.ActionOnExceed,
CreatedAt: p.CreatedAt,
LimitSubcents: p.LimitSubcents,
}
if issues := classifyStoredPolicy(p); issues.Any() {
result.Skipped = true
result.SkipIssues = issues
return result, false, nil
}
window, werr := s.spendWindowForPolicy(ctx, workspaceID, p, at)
if werr != nil {
return PreLaunchPolicyResult{}, false, &models.UnevaluatedPolicyError{PolicyID: p.ID, Err: werr}
}
result.PricedSubcents = window.PricedSubcents
result.Degraded = window.Degraded
result.LimitExceeded = window.PricedSubcents >= p.LimitSubcents &&
(p.ActionOnExceed == models.BudgetActionPauseAgent || p.ActionOnExceed == models.BudgetActionBlockNewTasks)
result.DegradationBlocked = degradationBlocks(window.Degraded, window.PricedSubcents, p.LimitSubcents, provenance)
return result, true, nil
}
// workspaceDailyBlockingSuperseded implements AC-OFFICE-BUDGET-003.4: true
// when a workspace-scoped, non-skipped, blocking-capable daily policy
// exists among survivors, regardless of whether it fired.
func workspaceDailyBlockingSuperseded(survivors []*PreLaunchPolicyResult) bool {
for _, r := range survivors {
if r.ScopeType == models.BudgetScopeWorkspace && r.Period == models.BudgetPeriodDaily &&
(r.ActionOnExceed == models.BudgetActionPauseAgent || r.ActionOnExceed == models.BudgetActionBlockNewTasks) {
return true
}
}
return false
}
// selectPreLaunchDecision picks the first (in survivors' already-sorted
// created_at ASC, id ASC order) policy whose limit or degradation test
// fired. Every survivor's tests were computed up front, so this is a
// selection over an already-fully-evaluated slice, never a
// short-circuiting loop (AC-OFFICE-BUDGET-001.9/AC-OFFICE-BUDGET-006.1).
// Within one policy, the limit test is checked before the degradation test:
// LimitExceeded implies DegradationBlocked can also be true for the same
// policy, and that combination still reports BlockedByLimit.
func selectPreLaunchDecision(survivors []*PreLaunchPolicyResult) (PreLaunchDecision, *PreLaunchPolicyResult) {
for _, r := range survivors {
switch {
case r.LimitExceeded:
return PreLaunchDecisionBlockedByLimit, r
case r.DegradationBlocked:
return PreLaunchDecisionBlockedByDegradation, r
}
}
return PreLaunchDecisionLaunch, nil
}
// EvaluatePreLaunch implements REQ-OFFICE-BUDGET-006's two-phase policy
// evaluation: lists and filters applicable policies, classifies/skips
// malformed ones, computes spend and degradation for every surviving policy
// up front (never short-circuiting), then selects the first (by created_at
// ASC, id ASC) whose limit or degradation test fires. It does not call the
// existing CheckBudget/evaluatePolicy post-event path (AC-OFFICE-BUDGET-006.2)
// and has no side effects of its own.
func (s *CostService) EvaluatePreLaunch(
ctx context.Context,
workspaceID, agentInstanceID, projectID string,
hasProject bool,
provenance shared.RunProvenance,
at time.Time,
) (PreLaunchResult, error) {
policies, err := s.repo.ListBudgetPolicies(ctx, workspaceID)
if err != nil {
return PreLaunchResult{}, err
}
applicable := preLaunchApplicablePolicies(policies, agentInstanceID, projectID, hasProject)
results := make([]PreLaunchPolicyResult, 0, len(applicable))
survivors := make([]*PreLaunchPolicyResult, 0, len(applicable))
for _, p := range applicable {
result, survives, evalErr := s.evaluateOnePolicy(ctx, workspaceID, p, at, provenance)
if evalErr != nil {
return PreLaunchResult{}, evalErr
}
results = append(results, result)
if survives {
survivors = append(survivors, &results[len(results)-1])
}
}
sort.Slice(survivors, func(i, j int) bool {
if !survivors[i].CreatedAt.Equal(survivors[j].CreatedAt) {
return survivors[i].CreatedAt.Before(survivors[j].CreatedAt)
}
return survivors[i].PolicyID < survivors[j].PolicyID
})
decision, decidingPolicy := selectPreLaunchDecision(survivors)
return PreLaunchResult{
Decision: decision,
DecidingPolicy: decidingPolicy,
Policies: results,
WorkspaceDailyBlockingSuperseded: workspaceDailyBlockingSuperseded(survivors),
}, nil
}
@@ -0,0 +1,383 @@
package costs_test
import (
"context"
"testing"
"time"
"github.com/google/uuid"
"github.com/kandev/kandev/internal/office/costs"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/repository/sqlite"
"github.com/kandev/kandev/internal/office/shared"
)
// mustCreateCostEvent inserts a cost event via the real repository, so
// EvaluatePreLaunch's spend-window queries (which join agent_profiles /
// filter project_id, not a manually-seeded fixture table) resolve it.
func mustCreateCostEvent(
t *testing.T, repo *sqlite.Repository,
agentID, projectID string, costSubcents int64, occurredAt time.Time, costSource *models.CostSource,
) {
t.Helper()
event := &models.CostEvent{
ID: uuid.NewString(), AgentProfileID: agentID, ProjectID: projectID,
CostSubcents: costSubcents, OccurredAt: occurredAt, CostSource: costSource,
}
if err := repo.CreateCostEvent(context.Background(), event); err != nil {
t.Fatalf("create cost event: %v", err)
}
}
// insertRawBudgetPolicy inserts a budget policy row directly via SQL, so
// tests can control created_at (for AC-OFFICE-BUDGET-001.9 ordering) and
// write a stored row validateBudgetPolicyWrite would reject (for
// AC-OFFICE-BUDGET-002.5/.11/.14's "malformed row already in storage" case).
func insertRawBudgetPolicy(
t *testing.T, execSQL func(string, ...interface{}),
workspaceID string, scopeType models.BudgetScopeType, scopeID string,
limitSubcents int64, period models.BudgetPeriod, action models.BudgetActionOnExceed,
createdAt time.Time,
) string {
t.Helper()
id := uuid.NewString()
execSQL(
`INSERT INTO office_budget_policies
(id, workspace_id, scope_type, scope_id, limit_subcents, period, alert_threshold_pct, action_on_exceed, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, 80, ?, ?, ?)`,
id, workspaceID, string(scopeType), scopeID, limitSubcents, string(period), string(action),
createdAt.UTC().Format(time.RFC3339Nano), createdAt.UTC().Format(time.RFC3339Nano),
)
return id
}
func TestEvaluatePreLaunch_NoPolicies_Launches(t *testing.T) {
svc, _, _ := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch", got.Decision)
}
if got.WorkspaceDailyBlockingSuperseded {
t.Error("WorkspaceDailyBlockingSuperseded = true, want false with no policies")
}
}
func TestEvaluatePreLaunch_UnderLimit_Launches(t *testing.T) {
svc, _, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch", got.Decision)
}
}
func TestEvaluatePreLaunch_OverLimitPauseAgent_Blocks(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
policyID := insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
t.Errorf("Decision = %v, want BlockedByLimit", got.Decision)
}
if got.DecidingPolicy == nil || got.DecidingPolicy.PolicyID != policyID {
t.Errorf("DecidingPolicy = %+v, want policy %s", got.DecidingPolicy, policyID)
}
}
// TestEvaluatePreLaunch_Inert covers AC-OFFICE-BUDGET-006.2: a pre-launch
// evaluation is a pure read against the same spend window the post-hoc
// budgets.go path (EvaluateBudget/CheckPreExecutionBudget) also reads, but
// unlike that path it must never itself write a budget.alert/budget.exceeded
// activity entry or pause the agent -- those side effects belong solely to
// the existing cost-recording path, not to an admission decision. Reuses
// TestEvaluatePreLaunch_OverLimitPauseAgent_Blocks's exact over-limit,
// pause_agent fixture (the shape most likely to tempt a shared side-effect
// path) but swaps in a service built with newBudgetTestServiceWithActivity's
// spy so the absence of any LogActivity call is observable, and asserts the
// agent's stored status is unchanged.
func TestEvaluatePreLaunch_Inert(t *testing.T) {
spy := &budgetActivitySpy{}
svc, repo, execSQL := newBudgetTestServiceWithActivity(t, spy)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
t.Fatalf("Decision = %v, want BlockedByLimit (fixture must actually be over limit to be a meaningful inertness check)", got.Decision)
}
if len(spy.calls) != 0 {
t.Errorf("EvaluatePreLaunch logged %d activity entries, want 0: %+v", len(spy.calls), spy.calls)
}
agent, err := repo.GetAgentInstance(ctx, "agent-1")
if err != nil {
t.Fatalf("get agent: %v", err)
}
if agent.Status != models.AgentStatusIdle {
t.Errorf("agent status = %q, want unchanged %q -- a pre-launch evaluation must never pause an agent",
agent.Status, models.AgentStatusIdle)
}
}
func TestEvaluatePreLaunch_OverLimitNotifyOnly_Launches(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
models.BudgetPeriodDaily, models.BudgetActionNotifyOnly, at.Add(-time.Hour))
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch (notify_only never blocks on limit alone)", got.Decision)
}
}
// TestEvaluatePreLaunch_FirstFiringPolicyWins pins AC-OFFICE-BUDGET-001.9:
// policies are evaluated in (created_at ASC, id ASC) order and the FIRST
// one whose limit or degradation test fires decides, even though a
// later-created policy would also fire.
func TestEvaluatePreLaunch_FirstFiringPolicyWins(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
earlyID := insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-2*time.Hour))
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 500,
models.BudgetPeriodDaily, models.BudgetActionBlockNewTasks, at.Add(-time.Hour))
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
t.Fatalf("Decision = %v, want BlockedByLimit", got.Decision)
}
if got.DecidingPolicy == nil || got.DecidingPolicy.PolicyID != earlyID {
t.Errorf("DecidingPolicy = %+v, want the earlier-created policy %s", got.DecidingPolicy, earlyID)
}
}
// TestEvaluatePreLaunch_MalformedPolicySkipped pins AC-OFFICE-BUDGET-002.5/
// .11/.14: a stored policy the build cannot evaluate is skipped -- excluded
// from ordering/selection and from default-supersession -- not treated as a
// lifetime window or blocking policy.
func TestEvaluatePreLaunch_MalformedPolicySkipped(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
// Non-positive limit: malformed, must be skipped rather than blocking
// every run.
malformedID := insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", -1,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch (malformed policy must not block)", got.Decision)
}
if got.WorkspaceDailyBlockingSuperseded {
t.Error("WorkspaceDailyBlockingSuperseded = true, want false: the only daily policy is skipped")
}
found := false
for _, p := range got.Policies {
if p.PolicyID == malformedID {
found = true
if !p.Skipped {
t.Error("malformed policy result has Skipped = false, want true")
}
if !p.SkipIssues.NonPositiveLimit {
t.Error("malformed policy result SkipIssues.NonPositiveLimit = false, want true")
}
}
}
if !found {
t.Error("malformed policy is absent from Policies; observability needs it present with Skipped=true")
}
}
func TestEvaluatePreLaunch_AgentScopeAppliesOnlyToMatchingAgent(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
createBudgetTestAgent(t, repo, "ws-1", "agent-2")
mustCreateCostEvent(t, repo, "agent-1", "", 1500, at.Add(-30*time.Minute), nil)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeAgent, "agent-2", 1000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch: agent-2's policy must not apply to agent-1's run", got.Decision)
}
if len(got.Policies) != 0 {
t.Errorf("Policies = %+v, want empty: a non-matching agent policy is not applicable at all", got.Policies)
}
}
func TestEvaluatePreLaunch_ProjectScopeRequiresHasProject(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "proj-1", 1500, at.Add(-30*time.Minute), nil)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeProject, "proj-1", 1000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
// hasProject=false: a genuinely project-less run must never match a
// project policy, even though scope_id happens to be non-empty.
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch when hasProject=false", got.Decision)
}
// hasProject=true with the matching project: now it applies and fires.
got, err = svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "proj-1", true, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionBlockedByLimit {
t.Errorf("Decision = %v, want BlockedByLimit when hasProject=true and project matches", got.Decision)
}
}
// TestEvaluatePreLaunch_WorkspaceDailyBlockingSupersededIgnoresWhetherItFired
// pins AC-OFFICE-BUDGET-003.4: supersession is by a blocking-capable daily
// policy EXISTING among survivors, not by it having fired.
func TestEvaluatePreLaunch_WorkspaceDailyBlockingSupersededIgnoresWhetherItFired(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 10, at.Add(-30*time.Minute), nil)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1_000_000,
models.BudgetPeriodDaily, models.BudgetActionPauseAgent, at.Add(-time.Hour))
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("Decision = %v, want Launch: spend is far under the limit", got.Decision)
}
if !got.WorkspaceDailyBlockingSuperseded {
t.Error("WorkspaceDailyBlockingSuperseded = false, want true: a blocking-capable daily policy exists regardless of firing")
}
}
// TestEvaluatePreLaunch_WorkspaceDailyNotifyOnly_DoesNotSupersedeDefault pins
// AC-OFFICE-BUDGET-003.4's negative case: supersession requires a
// blocking-capable action (pause_agent or block_new_tasks). A workspace-scoped
// daily policy configured notify_only cannot block on its own, so it must not
// suppress the built-in default ceiling either.
func TestEvaluatePreLaunch_WorkspaceDailyNotifyOnly_DoesNotSupersedeDefault(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 10, at.Add(-30*time.Minute), nil)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1_000_000,
models.BudgetPeriodDaily, models.BudgetActionNotifyOnly, at.Add(-time.Hour))
got, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if got.WorkspaceDailyBlockingSuperseded {
t.Error("WorkspaceDailyBlockingSuperseded = true, want false: a notify_only daily policy cannot block, so it must not supersede the default")
}
}
// TestEvaluatePreLaunch_DegradationBlocksEvenNotifyOnly pins
// AC-OFFICE-BUDGET-004.3: pricing degradation applies regardless of the
// policy's configured action, and only for an unattended run.
func TestEvaluatePreLaunch_DegradationBlocksEvenNotifyOnly(t *testing.T) {
svc, repo, execSQL := newBudgetTestService(t)
ctx := context.Background()
at := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
createBudgetTestAgent(t, repo, "ws-1", "agent-1")
mustCreateCostEvent(t, repo, "agent-1", "", 500, at.Add(-30*time.Minute), nil)
unpriced := models.CostSourceUnpriced
mustCreateCostEvent(t, repo, "agent-1", "", 0, at.Add(-20*time.Minute), &unpriced)
insertRawBudgetPolicy(t, execSQL, "ws-1", models.BudgetScopeWorkspace, "", 1000,
models.BudgetPeriodDaily, models.BudgetActionNotifyOnly, at.Add(-time.Hour))
gotUnattended, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceUnattended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if gotUnattended.Decision != costs.PreLaunchDecisionBlockedByDegradation {
t.Errorf("unattended Decision = %v, want BlockedByDegradation", gotUnattended.Decision)
}
gotAttended, err := svc.EvaluatePreLaunch(ctx, "ws-1", "agent-1", "", false, shared.RunProvenanceAttended, at)
if err != nil {
t.Fatalf("EvaluatePreLaunch: %v", err)
}
if gotAttended.Decision != costs.PreLaunchDecisionLaunch {
t.Errorf("attended Decision = %v, want Launch: attended runs are exempt from degradation blocking", gotAttended.Decision)
}
}
@@ -0,0 +1,99 @@
package costs
import (
"testing"
"time"
"github.com/kandev/kandev/internal/office/models"
)
// TestWindowStart pins AC-OFFICE-BUDGET-002.1-.4/.8: each period computes its
// UTC window start by name, and total is selected by name rather than by
// falling through an unrecognized period to a lifetime window.
func TestWindowStart(t *testing.T) {
at := time.Date(2026, 3, 15, 14, 30, 0, 0, time.UTC)
tests := []struct {
name string
period models.BudgetPeriod
wantStart time.Time
wantOK bool
}{
{
name: "daily is most recent UTC midnight",
period: models.BudgetPeriodDaily,
wantStart: time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC),
wantOK: true,
},
{
name: "monthly is the 1st of the UTC month",
period: models.BudgetPeriodMonthly,
wantStart: time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC),
wantOK: true,
},
{
name: "yearly is 1 Jan UTC",
period: models.BudgetPeriodYearly,
wantStart: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
wantOK: true,
},
{
name: "total is unbounded below, selected by name",
period: models.BudgetPeriodTotal,
wantStart: time.Time{},
wantOK: true,
},
{
name: "unrecognized period is not ok, never lifetime",
period: models.BudgetPeriod("weekly"),
wantOK: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
start, ok := windowStart(tt.period, at)
if ok != tt.wantOK {
t.Fatalf("windowStart(%q) ok = %v, want %v", tt.period, ok, tt.wantOK)
}
if ok && !start.Equal(tt.wantStart) {
t.Errorf("windowStart(%q) start = %v, want %v", tt.period, start, tt.wantStart)
}
})
}
}
// TestWindowStart_DailyConvertsToUTCFirst pins that a non-UTC instant is
// converted to UTC before the midnight boundary is computed, so a run
// evaluated late in a non-UTC day doesn't fall into the wrong UTC day.
func TestWindowStart_DailyConvertsToUTCFirst(t *testing.T) {
loc := time.FixedZone("UTC-5", -5*60*60)
at := time.Date(2026, 3, 15, 23, 0, 0, 0, loc) // 2026-03-16T04:00:00Z
start, ok := windowStart(models.BudgetPeriodDaily, at)
if !ok {
t.Fatal("windowStart(daily) ok = false, want true")
}
want := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
if !start.Equal(want) {
t.Errorf("windowStart(daily) start = %v, want %v", start, want)
}
}
// TestSelectPreLaunchDecision_LimitTestedBeforeDegradation pins the
// within-policy precedence: LimitExceeded implies DegradationBlocked can
// also be true for the same policy (priced>=limit algebraically implies
// 2*priced>=limit), so a survivor with both set must still report
// BlockedByLimit, never BlockedByDegradation.
func TestSelectPreLaunchDecision_LimitTestedBeforeDegradation(t *testing.T) {
both := &PreLaunchPolicyResult{PolicyID: "policy-both", LimitExceeded: true, DegradationBlocked: true}
decision, deciding := selectPreLaunchDecision([]*PreLaunchPolicyResult{both})
if decision != PreLaunchDecisionBlockedByLimit {
t.Errorf("decision = %v, want BlockedByLimit when a survivor has both LimitExceeded and DegradationBlocked set", decision)
}
if deciding != both {
t.Errorf("deciding policy = %+v, want %+v", deciding, both)
}
}
@@ -32,6 +32,17 @@ type Repository interface {
UpdateBudgetPolicy(ctx context.Context, policy *BudgetPolicy) error
DeleteBudgetPolicy(ctx context.Context, id string) error
UpdateAgentStatusFields(ctx context.Context, agentID, status, pauseReason string) error
SpendWindowForWorkspace(
ctx context.Context, workspaceID string, start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error)
SpendWindowForAgent(
ctx context.Context, agentInstanceID string, start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error)
SpendWindowForProject(
ctx context.Context, projectID string, start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error)
GetWorkspaceBudgetDefault(ctx context.Context, workspaceID string) (limitSubcents int64, found bool, err error)
SetWorkspaceBudgetDefault(ctx context.Context, workspaceID string, limitSubcents int64) error
}
// CostService handles cost recording, summaries, and budget evaluation.
+5 -2
View File
@@ -164,11 +164,14 @@ func (s CostSource) Valid() bool {
// BudgetPeriod is the time window a BudgetPolicy limit applies to.
type BudgetPeriod string
// Budget period values.
// Budget period values. BudgetPeriodTotal (AC-OFFICE-BUDGET-002.8) selects
// an unbounded-below window by name, rather than by falling through from an
// unrecognized period value.
const (
BudgetPeriodDaily BudgetPeriod = "daily"
BudgetPeriodMonthly BudgetPeriod = "monthly"
BudgetPeriodYearly BudgetPeriod = "yearly"
BudgetPeriodTotal BudgetPeriod = "total"
)
// String implements fmt.Stringer.
@@ -177,7 +180,7 @@ func (p BudgetPeriod) String() string { return string(p) }
// Valid reports whether p is one of the declared BudgetPeriod values.
func (p BudgetPeriod) Valid() bool {
switch p {
case BudgetPeriodDaily, BudgetPeriodMonthly, BudgetPeriodYearly:
case BudgetPeriodDaily, BudgetPeriodMonthly, BudgetPeriodYearly, BudgetPeriodTotal:
return true
}
return false
@@ -0,0 +1,35 @@
package models_test
import (
"testing"
"github.com/kandev/kandev/internal/office/models"
)
// TestBudgetPeriod_Total pins AC-OFFICE-BUDGET-002.8: `total` is a declared
// period value, not a fallthrough from an unrecognized one.
func TestBudgetPeriod_Total(t *testing.T) {
if !models.BudgetPeriodTotal.Valid() {
t.Errorf("BudgetPeriodTotal.Valid() = false, want true")
}
if models.BudgetPeriodTotal.String() != "total" {
t.Errorf("BudgetPeriodTotal.String() = %q, want \"total\"", models.BudgetPeriodTotal.String())
}
}
func TestBudgetPeriod_ValidSet(t *testing.T) {
valid := []models.BudgetPeriod{
models.BudgetPeriodDaily,
models.BudgetPeriodMonthly,
models.BudgetPeriodYearly,
models.BudgetPeriodTotal,
}
for _, p := range valid {
if !p.Valid() {
t.Errorf("%q.Valid() = false, want true", p)
}
}
if models.BudgetPeriod("weekly").Valid() {
t.Error(`BudgetPeriod("weekly").Valid() = true, want false`)
}
}
@@ -377,6 +377,21 @@ type BudgetPolicy struct {
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}
// SpendWindow reports one scope's priced spend and degradation state for a
// single [start, before) window, in one query round-trip. Shared between
// internal/office/repository/sqlite (the query implementations) and
// internal/office/costs (the Repository interface and EvaluatePreLaunch),
// so neither package needs to import the other's package for this one
// return type. AC-OFFICE-BUDGET-002.10/.15, REQ-OFFICE-BUDGET-004.
type SpendWindow struct {
// PricedSubcents excludes any event whose cost_source is 'unpriced'
// (AC-OFFICE-BUDGET-004.1); a NULL cost_source is treated as priced.
PricedSubcents int64
// Degraded is true when the window contains at least one unpriced
// event, determined from cost_source, never from estimated.
Degraded bool
}
// Run represents a run queue entry.
type Run struct {
ID string `json:"id" db:"id"`
@@ -0,0 +1,89 @@
package models
import (
"fmt"
"time"
)
// PreLaunchDecision is the pre-launch admission evaluator's outcome for one
// candidate run, per REQ-OFFICE-BUDGET-006. Declared here (rather than in
// internal/office/costs, where it is computed) so internal/office/service
// can declare a BudgetEvaluator interface method returning it without
// importing internal/office/costs — the same cross-package sharing this
// file's other types (SpendWindow, BudgetPolicy) already use.
type PreLaunchDecision string
const (
PreLaunchDecisionLaunch PreLaunchDecision = "launch"
PreLaunchDecisionBlockedByLimit PreLaunchDecision = "blocked_by_limit"
PreLaunchDecisionBlockedByDegradation PreLaunchDecision = "blocked_by_degradation"
)
// PreLaunchPolicyResult is one applicable policy's full pre-launch
// evaluation, kept for observability.
type PreLaunchPolicyResult struct {
PolicyID string
ScopeType BudgetScopeType
Period BudgetPeriod
ActionOnExceed BudgetActionOnExceed
CreatedAt time.Time
Skipped bool
SkipIssues PolicyValidationIssues
PricedSubcents int64
LimitSubcents int64
Degraded bool
LimitExceeded bool
DegradationBlocked bool
// IsDefault is true when this result is the built-in default ceiling,
// never a stored office_budget_policies row. PolicyID is "" in that case
// (AC-OFFICE-BUDGET-003.7's stable identifier distinct from any policy row).
IsDefault bool
}
// PreLaunchResult is the pre-launch evaluator's full output for one run.
type PreLaunchResult struct {
Decision PreLaunchDecision
DecidingPolicy *PreLaunchPolicyResult
Policies []PreLaunchPolicyResult
// WorkspaceDailyBlockingSuperseded is true when a workspace-scoped,
// non-skipped, blocking-capable (pause_agent/block_new_tasks) daily
// policy exists among the surviving set, independent of whether it
// fired: AC-OFFICE-BUDGET-003.4 supersedes the built-in default by
// existing, not by blocking.
WorkspaceDailyBlockingSuperseded bool
}
// PolicyValidationIssues enumerates every reason classifyStoredPolicy found
// a stored policy row cannot be evaluated as written (AC-OFFICE-BUDGET-002.5,
// -002.11, -002.14). Declared here for the same cross-package reason as
// PreLaunchPolicyResult above.
type PolicyValidationIssues struct {
UnrecognizedPeriod bool
NonPositiveLimit bool
UnrecognizedScope bool
UnrecognizedAction bool
EmptyScopeID bool
}
// Any reports whether classifyStoredPolicy found at least one issue.
func (i PolicyValidationIssues) Any() bool {
return i.UnrecognizedPeriod || i.NonPositiveLimit || i.UnrecognizedScope ||
i.UnrecognizedAction || i.EmptyScopeID
}
// UnevaluatedPolicyError names the applicable policy a pre-launch evaluation
// attempted, but failed, to evaluate — as opposed to a plain evaluator
// invocation fault (e.g. listing policies itself failing), which carries no
// policy identity. AC-OFFICE-BUDGET-006.1/.4/.5 require the two be
// distinguishable and require the former to name the policy; a caller
// extracts PolicyID via errors.As.
type UnevaluatedPolicyError struct {
PolicyID string
Err error
}
func (e *UnevaluatedPolicyError) Error() string {
return fmt.Sprintf("unevaluated policy %s: %v", e.PolicyID, e.Err)
}
func (e *UnevaluatedPolicyError) Unwrap() error { return e.Err }
@@ -120,6 +120,25 @@ func (r *Repository) ListActivityEntriesByType(ctx context.Context, workspaceID,
return entries, nil
}
// HasActivityToday reports whether an activity entry already exists for
// workspaceID with this exact action and targetID, created at or after
// dayStart. Used for AC-OFFICE-BUDGET-002.13/-004.8's at-most-once-per-
// policy-per-UTC-day dedup bound; best-effort under concurrency like the
// bound itself.
func (r *Repository) HasActivityToday(
ctx context.Context, workspaceID, action, targetID string, dayStart time.Time,
) (bool, error) {
var count int
err := r.ro.GetContext(ctx, &count, r.ro.Rebind(`
SELECT COUNT(*) FROM office_activity_log
WHERE workspace_id = ? AND action = ? AND target_id = ? AND created_at >= ?
`), workspaceID, action, targetID, dayStart)
if err != nil {
return false, err
}
return count > 0, nil
}
// ListActivityEntriesByTarget returns activity entries for one target in a workspace.
func (r *Repository) ListActivityEntriesByTarget(ctx context.Context, workspaceID, targetID string, limit int) ([]*models.ActivityEntry, error) {
if limit <= 0 {
@@ -187,7 +187,11 @@ func (r *Repository) GetAgentInstance(ctx context.Context, id string) (*models.A
query := `SELECT ` + agentInstanceColumns + ` FROM agent_profiles WHERE id = ? AND ` + agentInstanceFilter
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(query), id).StructScan(&agent)
if err == sql.ErrNoRows {
return nil, fmt.Errorf("agent instance not found: %s", id)
// Wrapping (not just formatting) sql.ErrNoRows lets callers tell "no
// such agent" apart from a transient I/O failure via errors.Is,
// without a second lookup or a new sentinel type (AC-OFFICE-BUDGET-
// 001.13's two dispositions require exactly that distinction).
return nil, fmt.Errorf("agent instance not found: %s: %w", id, sql.ErrNoRows)
}
return &agent, err
}
@@ -478,7 +482,9 @@ func (r *Repository) GetAgentInstanceByNameAny(
query := `SELECT ` + agentInstanceColumns + ` FROM agent_profiles WHERE name = ? AND ` + agentInstanceFilter + ` LIMIT 1`
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(query), name).StructScan(&agent)
if err == sql.ErrNoRows {
return nil, fmt.Errorf("agent instance not found: %s", name)
// See GetAgentInstance above: wrapped so GetAgentFromConfig can
// distinguish "not found" from a transient error via errors.Is.
return nil, fmt.Errorf("agent instance not found: %s: %w", name, sql.ErrNoRows)
}
return &agent, err
}
@@ -324,6 +324,15 @@ func (r *Repository) createCostTables() error {
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL
);
-- Built-in default spend ceiling (REQ-OFFICE-BUDGET-003): a stable
-- per-workspace identifier distinct from any office_budget_policies row
-- (AC-OFFICE-BUDGET-003.7), never listed alongside operator policies.
CREATE TABLE IF NOT EXISTS office_budget_default_settings (
workspace_id TEXT PRIMARY KEY,
limit_subcents INTEGER NOT NULL,
updated_at TIMESTAMP NOT NULL
);
`)
return err
}
@@ -0,0 +1,42 @@
package sqlite
import (
"context"
"database/sql"
"time"
)
// GetWorkspaceBudgetDefault returns the effective built-in default ceiling
// for workspaceID, in subcents. It never returns an error for "no row
// written yet" -- the caller substitutes the shipped constant in that case
// (AC-OFFICE-BUDGET-003.9), so an absent row is reported as (0, false, nil),
// not an error.
func (r *Repository) GetWorkspaceBudgetDefault(ctx context.Context, workspaceID string) (int64, bool, error) {
var limitSubcents int64
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(
`SELECT limit_subcents FROM office_budget_default_settings WHERE workspace_id = ?`,
), workspaceID).Scan(&limitSubcents)
if err == sql.ErrNoRows {
return 0, false, nil
}
if err != nil {
return 0, false, err
}
return limitSubcents, true, nil
}
// SetWorkspaceBudgetDefault writes workspaceID's built-in default ceiling.
// The single-statement upsert is what makes AC-OFFICE-BUDGET-003.10's
// last-write-wins hold without a read-modify-write race: two concurrent
// writers each execute one INSERT ... ON CONFLICT statement, and SQLite/
// Postgres both serialize those against the same primary key.
func (r *Repository) SetWorkspaceBudgetDefault(ctx context.Context, workspaceID string, limitSubcents int64) error {
_, err := r.db.ExecContext(ctx, r.db.Rebind(`
INSERT INTO office_budget_default_settings (workspace_id, limit_subcents, updated_at)
VALUES (?, ?, ?)
ON CONFLICT(workspace_id) DO UPDATE SET
limit_subcents = excluded.limit_subcents,
updated_at = excluded.updated_at
`), workspaceID, limitSubcents, time.Now().UTC())
return err
}
@@ -0,0 +1,83 @@
package sqlite_test
import (
"context"
"testing"
)
func TestGetWorkspaceBudgetDefault_NoRowReturnsNotFound(t *testing.T) {
repo := newTestRepo(t)
ctx := context.Background()
limitSubcents, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-1")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
}
if found {
t.Errorf("found = true, want false: no row has been written for this workspace")
}
if limitSubcents != 0 {
t.Errorf("limitSubcents = %d, want 0 when not found", limitSubcents)
}
}
func TestSetWorkspaceBudgetDefault_ThenGetReturnsWrittenValue(t *testing.T) {
repo := newTestRepo(t)
ctx := context.Background()
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 750_000); err != nil {
t.Fatalf("SetWorkspaceBudgetDefault: %v", err)
}
limitSubcents, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-1")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
}
if !found {
t.Error("found = false, want true after a write")
}
if limitSubcents != 750_000 {
t.Errorf("limitSubcents = %d, want 750000", limitSubcents)
}
}
// TestSetWorkspaceBudgetDefault_SecondWriteWins pins AC-OFFICE-BUDGET-003.10:
// the upsert is a single statement, so the last write in commit order is the
// effective value, and no intermediate state leaves the workspace with no
// effective row.
func TestSetWorkspaceBudgetDefault_SecondWriteWins(t *testing.T) {
repo := newTestRepo(t)
ctx := context.Background()
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 100_000); err != nil {
t.Fatalf("first SetWorkspaceBudgetDefault: %v", err)
}
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 200_000); err != nil {
t.Fatalf("second SetWorkspaceBudgetDefault: %v", err)
}
limitSubcents, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-1")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault: %v", err)
}
if !found || limitSubcents != 200_000 {
t.Errorf("limitSubcents = %d, found = %v, want 200000, true", limitSubcents, found)
}
}
func TestSetWorkspaceBudgetDefault_ScopedPerWorkspace(t *testing.T) {
repo := newTestRepo(t)
ctx := context.Background()
if err := repo.SetWorkspaceBudgetDefault(ctx, "ws-1", 100_000); err != nil {
t.Fatalf("SetWorkspaceBudgetDefault ws-1: %v", err)
}
_, found, err := repo.GetWorkspaceBudgetDefault(ctx, "ws-2")
if err != nil {
t.Fatalf("GetWorkspaceBudgetDefault ws-2: %v", err)
}
if found {
t.Error("found = true for ws-2, want false: a write to ws-1 must not leak")
}
}
@@ -0,0 +1,65 @@
package sqlite
import (
"context"
"time"
"github.com/kandev/kandev/internal/office/models"
)
// spendWindowQuery is shared by SpendWindowForWorkspace/Agent/Project: each
// caller supplies its own WHERE-clause scope predicate and args, sharing the
// SELECT and the half-open occurred_at bound so a policy and the built-in
// default can never disagree about which events count in the same window
// (AC-OFFICE-BUDGET-001.9). hasStart=false (the `total` period) omits the
// lower bound.
func (r *Repository) spendWindowQuery(
ctx context.Context, scopeWhere string, scopeArgs []interface{},
start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error) {
query := `
SELECT
COALESCE(SUM(CASE WHEN e.cost_source = 'unpriced' THEN 0 ELSE e.cost_subcents END), 0) AS priced_subcents,
COALESCE(SUM(CASE WHEN e.cost_source = 'unpriced' THEN 1 ELSE 0 END), 0) > 0 AS degraded
FROM office_cost_events e
` + scopeWhere + ` AND e.occurred_at < ?`
args := append(append([]interface{}{}, scopeArgs...), before.UTC())
if hasStart {
query += ` AND e.occurred_at >= ?`
args = append(args, start.UTC())
}
var out models.SpendWindow
err := r.ro.QueryRowxContext(ctx, r.ro.Rebind(query), args...).Scan(&out.PricedSubcents, &out.Degraded)
return out, err
}
// SpendWindowForWorkspace scopes by the event's agent's workspace via
// agent_profiles, never via tasks — closing the orphaned-cost-event gap a
// tasks join produces (W4 human disposition; see costs.go's SumCostsSince
// doc comment for the gap this deliberately does not share).
func (r *Repository) SpendWindowForWorkspace(
ctx context.Context, workspaceID string, start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error) {
const where = `JOIN agent_profiles a ON a.id = e.agent_profile_id WHERE a.workspace_id = ?`
return r.spendWindowQuery(ctx, where, []interface{}{workspaceID}, start, hasStart, before)
}
// SpendWindowForAgent scopes directly on office_cost_events.agent_profile_id.
func (r *Repository) SpendWindowForAgent(
ctx context.Context, agentInstanceID string, start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error) {
const where = `WHERE e.agent_profile_id = ?`
return r.spendWindowQuery(ctx, where, []interface{}{agentInstanceID}, start, hasStart, before)
}
// SpendWindowForProject scopes directly on office_cost_events.project_id,
// the value recorded on the cost event itself at write time — never the
// event's task's current project_id — so reparenting a task cannot move
// historical spend between ceilings (AC-OFFICE-BUDGET-002.15).
func (r *Repository) SpendWindowForProject(
ctx context.Context, projectID string, start time.Time, hasStart bool, before time.Time,
) (models.SpendWindow, error) {
const where = `WHERE e.project_id = ?`
return r.spendWindowQuery(ctx, where, []interface{}{projectID}, start, hasStart, before)
}
@@ -0,0 +1,196 @@
package sqlite_test
import (
"context"
"testing"
"time"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/repository/sqlite"
)
// spendWindowFixture seeds the six-event scenario AC-OFFICE-BUDGET-002.10/.15
// and REQ-OFFICE-BUDGET-004 exercise: two agents in two workspaces, two
// projects, one event before the window, one exactly at the window's
// exclusive upper bound, and one unpriced event inside the window.
//
// e1 agent-1 ws-1 proj-1 T0-2h cost=100 priced (before window)
// e2 agent-1 ws-1 proj-1 T0+1h cost=200 priced (in window)
// e3 agent-1 ws-1 proj-2 T0+1h cost=50 priced (in window, other project)
// e4 agent-2 ws-2 proj-3 T0+1h cost=999 priced (in window, other workspace)
// e5 agent-1 ws-1 proj-1 T1 cost=500 priced (at exclusive upper bound)
// e6 agent-1 ws-1 proj-1 T0+2h cost=0 unpriced (in window)
func spendWindowFixture(t *testing.T, repo *sqlite.Repository) (t0, t1 time.Time) {
t.Helper()
ctx := context.Background()
createSpendWindowTestAgent(t, repo, "ws-1", "agent-1")
createSpendWindowTestAgent(t, repo, "ws-2", "agent-2")
t0 = time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
t1 = time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
unpriced := models.CostSourceUnpriced
events := []*models.CostEvent{
{ID: "e1", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 100, OccurredAt: t0.Add(-2 * time.Hour)},
{ID: "e2", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 200, OccurredAt: t0.Add(1 * time.Hour)},
{ID: "e3", AgentProfileID: "agent-1", ProjectID: "proj-2", CostSubcents: 50, OccurredAt: t0.Add(1 * time.Hour)},
{ID: "e4", AgentProfileID: "agent-2", ProjectID: "proj-3", CostSubcents: 999, OccurredAt: t0.Add(1 * time.Hour)},
{ID: "e5", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 500, OccurredAt: t1},
{ID: "e6", AgentProfileID: "agent-1", ProjectID: "proj-1", CostSubcents: 0, OccurredAt: t0.Add(2 * time.Hour), CostSource: &unpriced},
}
for _, e := range events {
if err := repo.CreateCostEvent(ctx, e); err != nil {
t.Fatalf("create cost event %s: %v", e.ID, err)
}
}
return t0, t1
}
func createSpendWindowTestAgent(t *testing.T, repo *sqlite.Repository, wsID, agentID string) {
t.Helper()
agent := &models.AgentInstance{
ID: agentID,
WorkspaceID: wsID,
Name: "test-" + agentID,
Role: models.AgentRoleWorker,
Status: models.AgentStatusIdle,
}
if err := repo.CreateAgentInstance(context.Background(), agent); err != nil {
t.Fatalf("create test agent %s: %v", agentID, err)
}
}
func TestSpendWindowForWorkspace(t *testing.T) {
repo := newTestRepo(t)
t0, t1 := spendWindowFixture(t, repo)
ctx := context.Background()
got, err := repo.SpendWindowForWorkspace(ctx, "ws-1", t0, true, t1)
if err != nil {
t.Fatalf("SpendWindowForWorkspace: %v", err)
}
if got.PricedSubcents != 250 {
t.Errorf("PricedSubcents = %d, want 250 (e2=200 + e3=50 + e6=0; excludes e1 before window, e4 other workspace, e5 at upper bound)", got.PricedSubcents)
}
if !got.Degraded {
t.Error("Degraded = false, want true (e6 is unpriced and in window)")
}
}
func TestSpendWindowForWorkspace_TotalPeriodOmitsLowerBound(t *testing.T) {
repo := newTestRepo(t)
_, t1 := spendWindowFixture(t, repo)
ctx := context.Background()
got, err := repo.SpendWindowForWorkspace(ctx, "ws-1", time.Time{}, false, t1)
if err != nil {
t.Fatalf("SpendWindowForWorkspace: %v", err)
}
if got.PricedSubcents != 350 {
t.Errorf("PricedSubcents = %d, want 350 (e1=100 + e2=200 + e3=50 + e6=0; still excludes e5 at upper bound, e4 other workspace)", got.PricedSubcents)
}
}
func TestSpendWindowForAgent(t *testing.T) {
repo := newTestRepo(t)
t0, t1 := spendWindowFixture(t, repo)
ctx := context.Background()
got, err := repo.SpendWindowForAgent(ctx, "agent-1", t0, true, t1)
if err != nil {
t.Fatalf("SpendWindowForAgent: %v", err)
}
if got.PricedSubcents != 250 {
t.Errorf("PricedSubcents = %d, want 250", got.PricedSubcents)
}
if !got.Degraded {
t.Error("Degraded = false, want true")
}
}
func TestSpendWindowForAgent_NoUnpricedEventsIsNotDegraded(t *testing.T) {
repo := newTestRepo(t)
ctx := context.Background()
createSpendWindowTestAgent(t, repo, "ws-1", "agent-clean")
t0 := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
t1 := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
if err := repo.CreateCostEvent(ctx, &models.CostEvent{
ID: "clean-1", AgentProfileID: "agent-clean", ProjectID: "proj-1",
CostSubcents: 42, OccurredAt: t0.Add(time.Hour),
}); err != nil {
t.Fatalf("create cost event: %v", err)
}
got, err := repo.SpendWindowForAgent(ctx, "agent-clean", t0, true, t1)
if err != nil {
t.Fatalf("SpendWindowForAgent: %v", err)
}
if got.PricedSubcents != 42 {
t.Errorf("PricedSubcents = %d, want 42", got.PricedSubcents)
}
if got.Degraded {
t.Error("Degraded = true, want false (no unpriced events)")
}
}
func TestSpendWindowForAgent_NoEventsIsZeroNotError(t *testing.T) {
repo := newTestRepo(t)
ctx := context.Background()
createSpendWindowTestAgent(t, repo, "ws-1", "agent-empty")
t0 := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
t1 := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
got, err := repo.SpendWindowForAgent(ctx, "agent-empty", t0, true, t1)
if err != nil {
t.Fatalf("SpendWindowForAgent: %v", err)
}
if got.PricedSubcents != 0 || got.Degraded {
t.Errorf("got %+v, want zero value", got)
}
}
func TestSpendWindowForProject(t *testing.T) {
repo := newTestRepo(t)
t0, t1 := spendWindowFixture(t, repo)
ctx := context.Background()
got, err := repo.SpendWindowForProject(ctx, "proj-1", t0, true, t1)
if err != nil {
t.Fatalf("SpendWindowForProject: %v", err)
}
if got.PricedSubcents != 200 {
t.Errorf("PricedSubcents = %d, want 200 (e2=200 + e6=0; excludes e3/e4 other projects, e1 before window, e5 at upper bound)", got.PricedSubcents)
}
if !got.Degraded {
t.Error("Degraded = false, want true (e6 is unpriced, project proj-1, in window)")
}
}
func TestSpendWindowForProject_DoesNotUseTaskCurrentProject(t *testing.T) {
// Reparenting a task must not move its historical spend between
// ceilings (AC-OFFICE-BUDGET-002.15): the query filters on the cost
// event's own project_id, never a task join, so this test seeds no
// tasks table at all and still resolves correctly.
repo := newTestRepo(t)
ctx := context.Background()
createSpendWindowTestAgent(t, repo, "ws-1", "agent-1")
t0 := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
t1 := time.Date(2026, 3, 16, 0, 0, 0, 0, time.UTC)
if err := repo.CreateCostEvent(ctx, &models.CostEvent{
ID: "reparent-1", AgentProfileID: "agent-1", ProjectID: "proj-original",
CostSubcents: 77, OccurredAt: t0.Add(time.Hour),
}); err != nil {
t.Fatalf("create cost event: %v", err)
}
got, err := repo.SpendWindowForProject(ctx, "proj-original", t0, true, t1)
if err != nil {
t.Fatalf("SpendWindowForProject: %v", err)
}
if got.PricedSubcents != 77 {
t.Errorf("PricedSubcents = %d, want 77", got.PricedSubcents)
}
}
@@ -73,6 +73,7 @@ func (r *Repository) deleteWorkspaceDataTx(ctx context.Context, tx *sqlx.Tx, wor
`DELETE FROM office_workspace_routing WHERE workspace_id = ?`,
`DELETE FROM office_workspace_settings WHERE workspace_id = ?`,
`DELETE FROM office_budget_policies WHERE workspace_id = ?`,
`DELETE FROM office_budget_default_settings WHERE workspace_id = ?`,
`DELETE FROM office_routine_runs WHERE routine_id IN (SELECT id FROM office_routines WHERE workspace_id = ?)`,
`DELETE FROM office_routine_triggers WHERE routine_id IN (SELECT id FROM office_routines WHERE workspace_id = ?)`,
`DELETE FROM task_workspace_group_members WHERE workspace_group_id IN (
@@ -215,11 +215,22 @@ func applyServiceOverrides(opts *service.ServiceOptions, o service.ServiceOption
// insertTestCostEvent inserts a cost event directly into the DB for
// budget rollup tests. costSubcents is hundredths of a cent.
//
// occurred_at/created_at are bound as time.Time values, not pre-formatted
// strings: the production CreateCostEvent path binds event.OccurredAt the
// same way, and the pre-launch spend-window queries
// (internal/office/repository/sqlite/spendwindow.go) compare occurred_at
// against a time.Time bound the same way too. A hand-formatted
// time.RFC3339 string ("...T...Z") sorts inconsistently against the
// driver's own time.Time formatting ("... ...+00:00") once a query compares
// two timestamps seconds apart rather than months apart, which silently
// zeroed out spend in AC-OFFICE-BUDGET-006 admission tests until this was
// made to match.
func insertTestCostEvent(t *testing.T, svc interface {
ExecSQL(t *testing.T, q string, args ...interface{})
}, agentID, taskID string, costSubcents int64) {
t.Helper()
now := time.Now().UTC().Format(time.RFC3339)
now := time.Now().UTC()
svc.ExecSQL(t,
`INSERT INTO office_cost_events (id, agent_profile_id, task_id, cost_subcents, occurred_at, created_at)
VALUES (?, ?, ?, ?, ?, ?)`,
@@ -0,0 +1,453 @@
package service
import (
"context"
"encoding/json"
"errors"
"strconv"
"time"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/shared"
)
// Activity-log field key/value literals shared across the budget-admission
// entries in this file and in failRunNoEscalation (retry.go).
const (
activityFieldCeiling = "ceiling"
ceilingNotDetermined = "not_determined"
ceilingBuiltInDefault = "built_in_default"
)
// admitRun performs the five pre-launch admission gates of
// AC-OFFICE-BUDGET-001.14 and returns true only when the run may proceed to
// launch. It replaces the old checkBudget, which fail-opened both when no
// evaluator was wired and when the evaluator errored -- two of this
// capability's three closed fail-open paths. The third, zero configured
// policies, is closed by gate 5 (REQ-OFFICE-BUDGET-003's built-in default).
func (si *SchedulerIntegration) admitRun(
ctx context.Context, run *models.Run, agent *models.AgentInstance,
) bool {
provenance := shared.ClassifyRunProvenance(run.Reason)
// Gate 1: workspace resolution (AC-OFFICE-BUDGET-001.13). The lookup
// itself already happened in processRun via GetAgentFromConfig, which
// now disposes of a lookup ERROR itself (deferWorkspaceLookupFailure)
// before admitRun is ever called, per the recorded W2 human disposition
// that GetAgentFromConfig's own error contract is not reshaped. This
// gate is therefore defense-in-depth, not a live production path: the
// repository's agentInstanceFilter (workspace_id != '') guarantees any
// agent GetAgentFromConfig successfully returns already has a non-empty
// WorkspaceID, so this branch is structurally unreachable via the sole
// real caller and exists to keep AC-OFFICE-BUDGET-001.13's textual
// requirement true of admitRun itself, independent of that caller.
// AdmitRunForTest exercises it directly against a constructed agent.
if agent.WorkspaceID == "" {
incBudgetCancelledNoWorkspace(provenance)
return si.cancelBudgetRun(ctx, run, agent, "no_resolvable_workspace",
"run_budget_workspace_unresolvable", nil)
}
// Gate 2: evaluator presence (AC-OFFICE-BUDGET-001.5/.6).
if si.svc.budgetChecker == nil {
if provenance == shared.RunProvenanceAttended {
return true
}
incBudgetBlockedAbsentEvaluator(provenance)
return si.cancelBudgetRun(ctx, run, agent, "no_budget_evaluator",
"run_budget_no_evaluator", nil)
}
// Gate 3/4: evaluator invocation + applicable policies. The run's
// project identifier is resolved first (cheap: a single lookup, and its
// two permanent-cancellation outcomes -- (c) unparseable payload, (d)
// task not found -- are unconditional regardless of evaluator health),
// but a *lookup error* (b) must not itself decide the disposition:
// AC-OFFICE-BUDGET-001.14/-006.7 require project resolution to yield to
// gate 3 succeeding first, so that a run whose evaluator errors and
// whose project lookup would also fail gets one determinate disposition
// (evaluator fault) rather than one depending on which lookup happens to
// run first. On a lookup error we therefore invoke the evaluator with no
// project scope (a project-lookup failure is not itself evidence a
// project applies -- AC-OFFICE-BUDGET-001.15 already treats "no project"
// this way) to test gate 3 in isolation: an evaluator fault discovered
// there takes precedence, and only once gate 3 is confirmed healthy does
// the unresolvable project get its own distinguishable disposition
// (AC-OFFICE-BUDGET-006.3).
projectID, res := si.resolveRunProject(ctx, run.Payload)
switch res {
case projectResolutionUnparseable:
incBudgetCancelledUnparseablePayload(provenance)
return si.cancelBudgetRun(ctx, run, agent, "unparseable_payload",
"run_budget_payload_unparseable", nil)
case projectResolutionTaskNotFound:
incBudgetCancelledTaskNotFound(provenance)
return si.cancelBudgetRun(ctx, run, agent, "task_not_found",
"run_budget_task_not_found", nil)
}
hasProject := res == projectResolutionFound
if res == projectResolutionLookupError {
projectID, hasProject = "", false
}
now := time.Now().UTC()
result, err := si.svc.EvaluatePreLaunch(ctx, agent.WorkspaceID, agent.ID, projectID, hasProject, provenance, now)
if err != nil {
var upErr *models.UnevaluatedPolicyError
if errors.As(err, &upErr) {
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralUnevaluatedPolicy, upErr.PolicyID)
}
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralEvaluatorFault, "")
}
if res == projectResolutionLookupError {
// Gate 3 just succeeded (the evaluator itself is healthy) but the
// project remains unresolvable -- its own distinguishable cause,
// per AC-OFFICE-BUDGET-006.3/-006.7.
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralProjectLookupError, "")
}
si.logPolicyObservability(ctx, agent.WorkspaceID, run.ID, result.Policies, now)
degradedAdmitted := anyDegradedAdmitted(result.Policies)
if result.Decision != models.PreLaunchDecisionLaunch {
return si.finishPolicyBlock(ctx, run, agent, result.DecidingPolicy)
}
return si.admitDefaultCeilingGate(ctx, run, agent, provenance, result, degradedAdmitted, now)
}
// admitDefaultCeilingGate evaluates gate 5 (AC-OFFICE-BUDGET-003.1/.4/.11):
// the built-in default ceiling, applied to unattended runs only, and only
// when no workspace-scoped blocking-capable daily policy already supersedes
// it. Split out of admitRun to keep its cyclomatic complexity within the
// repo's golangci-lint limit; degradedAdmitted carries whether any of
// result's stored policies were already degraded-admitted at gate 4, so the
// AC-OFFICE-BUDGET-005.4 degraded-window counter still fires at most once
// per run even when both gate 4 and gate 5 saw a degraded window.
func (si *SchedulerIntegration) admitDefaultCeilingGate(
ctx context.Context, run *models.Run, agent *models.AgentInstance,
provenance shared.RunProvenance, result models.PreLaunchResult, degradedAdmitted bool, now time.Time,
) bool {
if provenance != shared.RunProvenanceUnattended || result.WorkspaceDailyBlockingSuperseded {
if degradedAdmitted {
incBudgetAdmittedDegradedWindow(provenance)
}
return true
}
def, defErr := si.svc.EvaluateDefaultCeiling(ctx, agent.WorkspaceID, now)
if defErr != nil {
return si.admitBudgetDeferral(ctx, run, agent, budgetDeferralEvaluatorFault, "")
}
si.logPolicyObservability(ctx, agent.WorkspaceID, run.ID, []models.PreLaunchPolicyResult{def}, now)
if def.LimitExceeded || def.DegradationBlocked {
return si.finishPolicyBlock(ctx, run, agent, &def)
}
incBudgetAdmittedDefault(provenance)
if degradedAdmitted || isDegradedAdmitted(&def) {
incBudgetAdmittedDegradedWindow(provenance)
}
return true
}
// finishPolicyBlock finishes run as blocked by p -- either a stored policy
// or the built-in default (p.IsDefault). Per AC-OFFICE-BUDGET-005.7/-004.6,
// a policy that blocked purely on pricing degradation (its limit was not
// also reached) carries the distinct run_budget_unmeasurable outcome and a
// distinct activity action; a plain limit block, including one where
// degradation also fired, keeps the existing budget_blocked outcome and
// action, with the degradation flag carried on the entry alone.
func (si *SchedulerIntegration) finishPolicyBlock(
ctx context.Context, run *models.Run, agent *models.AgentInstance, p *models.PreLaunchPolicyResult,
) bool {
si.releaseCheckoutIfNeeded(ctx, run)
si.svc.clearAgentWorking(ctx, agent.ID, run.ID)
provenance := shared.ClassifyRunProvenance(run.Reason)
action := "run_budget_blocked"
outcome := RunOutcomeBudgetBlocked
if !p.LimitExceeded {
action = "run_budget_pricing_degraded_blocked"
outcome = RunOutcomeBudgetUnmeasurable
incBudgetBlockedPricingDegraded(provenance)
} else {
incBudgetBlockedByLimit(provenance)
}
_ = si.svc.FinishRun(ctx, run.ID, outcome)
fields := map[string]string{"degraded": strconv.FormatBool(p.Degraded)}
if p.IsDefault {
fields[activityFieldCeiling] = ceilingBuiltInDefault
} else {
fields["policy_id"] = p.PolicyID
}
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
action, "run", run.ID, mustJSON(fields), run.ID, "")
return false
}
// cancelBudgetRun cancels run for a permanent, non-retryable admission
// outcome -- an unresolvable workspace, an absent evaluator on an
// unattended run, an unparseable payload, or a task that no longer exists
// -- mirroring cancelStaleRun's release/cancel/publish/log sequence. Always
// returns false.
func (si *SchedulerIntegration) cancelBudgetRun(
ctx context.Context, run *models.Run, agent *models.AgentInstance,
reason, action string, extraFields map[string]string,
) bool {
si.releaseCheckoutIfNeeded(ctx, run)
si.svc.clearAgentWorking(ctx, agent.ID, run.ID)
if err := si.svc.repo.CancelRun(ctx, run.ID, reason); err != nil {
si.logger.Error("failed to cancel run", zap.String("run_id", run.ID), zap.Error(err))
} else {
si.svc.publishRunProcessed(ctx, run.ID, RunStatusCancelled, run)
}
fields := map[string]string{activityFieldCeiling: ceilingNotDetermined}
for k, v := range extraFields {
fields[k] = v
}
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
action, "run", run.ID, mustJSON(fields), run.ID, "")
return false
}
// projectResolution enumerates the outcomes of resolving a run's project
// identifier for gate 4 (AC-OFFICE-BUDGET-006.7).
type projectResolution int
const (
// projectResolutionNone covers outcome (a): a well-formed payload with
// no task identifier, or a task that resolves with no project. Not a
// fault; no project-scoped policy applies (AC-OFFICE-BUDGET-001.15).
projectResolutionNone projectResolution = iota
projectResolutionFound
// projectResolutionLookupError covers outcome (b): GetTaskBasicInfo
// returned an error. An evaluator fault, deferred under
// AC-OFFICE-BUDGET-006.3.
projectResolutionLookupError
// projectResolutionUnparseable covers outcome (c): the payload cannot
// be parsed as JSON. Must not be read as (a); the run is cancelled,
// never retried or failed.
projectResolutionUnparseable
// projectResolutionTaskNotFound covers outcome (d): the lookup
// succeeded but the named task does not exist. Cancelled, never
// retried or failed.
projectResolutionTaskNotFound
)
// resolveRunProject resolves a run's project identifier for gate 4,
// implementing AC-OFFICE-BUDGET-006.7's four-outcome split. It does not
// reuse extractProjectID (which collapses all four outcomes to "" for its
// other, non-admission callers) or ParseRunPayload (which silently
// swallows a JSON unmarshal error), because gate 4 must distinguish all
// four rather than treating a malformed payload as "no project".
func (si *SchedulerIntegration) resolveRunProject(
ctx context.Context, payload string,
) (projectID string, res projectResolution) {
if payload == "" || payload == "{}" {
return "", projectResolutionNone
}
var parsed struct {
TaskID string `json:"task_id"`
}
if err := json.Unmarshal([]byte(payload), &parsed); err != nil {
return "", projectResolutionUnparseable
}
if parsed.TaskID == "" {
return "", projectResolutionNone
}
info, err := si.svc.repo.GetTaskBasicInfo(ctx, parsed.TaskID)
if err != nil {
return "", projectResolutionLookupError
}
if info == nil {
return "", projectResolutionTaskNotFound
}
if info.ProjectID == "" {
return "", projectResolutionNone
}
return info.ProjectID, projectResolutionFound
}
// budgetDeferralCause is one of the three AC-OFFICE-BUDGET-006.4 admission
// faults that share the evaluator fault's retry/backoff mechanics
// (AC-OFFICE-BUDGET-001.3/.16) but must stay distinguishable from it and
// from each other in their activity entries (AC-OFFICE-BUDGET-006.5). The
// workspace-lookup-error branch of AC-OFFICE-BUDGET-001.13 is deliberately
// NOT a fourth value here: it never reaches admitRun at all (processRun
// resolves it before admitRun is called, since no *models.AgentInstance
// exists yet to pass in), so it has its own dedicated pair,
// deferWorkspaceLookupFailure/cancelUnresolvableAgentRun, sharing this
// type's action-naming and no-escalation shape but not its cause value.
type budgetDeferralCause int
const (
budgetDeferralEvaluatorFault budgetDeferralCause = iota
budgetDeferralUnevaluatedPolicy
budgetDeferralProjectLookupError
)
func (c budgetDeferralCause) deferredAction() string {
switch c {
case budgetDeferralUnevaluatedPolicy:
return "run_budget_unevaluated_policy_deferred"
case budgetDeferralProjectLookupError:
return "run_budget_project_lookup_deferred"
default:
return "run_budget_evaluator_fault_deferred"
}
}
func (c budgetDeferralCause) failedAction() string {
switch c {
case budgetDeferralUnevaluatedPolicy:
return "run_budget_unevaluated_policy_failed"
case budgetDeferralProjectLookupError:
return "run_budget_project_lookup_failed"
default:
return "run_budget_evaluator_fault_failed"
}
}
// admitBudgetDeferral defers (retries) run for one of the three
// AC-OFFICE-BUDGET-006.4 admission-fault causes, or fails it without
// escalation once retries are exhausted (AC-OFFICE-BUDGET-001.17). It
// reuses the existing scheduleRetry/isRetryStale machinery so retry_count,
// backoff and the staleness bound are shared with every other retry class
// (AC-OFFICE-BUDGET-001.16/.18), but never calls escalateFailure. policyID
// names the policy per AC-OFFICE-BUDGET-005.5/-006.5's naming rule and is
// "" for every cause but budgetDeferralUnevaluatedPolicy. Always returns
// false: every call site uses it as `return si.admitBudgetDeferral(...)`.
func (si *SchedulerIntegration) admitBudgetDeferral(
ctx context.Context, run *models.Run, agent *models.AgentInstance,
cause budgetDeferralCause, policyID string,
) bool {
si.releaseCheckoutIfNeeded(ctx, run)
provenance := shared.ClassifyRunProvenance(run.Reason)
if run.RetryCount >= MaxRetryCount {
incBudgetFailedNoEscalation(cause, provenance)
if err := si.svc.failRunNoEscalation(ctx, run, agent, cause, policyID); err != nil {
si.logger.Error("failed to fail run without escalation",
zap.String("run_id", run.ID), zap.Error(err))
}
return false
}
if stale, _ := isRetryStale(run); stale {
incBudgetCancelledStaleDeferral(provenance)
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
"run_budget_deferral_stale_cancelled", "run", run.ID,
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined, "cause": "budget_deferral"}), run.ID, "")
} else {
switch cause {
case budgetDeferralEvaluatorFault:
incBudgetDeferredEvaluatorFault(provenance)
case budgetDeferralUnevaluatedPolicy:
incBudgetDeferredUnevaluatedPolicy(provenance)
case budgetDeferralProjectLookupError:
incBudgetDeferredProjectLookup(provenance)
}
fields := map[string]string{
activityFieldCeiling: ceilingNotDetermined,
"attempt": strconv.Itoa(run.RetryCount + 1),
}
if policyID != "" {
fields["policy_id"] = policyID
}
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID, "scheduler", "office-scheduler",
cause.deferredAction(), "run", run.ID, mustJSON(fields), run.ID, "")
}
if err := si.svc.scheduleRetry(ctx, run); err != nil {
si.logger.Error("failed to schedule budget deferral retry",
zap.String("run_id", run.ID), zap.Error(err))
}
return false
}
// cancelUnresolvableAgentRun implements AC-OFFICE-BUDGET-001.13's "lookup
// succeeded and found no agent instance" disposition, called from
// processRun before an *models.AgentInstance is available -- the run
// carries no workspace and therefore no ceiling that could ever be
// evaluated, so it is cancelled rather than retried or failed, and never
// escalated (AC-OFFICE-BUDGET-001.17). Shares its action with admitRun's
// gate 1 (agent found but WorkspaceID == ""), the other branch of the same
// disposition; unlike cancelBudgetRun's other callers, no agent is
// available here, so the activity entry carries no workspace scope.
func (si *SchedulerIntegration) cancelUnresolvableAgentRun(ctx context.Context, run *models.Run) {
provenance := shared.ClassifyRunProvenance(run.Reason)
incBudgetCancelledNoWorkspace(provenance)
si.cleanupWorkspaceLookupRun(ctx, run)
if err := si.svc.repo.CancelRun(ctx, run.ID, "no_resolvable_workspace"); err != nil {
si.logger.Error("failed to cancel run", zap.String("run_id", run.ID), zap.Error(err))
} else {
si.svc.publishRunProcessed(ctx, run.ID, RunStatusCancelled, run)
}
si.svc.LogActivityWithRun(ctx, "", "scheduler", "office-scheduler",
"run_budget_workspace_unresolvable", "run", run.ID,
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined}), run.ID, "")
}
// deferWorkspaceLookupFailure implements AC-OFFICE-BUDGET-001.13's "lookup
// returned an error" disposition: deferred/retried on the same terms as an
// evaluator fault (AC-OFFICE-BUDGET-001.3/.16/.18), and at MaxRetryCount
// failed without escalation (AC-OFFICE-BUDGET-006.4) rather than through
// the generic HandleRunFailure/escalateFailure path, which would queue a
// new run for the CEO agent (AC-OFFICE-BUDGET-001.17). Mirrors
// admitBudgetDeferral's shape, but no *models.AgentInstance is available
// here (the lookup itself is what failed), so the activity entry carries
// no workspace scope. The run may still own a checkout from an earlier
// routed launch, so this path releases run-owned state before retrying.
func (si *SchedulerIntegration) deferWorkspaceLookupFailure(ctx context.Context, run *models.Run) {
provenance := shared.ClassifyRunProvenance(run.Reason)
si.cleanupWorkspaceLookupRun(ctx, run)
if run.RetryCount >= MaxRetryCount {
incBudgetFailedWorkspaceLookup(provenance)
if err := si.svc.FailRun(ctx, run.ID); err != nil {
si.logger.Error("failed to fail run without escalation",
zap.String("run_id", run.ID), zap.Error(err))
return
}
si.svc.LogActivityWithRun(ctx, "", "system", "scheduler",
"run_budget_workspace_lookup_failed", "run", run.ID,
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined}), run.ID, "")
return
}
if stale, _ := isRetryStale(run); stale {
incBudgetCancelledStaleDeferral(provenance)
si.svc.LogActivityWithRun(ctx, "", "scheduler", "office-scheduler",
"run_budget_deferral_stale_cancelled", "run", run.ID,
mustJSON(map[string]string{activityFieldCeiling: ceilingNotDetermined, "cause": "workspace_lookup"}), run.ID, "")
} else {
incBudgetDeferredWorkspaceLookup(provenance)
si.svc.LogActivityWithRun(ctx, "", "scheduler", "office-scheduler",
"run_budget_workspace_lookup_deferred", "run", run.ID,
mustJSON(map[string]string{
activityFieldCeiling: ceilingNotDetermined,
"attempt": strconv.Itoa(run.RetryCount + 1),
}), run.ID, "")
}
if err := si.svc.scheduleRetry(ctx, run); err != nil {
si.logger.Error("failed to schedule workspace lookup retry",
zap.String("run_id", run.ID), zap.Error(err))
}
}
// cleanupWorkspaceLookupRun clears ownership retained by a routed run that
// was requeued after launch. The owner-scoped release is a no-op when this
// attempt never held a checkout, so a lookup failure cannot steal another
// run's lock.
func (si *SchedulerIntegration) cleanupWorkspaceLookupRun(ctx context.Context, run *models.Run) {
si.releaseCheckoutIfNeeded(ctx, run)
if run != nil {
si.svc.clearAgentWorking(ctx, run.AgentProfileID, run.ID)
}
}
@@ -0,0 +1,935 @@
package service_test
// Covers the five pre-launch admission gates of
// docs/specs/office/requirements/budget-enforcement.md AC-OFFICE-BUDGET-001.14,
// replacing the old checkBudget's two fail-open paths (no evaluator wired,
// evaluator error) and closing the third (zero configured policies) via the
// built-in default at gate 5.
import (
"context"
"encoding/json"
"sort"
"testing"
"time"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/service"
"github.com/kandev/kandev/internal/office/shared"
)
// fakeBudgetEvaluator lets admission tests force EvaluatePreLaunch/
// EvaluateDefaultCeiling's error and result shapes without needing a real
// repository failure.
type fakeBudgetEvaluator struct {
preLaunchResult models.PreLaunchResult
preLaunchErr error
defaultResult models.PreLaunchPolicyResult
defaultErr error
}
func (f *fakeBudgetEvaluator) CheckPreExecutionBudget(
context.Context, string, string, string,
) (bool, string, error) {
return true, "", nil
}
func (f *fakeBudgetEvaluator) EvaluateBudget(context.Context, string, string, string) error {
return nil
}
func (f *fakeBudgetEvaluator) EvaluatePreLaunch(
context.Context, string, string, string, bool, shared.RunProvenance, time.Time,
) (models.PreLaunchResult, error) {
return f.preLaunchResult, f.preLaunchErr
}
func (f *fakeBudgetEvaluator) EvaluateDefaultCeiling(
context.Context, string, time.Time,
) (models.PreLaunchPolicyResult, error) {
return f.defaultResult, f.defaultErr
}
// deferralAttempts returns the "attempt" field of every activity entry for
// runID matching action, sorted ascending. Sorted rather than
// created_at-ordered because repeated deferrals in a test can land within
// the same timestamp resolution.
func deferralAttempts(t *testing.T, svc *service.Service, wsID, runID, action string) []string {
t.Helper()
entries, err := svc.ListActivity(context.Background(), wsID, 50)
if err != nil {
t.Fatalf("list activity: %v", err)
}
var attempts []string
for _, e := range entries {
if e.RunID != runID || string(e.Action) != action {
continue
}
var fields map[string]string
if err := json.Unmarshal([]byte(e.Details), &fields); err != nil {
t.Fatalf("unmarshal activity details %q: %v", e.Details, err)
}
attempts = append(attempts, fields["attempt"])
}
sort.Strings(attempts)
return attempts
}
func hasActivityAction(t *testing.T, svc *service.Service, wsID, action string) bool {
t.Helper()
entries, err := svc.ListActivity(context.Background(), wsID, 50)
if err != nil {
t.Fatalf("list activity: %v", err)
}
for _, e := range entries {
if string(e.Action) == action {
return true
}
}
return false
}
// TestAdmitRun_NoEvaluatorWired_UnattendedCancels covers AC-OFFICE-BUDGET-001.5:
// an absent evaluator is a deployment fact, not a transient fault, so an
// unattended run is cancelled rather than retried or failed.
func TestAdmitRun_NoEvaluatorWired_UnattendedCancels(t *testing.T) {
svc := newTestService(t)
svc.SetBudgetChecker(nil)
ctx := context.Background()
agent := makeAgent("worker-no-evaluator-unattended", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
if run.Status != service.RunStatusCancelled {
t.Fatalf("status = %q, want cancelled", run.Status)
}
if !hasActivityAction(t, svc, "ws-1", "run_budget_no_evaluator") {
t.Error("expected run_budget_no_evaluator activity entry")
}
}
// TestAdmitRun_NoEvaluatorWired_AttendedLaunches covers AC-OFFICE-BUDGET-001.6:
// an absent evaluator never blocks an attended run.
func TestAdmitRun_NoEvaluatorWired_AttendedLaunches(t *testing.T) {
svc := newTestService(t)
svc.SetBudgetChecker(nil)
ctx := context.Background()
agent := makeAgent("worker-no-evaluator-attended", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestTask(t, svc, "task-no-evaluator-attended", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-no-evaluator-attended"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if hasActivityAction(t, svc, "ws-1", "run_budget_no_evaluator") {
t.Error("attended run must not be blocked by an absent evaluator")
}
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
if run.Status == service.RunStatusCancelled {
t.Fatalf("status = %q, attended run must not be cancelled", run.Status)
}
}
// TestAdmitRun_EvaluatorFault_DefersThenFailsWithoutEscalation covers
// AC-OFFICE-BUDGET-001.3/.4/.17: a plain evaluator error (not naming any
// policy) defers the run, and failing it at MaxRetryCount neither escalates
// to the CEO agent nor queues any new run.
func TestAdmitRun_EvaluatorFault_DefersThenFailsWithoutEscalation(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
svc.SetBudgetChecker(fake)
ctx := context.Background()
ceo := makeAgent("ceo-evaluator-fault", models.AgentRoleCEO)
if err := svc.CreateAgentInstance(ctx, ceo); err != nil {
t.Fatalf("create ceo: %v", err)
}
agent := makeAgent("worker-evaluator-fault", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestTask(t, svc, "task-evaluator-fault", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-evaluator-fault"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
if run.Status != service.RunStatusQueued {
t.Fatalf("status after first fault = %q, want queued (deferred)", run.Status)
}
if !hasActivityAction(t, svc, "ws-1", "run_budget_evaluator_fault_deferred") {
t.Error("expected run_budget_evaluator_fault_deferred activity entry")
}
// Drive the run to MaxRetryCount and re-process it directly (bypassing
// the real backoff delay, exactly as the existing retry tests do).
run.RetryCount = service.MaxRetryCount
service.ProcessRunForTest(svc, ctx, run)
failed, err := svc.GetRun(ctx, run.ID)
if err != nil {
t.Fatalf("get run: %v", err)
}
if failed.Status != service.RunStatusFailed {
t.Fatalf("status at MaxRetryCount = %q, want failed", failed.Status)
}
if !hasActivityAction(t, svc, "ws-1", "run_budget_evaluator_fault_failed") {
t.Error("expected run_budget_evaluator_fault_failed activity entry")
}
// AC-OFFICE-BUDGET-001.17: no escalation run queued for the CEO.
runs, err := svc.ListRuns(ctx, "ws-1")
if err != nil {
t.Fatalf("list runs: %v", err)
}
for _, r := range runs {
if r.AgentProfileID == ceo.ID {
t.Errorf("unexpected run queued for CEO agent after budget-fault failure: %+v", r)
}
}
}
// TestAdmitRun_UnevaluatedPolicy_NamesPolicyInDeferral covers
// AC-OFFICE-BUDGET-006.1/.5: an unevaluated-policy fault is distinguishable
// from a plain evaluator fault and names the policy it could not evaluate.
func TestAdmitRun_UnevaluatedPolicy_NamesPolicyInDeferral(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-xyz", Err: context.DeadlineExceeded},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-unevaluated-policy", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestTask(t, svc, "task-unevaluated-policy", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-unevaluated-policy"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
if run.Status != service.RunStatusQueued {
t.Fatalf("status = %q, want queued (deferred)", run.Status)
}
if !hasActivityAction(t, svc, "ws-1", "run_budget_unevaluated_policy_deferred") {
t.Error("expected run_budget_unevaluated_policy_deferred activity entry")
}
if hasActivityAction(t, svc, "ws-1", "run_budget_evaluator_fault_deferred") {
t.Error("unevaluated-policy fault must not also fire the generic evaluator-fault action")
}
}
// TestFinishPolicyBlock_ClearsStaleAgentWorkingStatus and
// TestCancelBudgetRun_ClearsStaleAgentWorkingStatus pin a fix carried over
// from a rebase onto main: main independently added an equivalent
// clearAgentWorking call to the old checkBudget's block branch (fixing a
// stuck-"working" agent), and cancelBudgetRun's own doc comment already
// claimed to mirror cancelStaleRun's release/cancel/publish/log sequence --
// which has always included clearAgentWorking -- without actually doing so.
// admitRun always runs before markAgentWorking in the real pipeline
// (processRun calls admitRun, then prepareAndLaunch marks working), so the
// only way an agent is already "working" when a block/cancel fires for the
// same run.ID is a run that reached the launch boundary once, then got
// requeued (e.g. a contended checkout retry) and is being re-admitted.
// TestFinishPolicyBlock_ClearsStaleAgentWorkingStatus covers finishPolicyBlock.
func TestFinishPolicyBlock_ClearsStaleAgentWorkingStatus(t *testing.T) {
svc := newTestService(t)
deciding := &models.PreLaunchPolicyResult{PolicyID: "policy-stale-working", LimitExceeded: true}
fake := &fakeBudgetEvaluator{
preLaunchResult: models.PreLaunchResult{
Decision: models.PreLaunchDecisionBlockedByLimit,
DecidingPolicy: deciding,
Policies: []models.PreLaunchPolicyResult{*deciding},
},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-stale-working-block", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
t.Fatalf("mark agent working: %v", err)
}
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusWorking, "before the re-admission block")
service.AdmitRunForTest(svc, ctx, run, agent)
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusIdle,
"after a policy block clears a stale working mark left by an earlier attempt")
}
// TestCancelBudgetRun_ClearsStaleAgentWorkingStatus covers cancelBudgetRun,
// via gate 1's cancellation path.
func TestCancelBudgetRun_ClearsStaleAgentWorkingStatus(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-stale-working-cancel", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
t.Fatalf("mark agent working: %v", err)
}
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusWorking, "before the re-admission cancel")
unresolvedAgent := *agent
unresolvedAgent.WorkspaceID = ""
service.AdmitRunForTest(svc, ctx, run, &unresolvedAgent)
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusIdle,
"after a gate-1 cancel clears a stale working mark left by an earlier attempt")
}
// TestFailRunNoEscalation_ClearsStaleAgentWorkingStatus covers
// failRunNoEscalation (retry.go), reached via admitBudgetDeferral once
// RetryCount reaches MaxRetryCount. Same stale-mark scenario as the two
// tests above: a run that reached the launch boundary once, was requeued,
// then exhausted its retries on a budget-admission fault must not leave its
// agent stuck "working" forever.
func TestFailRunNoEscalation_ClearsStaleAgentWorkingStatus(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-stale-working-no-escalation", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
t.Fatalf("mark agent working: %v", err)
}
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusWorking, "before the re-admission fault")
run.RetryCount = service.MaxRetryCount
service.AdmitRunForTest(svc, ctx, run, agent)
failed, err := svc.GetRun(ctx, run.ID)
if err != nil {
t.Fatalf("get run: %v", err)
}
if failed.Status != service.RunStatusFailed {
t.Fatalf("status at MaxRetryCount = %q, want failed", failed.Status)
}
assertAgentStatus(t, svc, ctx, agent.ID, models.AgentStatusIdle,
"after failRunNoEscalation clears a stale working mark left by an earlier attempt")
}
// TestProcessRun_MissingAgentReleasesPriorCheckout covers a routed run that
// was requeued after launch. The next scheduler pass may find that its agent
// no longer exists, but the run still owns the task checkout from its prior
// attempt. The cancellation must release that ownership.
func TestProcessRun_MissingAgentReleasesPriorCheckout(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-routed-missing", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
svc.ExecSQL(t, `
INSERT INTO tasks (id, workspace_id, title, created_at, updated_at)
VALUES ('task-routed-missing', 'ws-1', 'Routed task', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
`)
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-routed-missing"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
acquired, err := svc.RepoForTest().CheckoutTaskForRun(ctx, "task-routed-missing", agent.ID, run.ID)
if err != nil || !acquired {
t.Fatalf("seed run checkout: acquired=%v err=%v", acquired, err)
}
if _, err := svc.RepoForTest().MarkAgentWorking(ctx, agent.ID, run.ID); err != nil {
t.Fatalf("mark agent working: %v", err)
}
if err := svc.RepoForTest().DeleteAgentInstance(ctx, agent.ID); err != nil {
t.Fatalf("delete agent: %v", err)
}
service.ProcessRunForTest(svc, ctx, run)
replacement := makeAgent("worker-routed-replacement", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, replacement); err != nil {
t.Fatalf("create replacement agent: %v", err)
}
acquired, err = svc.CheckoutTask(ctx, "task-routed-missing", replacement.ID)
if err != nil {
t.Fatalf("replacement checkout: %v", err)
}
if !acquired {
t.Fatal("replacement agent could not acquire a checkout left by the missing-agent cancellation")
}
cancelled, err := svc.GetRun(ctx, run.ID)
if err != nil {
t.Fatalf("get cancelled run: %v", err)
}
if cancelled.Status != service.RunStatusCancelled {
t.Fatalf("run status = %q, want cancelled", cancelled.Status)
}
}
// TestProcessRun_WorkspaceLookupErrorReleasesPriorCheckout covers the retry
// branch. A temporary repository lookup error must not preserve a checkout
// while the run waits in the queue.
func TestProcessRun_WorkspaceLookupErrorReleasesPriorCheckout(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-routed-lookup-error", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
svc.ExecSQL(t, `
INSERT INTO tasks (id, workspace_id, title, created_at, updated_at)
VALUES ('task-routed-lookup-error', 'ws-1', 'Routed task', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
`)
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-routed-lookup-error"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
acquired, err := svc.RepoForTest().CheckoutTaskForRun(ctx, "task-routed-lookup-error", agent.ID, run.ID)
if err != nil || !acquired {
t.Fatalf("seed run checkout: acquired=%v err=%v", acquired, err)
}
// Make both agent lookup queries fail with a transient database error.
svc.ExecSQL(t, "DROP TABLE agent_profiles")
service.ProcessRunForTest(svc, ctx, run)
acquired, err = svc.CheckoutTask(ctx, "task-routed-lookup-error", "replacement-agent")
if err != nil {
t.Fatalf("replacement checkout: %v", err)
}
if !acquired {
t.Fatal("replacement agent could not acquire a checkout left by the lookup-error deferral")
}
deferred, err := svc.GetRun(ctx, run.ID)
if err != nil {
t.Fatalf("get deferred run: %v", err)
}
if deferred.Status != service.RunStatusQueued {
t.Fatalf("run status = %q, want queued", deferred.Status)
}
}
// TestAdmitRun_RepeatedDeferral_AttemptIncrementsPerActivity covers
// AC-OFFICE-BUDGET-005.6: each deferral of the same run writes its own
// activity entry -- never coalesced into a single running total -- and each
// entry's "attempt" field tracks that call's run.RetryCount+1.
func TestAdmitRun_RepeatedDeferral_AttemptIncrementsPerActivity(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-attempt", Err: context.DeadlineExceeded},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-attempt-increments", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestTask(t, svc, "task-attempt-increments", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-attempt-increments"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
for i := 0; i < 3; i++ {
service.AdmitRunForTest(svc, ctx, run, agent)
run.RetryCount++
}
got := deferralAttempts(t, svc, "ws-1", run.ID, "run_budget_unevaluated_policy_deferred")
want := []string{"1", "2", "3"}
if len(got) != len(want) {
t.Fatalf("attempts = %v, want %v (one entry per deferral, not coalesced)", got, want)
}
for i, w := range want {
if got[i] != w {
t.Errorf("attempts = %v, want %v", got, want)
break
}
}
}
// TestAdmitRun_DefaultCeiling_BlocksUnattendedRunWithZeroPolicies closes the
// third of the three fail-open paths this capability replaces: with zero
// configured policies, an unattended run over the built-in default's daily
// ceiling is blocked rather than launched unconditionally.
func TestAdmitRun_DefaultCeiling_BlocksUnattendedRunWithZeroPolicies(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-default-ceiling", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestCostEvent(t, svc, agent.ID, "task-default-ceiling", int64(600_000))
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
assertOutcome(t, run, service.RunOutcomeBudgetBlocked)
if !hasActivityAction(t, svc, "ws-1", "run_budget_blocked") {
t.Error("expected run_budget_blocked activity entry")
}
}
// TestResolveRunProject covers AC-OFFICE-BUDGET-006.7's four-outcome split.
// Tested directly against resolveRunProject rather than through the full
// scheduler pipeline: checkoutTask's own contention query independently
// requires the named task to already exist (a 0-row checkout update reads
// identically to "held by another agent"), so a task-not-found or a
// tasks-table failure never reaches admitRun through that path at all in
// this codebase's existing checkout flow -- resolveRunProject's own
// contract is what this capability adds and is what needs covering here.
func TestResolveRunProject(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
insertTestTask(t, svc, "task-with-project", "ws-1")
svc.ExecSQL(t, `UPDATE tasks SET project_id = ? WHERE id = ?`, "project-1", "task-with-project")
insertTestTask(t, svc, "task-no-project", "ws-1")
cases := []struct {
name string
payload string
wantProjectID string
wantRes int
}{
{"empty payload", "", "", service.ProjectResolutionNoneForTest},
{"empty object payload", "{}", "", service.ProjectResolutionNoneForTest},
{"no task_id key", `{"other":"field"}`, "", service.ProjectResolutionNoneForTest},
{"task resolves with no project", `{"task_id":"task-no-project"}`, "", service.ProjectResolutionNoneForTest},
{"task resolves with a project", `{"task_id":"task-with-project"}`, "project-1", service.ProjectResolutionFoundForTest},
{"unparseable payload", `{not-json`, "", service.ProjectResolutionUnparseableForTest},
{"task does not exist", `{"task_id":"does-not-exist"}`, "", service.ProjectResolutionTaskNotFoundForTest},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
gotID, gotRes := service.ResolveRunProjectForTest(svc, ctx, tc.payload)
if gotID != tc.wantProjectID || gotRes != tc.wantRes {
t.Errorf("resolveRunProject(%q) = (%q, %d), want (%q, %d)",
tc.payload, gotID, gotRes, tc.wantProjectID, tc.wantRes)
}
})
}
t.Run("lookup error", func(t *testing.T) {
svc.ExecSQL(t, `DROP TABLE tasks`)
_, gotRes := service.ResolveRunProjectForTest(svc, ctx, `{"task_id":"task-with-project"}`)
if gotRes != service.ProjectResolutionLookupErrorForTest {
t.Errorf("resolution = %d, want lookup error (%d)", gotRes, service.ProjectResolutionLookupErrorForTest)
}
})
}
// TestAdmitRun_PricingDegradedBlock_UnmeasurableOutcome covers
// AC-OFFICE-BUDGET-004.6/-005.7: a policy that blocks purely on pricing
// degradation (its limit was never confirmed reached) carries the distinct
// run_budget_unmeasurable outcome and its own activity action, not the plain
// limit-block pair.
func TestAdmitRun_PricingDegradedBlock_UnmeasurableOutcome(t *testing.T) {
svc := newTestService(t)
deciding := &models.PreLaunchPolicyResult{
PolicyID: "policy-pricing-degraded", Degraded: true, DegradationBlocked: true, LimitExceeded: false,
}
fake := &fakeBudgetEvaluator{
preLaunchResult: models.PreLaunchResult{
Decision: models.PreLaunchDecisionBlockedByDegradation,
DecidingPolicy: deciding,
Policies: []models.PreLaunchPolicyResult{*deciding},
},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-pricing-degraded-block", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
assertOutcome(t, run, service.RunOutcomeBudgetUnmeasurable)
if !hasActivityAction(t, svc, "ws-1", "run_budget_pricing_degraded_blocked") {
t.Error("expected run_budget_pricing_degraded_blocked activity entry")
}
if hasActivityAction(t, svc, "ws-1", "run_budget_blocked") {
t.Error("a pricing-degraded block must not also fire the plain limit-block action")
}
}
// TestAdmitRun_DefaultCeiling_ExemptsAttendedRun covers AC-OFFICE-BUDGET-003.3:
// the built-in default ceiling gates unattended runs only. An attended run
// launches even though its workspace already exceeds the default ceiling
// (mirroring TestAdmitRun_DefaultCeiling_BlocksUnattendedRunWithZeroPolicies's
// spend fixture, but with a task-assigned, attended run instead).
func TestAdmitRun_DefaultCeiling_ExemptsAttendedRun(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-default-ceiling-attended", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestCostEvent(t, svc, agent.ID, "task-default-ceiling-attended", int64(600_000))
insertTestTask(t, svc, "task-default-ceiling-attended-run", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-default-ceiling-attended-run"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonTaskAssigned)
if run.Status == service.RunStatusCancelled {
t.Fatalf("status = %q, attended run must not be cancelled by the default ceiling", run.Status)
}
if run.Status == "finished" && run.Outcome != nil && *run.Outcome == service.RunOutcomeBudgetBlocked {
t.Fatalf("attended run was finished with outcome %q, want not blocked by the default ceiling", *run.Outcome)
}
if hasActivityAction(t, svc, "ws-1", "run_budget_blocked") {
t.Error("attended run must not trigger a default-ceiling block")
}
}
// activityActionForRun returns the single activity action recorded for
// runID within wsID's activity log, failing the test if none is found.
// cancelUnresolvableAgentRun logs with an empty workspace scope (no agent
// available to read WorkspaceID from), so callers pass "" for that scenario.
func activityActionForRun(t *testing.T, svc *service.Service, wsID, runID string) string {
t.Helper()
entries, err := svc.ListActivity(context.Background(), wsID, 50)
if err != nil {
t.Fatalf("list activity: %v", err)
}
for _, e := range entries {
if e.RunID == runID {
return string(e.Action)
}
}
t.Fatalf("no activity entry found for run %s in workspace %q", runID, wsID)
return ""
}
// TestBudgetAdmission_ActionsAreDistinguishable covers AC-OFFICE-BUDGET-005.3/
// -006.5: every admission-fault, cancellation, and block disposition this
// capability introduces writes its own distinct activity action, so an
// operator (or an alerting query keyed on the action string) can always
// tell dispositions apart. Each scenario runs against its own service
// instance so setup that mutates shared state (a dropped table, a forced
// retry count) can't leak into another scenario's result.
func TestBudgetAdmission_ActionsAreDistinguishable(t *testing.T) {
type observedAction struct{ scenario, action string }
var seen []observedAction
record := func(scenario, action string) {
seen = append(seen, observedAction{scenario, action})
}
t.Run("workspace_lookup_deferred", func(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-actions-ws-deferred", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DROP TABLE agent_profiles`)
service.ProcessRunForTest(svc, ctx, run)
// deferWorkspaceLookupFailure logs with no workspace scope: no
// *models.AgentInstance was ever resolved to read a WorkspaceID from.
record("workspace_lookup_deferred", activityActionForRun(t, svc, "", run.ID))
})
t.Run("workspace_lookup_failed", func(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-actions-ws-failed", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DROP TABLE agent_profiles`)
run.RetryCount = service.MaxRetryCount
service.ProcessRunForTest(svc, ctx, run)
record("workspace_lookup_failed", activityActionForRun(t, svc, "", run.ID))
})
t.Run("workspace_unresolvable", func(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
agent := makeAgent("worker-actions-ws-unresolvable", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DELETE FROM agent_profiles WHERE id = ?`, agent.ID)
service.ProcessRunForTest(svc, ctx, run)
record("workspace_unresolvable", activityActionForRun(t, svc, "", run.ID))
})
t.Run("unevaluated_policy_deferred", func(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-actions", Err: context.DeadlineExceeded},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-unevaluated-deferred", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
record("unevaluated_policy_deferred", activityActionForRun(t, svc, "ws-1", run.ID))
})
t.Run("unevaluated_policy_failed", func(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchErr: &models.UnevaluatedPolicyError{PolicyID: "policy-actions", Err: context.DeadlineExceeded},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-unevaluated-failed", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
run.RetryCount = service.MaxRetryCount
service.ProcessRunForTest(svc, ctx, run)
record("unevaluated_policy_failed", activityActionForRun(t, svc, "ws-1", run.ID))
})
// project_lookup_deferred/failed, payload_unparseable and task_not_found
// all drive admitRun directly via AdmitRunForTest rather than through
// RunSchedulerTick/ProcessRunForTest: as TestResolveRunProject's doc
// comment explains, checkoutTask's own contention query independently
// requires the named task to exist (or the tasks table to be queryable
// at all), so a task-not-found or tasks-table failure is intercepted by
// checkoutTask as "held by another agent" / a checkout error before the
// run ever reaches admitRun through the scheduler pipeline -- exactly
// the scenario each of these needs to construct.
t.Run("project_lookup_deferred", func(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-project-deferred", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DROP TABLE tasks`)
run.Payload = `{"task_id":"any-task"}`
service.AdmitRunForTest(svc, ctx, run, agent)
record("project_lookup_deferred", activityActionForRun(t, svc, "ws-1", run.ID))
})
t.Run("project_lookup_failed", func(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-project-failed", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DROP TABLE tasks`)
run.Payload = `{"task_id":"any-task"}`
run.RetryCount = service.MaxRetryCount
service.AdmitRunForTest(svc, ctx, run, agent)
record("project_lookup_failed", activityActionForRun(t, svc, "ws-1", run.ID))
})
t.Run("payload_unparseable", func(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-unparseable", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
run.Payload = `{not-json`
service.AdmitRunForTest(svc, ctx, run, agent)
record("payload_unparseable", activityActionForRun(t, svc, "ws-1", run.ID))
})
t.Run("task_not_found", func(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-task-not-found", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
run.Payload = `{"task_id":"does-not-exist"}`
service.AdmitRunForTest(svc, ctx, run, agent)
record("task_not_found", activityActionForRun(t, svc, "ws-1", run.ID))
})
t.Run("pricing_degraded_blocked", func(t *testing.T) {
svc := newTestService(t)
deciding := &models.PreLaunchPolicyResult{
PolicyID: "policy-actions-degraded", Degraded: true, DegradationBlocked: true, LimitExceeded: false,
}
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{
Decision: models.PreLaunchDecisionBlockedByDegradation, DecidingPolicy: deciding,
Policies: []models.PreLaunchPolicyResult{*deciding},
}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
agent := makeAgent("worker-actions-pricing-degraded", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
run := findRunForAgent(t, svc, ctx, "ws-1", agent.ID, service.RunReasonRoutineTrigger)
record("pricing_degraded_blocked", activityActionForRun(t, svc, "ws-1", run.ID))
})
const wantScenarios = 10
if len(seen) != wantScenarios {
t.Fatalf("expected %d scenarios to record an action, got %d: %+v", wantScenarios, len(seen), seen)
}
byAction := make(map[string]string, len(seen))
for _, o := range seen {
if prior, ok := byAction[o.action]; ok {
t.Errorf("action %q fired for both %q and %q; every disposition must be independently distinguishable",
o.action, prior, o.scenario)
continue
}
byAction[o.action] = o.scenario
}
}
@@ -0,0 +1,137 @@
package service
import (
"expvar"
"github.com/kandev/kandev/internal/office/shared"
)
// expvar maps for AC-OFFICE-BUDGET-005.4's nine required counters, in the
// same /debug/vars surface as the existing Office metrics (routing_*,
// cost_events_*). Mirrors scheduler/metrics_vars.go's shape: counters only,
// each labelled by run provenance (AC-OFFICE-BUDGET-007.1).
var (
budgetBlockedByLimitTotal = expvar.NewMap("office_budget_blocked_by_limit_total")
budgetDeferredEvaluatorFaultTotal = expvar.NewMap("office_budget_deferred_evaluator_fault_total")
budgetBlockedAbsentEvaluatorTotal = expvar.NewMap("office_budget_blocked_absent_evaluator_total")
budgetDeferredWorkspaceLookupTotal = expvar.NewMap("office_budget_deferred_workspace_lookup_total")
budgetCancelledNoWorkspaceTotal = expvar.NewMap("office_budget_cancelled_no_workspace_total")
budgetCancelledStaleDeferralTotal = expvar.NewMap("office_budget_cancelled_stale_deferral_total")
budgetBlockedPricingDegradedTotal = expvar.NewMap("office_budget_blocked_pricing_degraded_total")
budgetAdmittedDefaultTotal = expvar.NewMap("office_budget_admitted_default_total")
budgetAdmittedDegradedWindowTotal = expvar.NewMap("office_budget_admitted_degraded_window_total")
)
// expvar maps for AC-OFFICE-BUDGET-006.6's seven additional counters, one
// per state AC-OFFICE-BUDGET-006.5 names beyond the nine above: two
// deferral-attempt counters for the causes AC-OFFICE-BUDGET-005.4's literal
// enumeration omits (unevaluated-policy, project-lookup-error --
// workspace-lookup deferral already has budgetDeferredWorkspaceLookupTotal
// above), three MaxRetryCount-failure counters, one per AC-OFFICE-BUDGET-
// 006.4 cause (the "evaluator error itself" is explicitly out of that
// criterion's scope, so it is not a fourth), and two AC-OFFICE-BUDGET-006.7
// cancellation counters. Kept in a separate var block from the nine above
// because they answer a distinct criterion, not a revision of it.
var (
budgetDeferredUnevaluatedPolicyTotal = expvar.NewMap("office_budget_deferred_unevaluated_policy_total")
budgetDeferredProjectLookupTotal = expvar.NewMap("office_budget_deferred_project_lookup_total")
budgetFailedWorkspaceLookupTotal = expvar.NewMap("office_budget_failed_workspace_lookup_total")
budgetFailedUnevaluatedPolicyTotal = expvar.NewMap("office_budget_failed_unevaluated_policy_total")
budgetFailedProjectLookupTotal = expvar.NewMap("office_budget_failed_project_lookup_total")
budgetCancelledUnparseablePayload = expvar.NewMap("office_budget_cancelled_unparseable_payload_total")
budgetCancelledTaskNotFoundTotal = expvar.NewMap("office_budget_cancelled_task_not_found_total")
)
// provenanceLabel renders a run's provenance as the "provenance=..." expvar
// map key every counter in this file shares.
func provenanceLabel(p shared.RunProvenance) string {
if p.Attended() {
return "provenance=attended"
}
return "provenance=unattended"
}
func incBudgetBlockedByLimit(p shared.RunProvenance) {
budgetBlockedByLimitTotal.Add(provenanceLabel(p), 1)
}
func incBudgetDeferredEvaluatorFault(p shared.RunProvenance) {
budgetDeferredEvaluatorFaultTotal.Add(provenanceLabel(p), 1)
}
func incBudgetBlockedAbsentEvaluator(p shared.RunProvenance) {
budgetBlockedAbsentEvaluatorTotal.Add(provenanceLabel(p), 1)
}
func incBudgetDeferredWorkspaceLookup(p shared.RunProvenance) {
budgetDeferredWorkspaceLookupTotal.Add(provenanceLabel(p), 1)
}
func incBudgetCancelledNoWorkspace(p shared.RunProvenance) {
budgetCancelledNoWorkspaceTotal.Add(provenanceLabel(p), 1)
}
func incBudgetCancelledStaleDeferral(p shared.RunProvenance) {
budgetCancelledStaleDeferralTotal.Add(provenanceLabel(p), 1)
}
func incBudgetBlockedPricingDegraded(p shared.RunProvenance) {
budgetBlockedPricingDegradedTotal.Add(provenanceLabel(p), 1)
}
func incBudgetAdmittedDefault(p shared.RunProvenance) {
budgetAdmittedDefaultTotal.Add(provenanceLabel(p), 1)
}
// incBudgetAdmittedDegradedWindow implements AC-OFFICE-BUDGET-005.4's carved
// out rule for this one counter: callers must only invoke this at a point
// where the run's final disposition is already known to be launch, and only
// when at least one evaluated policy or the default was degraded-admitted
// (isDegradedAdmitted) -- never once per AC-OFFICE-BUDGET-004.8 activity
// entry, since a later gate can still block the run after that entry is
// written.
func incBudgetAdmittedDegradedWindow(p shared.RunProvenance) {
budgetAdmittedDegradedWindowTotal.Add(provenanceLabel(p), 1)
}
func incBudgetDeferredUnevaluatedPolicy(p shared.RunProvenance) {
budgetDeferredUnevaluatedPolicyTotal.Add(provenanceLabel(p), 1)
}
func incBudgetDeferredProjectLookup(p shared.RunProvenance) {
budgetDeferredProjectLookupTotal.Add(provenanceLabel(p), 1)
}
func incBudgetFailedWorkspaceLookup(p shared.RunProvenance) {
budgetFailedWorkspaceLookupTotal.Add(provenanceLabel(p), 1)
}
func incBudgetFailedUnevaluatedPolicy(p shared.RunProvenance) {
budgetFailedUnevaluatedPolicyTotal.Add(provenanceLabel(p), 1)
}
func incBudgetFailedProjectLookup(p shared.RunProvenance) {
budgetFailedProjectLookupTotal.Add(provenanceLabel(p), 1)
}
func incBudgetCancelledUnparseablePayload(p shared.RunProvenance) {
budgetCancelledUnparseablePayload.Add(provenanceLabel(p), 1)
}
func incBudgetCancelledTaskNotFound(p shared.RunProvenance) {
budgetCancelledTaskNotFoundTotal.Add(provenanceLabel(p), 1)
}
// incBudgetFailedNoEscalation increments the MaxRetryCount-failure counter
// matching cause, per AC-OFFICE-BUDGET-006.6's "not one counter shared
// across the three" rule. The evaluator-fault-proper cause is deliberately
// not routed here: AC-OFFICE-BUDGET-006.4 excludes "the evaluator error
// itself" from its own three named causes.
func incBudgetFailedNoEscalation(cause budgetDeferralCause, p shared.RunProvenance) {
switch cause {
case budgetDeferralUnevaluatedPolicy:
incBudgetFailedUnevaluatedPolicy(p)
case budgetDeferralProjectLookupError:
incBudgetFailedProjectLookup(p)
}
}
@@ -0,0 +1,382 @@
package service_test
// Covers AC-OFFICE-BUDGET-005.4: nine /debug/vars counters, one per
// individually-observable admission state, each labelled by run provenance.
// Each test drives a real admission decision (mostly via fakeBudgetEvaluator,
// as budget_admission_test.go already does) and asserts the exact counter
// bumps by exactly one, and that sibling counters for other states do not
// move -- so a mislabelled or misplaced increment fails loudly rather than
// only being caught by a coincidentally-passing total.
import (
"context"
"testing"
"time"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/service"
)
const (
metricBlockedByLimit = "office_budget_blocked_by_limit_total"
metricDeferredEvalFault = "office_budget_deferred_evaluator_fault_total"
metricBlockedNoEvaluator = "office_budget_blocked_absent_evaluator_total"
metricDeferredWorkspace = "office_budget_deferred_workspace_lookup_total"
metricCancelledNoWS = "office_budget_cancelled_no_workspace_total"
metricCancelledStale = "office_budget_cancelled_stale_deferral_total"
metricBlockedDegraded = "office_budget_blocked_pricing_degraded_total"
metricAdmittedDefault = "office_budget_admitted_default_total"
metricAdmittedDegradedWin = "office_budget_admitted_degraded_window_total"
labelUnattended = "provenance=unattended"
labelAttended = "provenance=attended"
)
func TestAdmitRun_MetricBlockedByLimit(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{
Decision: models.PreLaunchDecisionBlockedByLimit,
DecidingPolicy: &models.PreLaunchPolicyResult{PolicyID: "p-limit", LimitExceeded: true},
}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended)
beforeDegraded := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended)
agent := makeAgent("worker-metric-blocked-limit", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricBlockedByLimit, labelUnattended, got, before+1)
}
if got := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended); got != beforeDegraded {
t.Errorf("%s[%s] = %d, want unchanged %d", metricBlockedDegraded, labelUnattended, got, beforeDegraded)
}
}
func TestAdmitRun_MetricBlockedPricingDegraded(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchResult: models.PreLaunchResult{
Decision: models.PreLaunchDecisionBlockedByDegradation,
DecidingPolicy: &models.PreLaunchPolicyResult{
PolicyID: "p-degraded", LimitExceeded: false, Degraded: true, DegradationBlocked: true,
},
}}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended)
beforeLimit := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended)
agent := makeAgent("worker-metric-blocked-degraded", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricBlockedDegraded, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricBlockedDegraded, labelUnattended, got, before+1)
}
if got := service.BudgetMetricValueForTest(t, metricBlockedByLimit, labelUnattended); got != beforeLimit {
t.Errorf("%s[%s] = %d, want unchanged %d", metricBlockedByLimit, labelUnattended, got, beforeLimit)
}
}
func TestAdmitRun_MetricDeferredEvaluatorFault(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricDeferredEvalFault, labelAttended)
agent := makeAgent("worker-metric-deferred-fault", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestTask(t, svc, "task-metric-deferred-fault", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-metric-deferred-fault"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricDeferredEvalFault, labelAttended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricDeferredEvalFault, labelAttended, got, before+1)
}
}
func TestAdmitRun_MetricBlockedAbsentEvaluator(t *testing.T) {
svc := newTestService(t)
svc.SetBudgetChecker(nil)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricBlockedNoEvaluator, labelUnattended)
agent := makeAgent("worker-metric-no-evaluator", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricBlockedNoEvaluator, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricBlockedNoEvaluator, labelUnattended, got, before+1)
}
}
// TestAdmitRun_MetricDeferredWorkspaceLookup covers the one counter whose
// cause never reaches admitRun at all (W2 disposition): a genuine
// GetAgentFromConfig I/O error, instrumented at its existing call site in
// processRun. AC-OFFICE-BUDGET-001.13 gives this a different disposition
// than a lookup that succeeds and finds no row (see
// TestProcessRun_AgentRowDeleted_Cancels below): the query is broken by
// dropping the underlying table after the agent, so the earlier
// create/queue/claim calls that also read it succeed normally and only the
// processRun call under test observes the failure -- a real, non-ErrNoRows
// error, not a simulation of one.
func TestAdmitRun_MetricDeferredWorkspaceLookup(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended)
agent := makeAgent("worker-metric-lookup-error", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DROP TABLE agent_profiles`)
service.ProcessRunForTest(svc, ctx, run)
if got := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricDeferredWorkspace, labelUnattended, got, before+1)
}
}
// TestProcessRun_AgentRowDeleted_Cancels covers AC-OFFICE-BUDGET-001.13's
// other workspace-lookup disposition: the lookup itself succeeds (no I/O
// error) but finds no row, because the agent was deleted after the run was
// queued. Unlike a lookup error (deferred/retried above), this is
// cancelled -- an orphaned run has no workspace and so no ceiling that
// could ever be evaluated -- and must never reach MaxRetryCount or
// escalate. Drives it through the real processRun pipeline (not
// AdmitRunForTest, which only reaches admitRun's separate, structurally
// unreachable-in-production gate-1 branch for an agent found with an empty
// WorkspaceID -- see TestAdmitRun_MetricCancelledNoWorkspace above).
func TestProcessRun_AgentRowDeleted_Cancels(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
beforeCancelled := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended)
beforeDeferred := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended)
agent := makeAgent("worker-metric-agent-deleted", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
svc.ExecSQL(t, `DELETE FROM agent_profiles WHERE id = ?`, agent.ID)
service.ProcessRunForTest(svc, ctx, run)
if got := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended); got != beforeCancelled+1 {
t.Errorf("%s[%s] = %d, want %d", metricCancelledNoWS, labelUnattended, got, beforeCancelled+1)
}
if got := service.BudgetMetricValueForTest(t, metricDeferredWorkspace, labelUnattended); got != beforeDeferred {
t.Errorf("%s[%s] = %d, want unchanged %d (a deleted agent must cancel, not defer)",
metricDeferredWorkspace, labelUnattended, got, beforeDeferred)
}
got, err := svc.GetRun(ctx, run.ID)
if err != nil {
t.Fatalf("get run: %v", err)
}
if got.Status != service.RunStatusCancelled {
t.Errorf("run status = %q, want %q", got.Status, service.RunStatusCancelled)
}
if got.RetryCount != 0 {
t.Errorf("retry_count = %d, want 0 (cancelled, never retried)", got.RetryCount)
}
}
// TestAdmitRun_MetricCancelledNoWorkspace covers gate 1 via AdmitRunForTest
// rather than the full scheduler pipeline: GetAgentFromConfig's own
// agentInstanceFilter (workspace_id must be non-empty) means a real
// ClaimNextRun/processRun cycle can never hand admitRun an agent with an
// empty WorkspaceID, mirroring resolveRunProject's already-documented
// unreachable branches. The gate 1 code path itself is real and still needs
// coverage.
func TestAdmitRun_MetricCancelledNoWorkspace(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended)
agent := makeAgent("worker-metric-no-workspace", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
unresolvedAgent := *agent
unresolvedAgent.WorkspaceID = ""
service.AdmitRunForTest(svc, ctx, run, &unresolvedAgent)
if got := service.BudgetMetricValueForTest(t, metricCancelledNoWS, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricCancelledNoWS, labelUnattended, got, before+1)
}
}
// TestAdmitRun_MetricCancelledStaleDeferral drives admitBudgetDeferral's
// stale branch by backdating a claimed run's RequestedAt past retryMaxAge,
// mirroring the RetryCount mutation the MaxRetryCount test in
// budget_admission_test.go already uses to reach a similar deep branch.
func TestAdmitRun_MetricCancelledStaleDeferral(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{preLaunchErr: context.DeadlineExceeded}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricCancelledStale, labelUnattended)
agent := makeAgent("worker-metric-stale-deferral", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
run, err := svc.ClaimNextRun(ctx)
if err != nil || run == nil {
t.Fatalf("claim: %v", err)
}
run.RequestedAt = time.Now().Add(-25 * time.Hour)
service.ProcessRunForTest(svc, ctx, run)
if got := service.BudgetMetricValueForTest(t, metricCancelledStale, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricCancelledStale, labelUnattended, got, before+1)
}
}
func TestAdmitRun_MetricAdmittedDefault(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch},
defaultResult: models.PreLaunchPolicyResult{IsDefault: true},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricAdmittedDefault, labelUnattended)
beforeDegraded := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended)
agent := makeAgent("worker-metric-admitted-default", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricAdmittedDefault, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricAdmittedDefault, labelUnattended, got, before+1)
}
if got := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended); got != beforeDegraded {
t.Errorf("%s[%s] = %d, want unchanged %d (default was not degraded)", metricAdmittedDegradedWin, labelUnattended, got, beforeDegraded)
}
}
// TestAdmitRun_MetricAdmittedDegradedWindow_ViaDefault covers the gate-5
// branch of AC-OFFICE-BUDGET-005.4's carved-out counter: the default's
// window was degraded but did not block, and the run still launches.
func TestAdmitRun_MetricAdmittedDegradedWindow_ViaDefault(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchResult: models.PreLaunchResult{Decision: models.PreLaunchDecisionLaunch},
defaultResult: models.PreLaunchPolicyResult{
IsDefault: true, Degraded: true, DegradationBlocked: false, LimitExceeded: false,
},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended)
agent := makeAgent("worker-metric-degraded-default", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonRoutineTrigger, `{}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelUnattended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricAdmittedDegradedWin, labelUnattended, got, before+1)
}
}
// TestAdmitRun_MetricAdmittedDegradedWindow_ViaStoredPolicyBypassingGate5
// covers the other launch point that can carry a degraded-admitted policy:
// an attended run, whose provenance bypasses gate 5 entirely, but which was
// still admitted against a stored policy's degraded window at gate 4.
func TestAdmitRun_MetricAdmittedDegradedWindow_ViaStoredPolicyBypassingGate5(t *testing.T) {
svc := newTestService(t)
fake := &fakeBudgetEvaluator{
preLaunchResult: models.PreLaunchResult{
Decision: models.PreLaunchDecisionLaunch,
Policies: []models.PreLaunchPolicyResult{
{PolicyID: "p-degraded-admitted", Degraded: true, DegradationBlocked: false, LimitExceeded: false},
},
},
}
svc.SetBudgetChecker(fake)
ctx := context.Background()
before := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelAttended)
agent := makeAgent("worker-metric-degraded-attended", models.AgentRoleWorker)
if err := svc.CreateAgentInstance(ctx, agent); err != nil {
t.Fatalf("create agent: %v", err)
}
insertTestTask(t, svc, "task-metric-degraded-attended", "ws-1")
if err := svc.QueueRun(ctx, agent.ID, service.RunReasonTaskAssigned,
`{"task_id":"task-metric-degraded-attended"}`, ""); err != nil {
t.Fatalf("queue: %v", err)
}
service.RunSchedulerTick(svc, ctx)
if got := service.BudgetMetricValueForTest(t, metricAdmittedDegradedWin, labelAttended); got != before+1 {
t.Errorf("%s[%s] = %d, want %d", metricAdmittedDegradedWin, labelAttended, got, before+1)
}
}
@@ -0,0 +1,146 @@
package service
import (
"context"
"strconv"
"strings"
"time"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/office/models"
)
const (
actionBudgetPolicySkipped = "run_budget_policy_skipped"
actionBudgetPolicyDegradedAdmitted = "run_budget_policy_degraded_admitted"
)
// utcDayStart returns the UTC midnight at or before at, the dedup boundary
// AC-OFFICE-BUDGET-002.13 and AC-OFFICE-BUDGET-004.8 share.
func utcDayStart(at time.Time) time.Time {
u := at.UTC()
return time.Date(u.Year(), u.Month(), u.Day(), 0, 0, 0, 0, time.UTC)
}
// skipIssueLabels renders a stored policy's PolicyValidationIssues as a
// stable, sorted list of short field names, so one activity entry can name
// every violation a policy has at once (AC-OFFICE-BUDGET-002.13), rather
// than one entry per violated field.
func skipIssueLabels(issues models.PolicyValidationIssues) []string {
var out []string
if issues.UnrecognizedPeriod {
out = append(out, "unrecognized_period")
}
if issues.NonPositiveLimit {
out = append(out, "non_positive_limit")
}
if issues.UnrecognizedScope {
out = append(out, "unrecognized_scope")
}
if issues.UnrecognizedAction {
out = append(out, "unrecognized_action")
}
if issues.EmptyScopeID {
out = append(out, "empty_scope_id")
}
return out
}
// skippedPolicyFields renders a skipped policy's activity-entry fields.
// AC-OFFICE-BUDGET-002.5 requires naming the unrecognized period value and
// AC-OFFICE-BUDGET-002.11 requires naming the non-positive limit itself,
// alongside the policy id and the (already-present) issue labels that
// satisfy AC-OFFICE-BUDGET-002.14's "offending field" for the remaining
// issues.
func skippedPolicyFields(p *models.PreLaunchPolicyResult) map[string]string {
fields := map[string]string{
"policy_id": p.PolicyID,
"issues": strings.Join(skipIssueLabels(p.SkipIssues), ","),
}
if p.SkipIssues.UnrecognizedPeriod {
fields["period"] = string(p.Period)
}
if p.SkipIssues.NonPositiveLimit {
fields["limit_subcents"] = strconv.FormatInt(p.LimitSubcents, 10)
}
return fields
}
// isDegradedAdmitted reports whether p's window was pricing-degraded but did
// not itself block the run -- the condition AC-OFFICE-BUDGET-004.4/-004.7/
// -004.8's activity entry and AC-OFFICE-BUDGET-005.4's "admitted against a
// pricing-degraded window" counter share.
func isDegradedAdmitted(p *models.PreLaunchPolicyResult) bool {
return p.Degraded && !p.DegradationBlocked && !p.LimitExceeded
}
// anyDegradedAdmitted reports whether any policy in policies satisfies
// isDegradedAdmitted, for admitRun's AC-OFFICE-BUDGET-005.4 counter, which
// must fire at most once per run regardless of how many policies qualify.
func anyDegradedAdmitted(policies []models.PreLaunchPolicyResult) bool {
for i := range policies {
if isDegradedAdmitted(&policies[i]) {
return true
}
}
return false
}
// logPolicyObservability writes the operator-visible entries
// AC-OFFICE-BUDGET-002.5/-002.11/-002.14 (a stored policy this build cannot
// evaluate, skipped) and AC-OFFICE-BUDGET-004.4/-004.7/-004.8 (a policy's
// window was pricing-degraded but did not block via degradation) require,
// each deduplicated at most once per policy per UTC day
// (AC-OFFICE-BUDGET-002.13). Called once per admission evaluation of a set
// of policies (the stored policies from EvaluatePreLaunch, or a single
// built-in default result from EvaluateDefaultCeiling) independent of the
// run's final decision: AC-OFFICE-BUDGET-005.4 states the degraded-admitted
// entry is written per non-blocking-degraded policy even when a later
// policy or gate 5 still blocks the run overall — only the *counter*, not
// this entry, is conditioned on the run's final disposition; see
// incBudgetAdmittedDegradedWindow's own call sites in budget_admission.go
// for where that conditioning happens.
func (si *SchedulerIntegration) logPolicyObservability(
ctx context.Context, workspaceID, runID string, policies []models.PreLaunchPolicyResult, at time.Time,
) {
day := utcDayStart(at)
for i := range policies {
p := &policies[i]
switch {
case p.Skipped:
si.logOncePerPolicyPerDay(ctx, workspaceID, runID, actionBudgetPolicySkipped, p.PolicyID, day,
skippedPolicyFields(p))
case isDegradedAdmitted(p):
fields := map[string]string{"degraded": strconv.FormatBool(true)}
if p.IsDefault {
fields[activityFieldCeiling] = ceilingBuiltInDefault
} else {
fields["policy_id"] = p.PolicyID
}
si.logOncePerPolicyPerDay(ctx, workspaceID, runID, actionBudgetPolicyDegradedAdmitted, p.PolicyID, day, fields)
}
}
}
// logOncePerPolicyPerDay writes one activity entry for (workspaceID, action,
// targetID) unless one already exists with created_at on or after day.
// Best-effort under concurrency, per AC-OFFICE-BUDGET-002.13: two runs
// evaluating the same policy concurrently may each observe no entry yet and
// each write one. A duplicate is acceptable; this bound exists to stop a
// per-evaluation stream, not to guarantee uniqueness.
func (si *SchedulerIntegration) logOncePerPolicyPerDay(
ctx context.Context, workspaceID, runID, action, targetID string, day time.Time, fields map[string]string,
) {
exists, err := si.svc.repo.HasActivityToday(ctx, workspaceID, action, targetID, day)
if err != nil {
si.logger.Warn("failed to check budget activity dedup",
zap.String("action", action), zap.String("target_id", targetID), zap.Error(err))
return
}
if exists {
return
}
si.svc.LogActivityWithRun(ctx, workspaceID, "scheduler", "office-scheduler",
action, "policy", targetID, mustJSON(fields), runID, "")
}
@@ -0,0 +1,203 @@
package service_test
// Covers AC-OFFICE-BUDGET-002.5/-002.11/-002.14 (a stored policy this build
// cannot evaluate is skipped, and the skip is operator-visible), and
// AC-OFFICE-BUDGET-004.4/-004.7/-004.8 (a pricing-degraded, non-blocking
// policy is operator-visible too), plus the AC-OFFICE-BUDGET-002.13
// at-most-once-per-policy-per-UTC-day dedup bound both share.
import (
"context"
"strings"
"testing"
"time"
"github.com/kandev/kandev/internal/office/models"
"github.com/kandev/kandev/internal/office/service"
)
func activityDetails(t *testing.T, svc *service.Service, wsID, action string) (string, bool) {
t.Helper()
entries, err := svc.ListActivity(context.Background(), wsID, 50)
if err != nil {
t.Fatalf("list activity: %v", err)
}
for _, e := range entries {
if string(e.Action) == action {
return e.Details, true
}
}
return "", false
}
func countActivityAction(t *testing.T, svc *service.Service, wsID, action string) int {
t.Helper()
entries, err := svc.ListActivity(context.Background(), wsID, 50)
if err != nil {
t.Fatalf("list activity: %v", err)
}
n := 0
for _, e := range entries {
if string(e.Action) == action {
n++
}
}
return n
}
// TestLogPolicyObservability_SkippedPolicy_NamesPolicyAndIssues covers
// AC-OFFICE-BUDGET-002.5/-002.11/-002.14: a skipped policy's entry names
// the policy and every violated field, not just one.
func TestLogPolicyObservability_SkippedPolicy_NamesPolicyAndIssues(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
policies := []models.PreLaunchPolicyResult{
{
PolicyID: "policy-skip-1",
Skipped: true,
SkipIssues: models.PolicyValidationIssues{
NonPositiveLimit: true,
UnrecognizedScope: true,
},
},
}
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
details, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_skipped")
if !ok {
t.Fatal("expected run_budget_policy_skipped activity entry")
}
if !strings.Contains(details, "policy-skip-1") {
t.Errorf("details = %q, want policy id policy-skip-1", details)
}
if !strings.Contains(details, "non_positive_limit") || !strings.Contains(details, "unrecognized_scope") {
t.Errorf("details = %q, want both violated issues named", details)
}
}
// TestLogPolicyObservability_SkippedPolicy_DedupedPerDay covers
// AC-OFFICE-BUDGET-002.13: the same policy's skip is recorded at most once
// per UTC day, not once per evaluation.
func TestLogPolicyObservability_SkippedPolicy_DedupedPerDay(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
policies := []models.PreLaunchPolicyResult{
{PolicyID: "policy-skip-dedup", Skipped: true, SkipIssues: models.PolicyValidationIssues{NonPositiveLimit: true}},
}
now := time.Now()
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, now)
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-2", policies, now)
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-3", policies, now)
if n := countActivityAction(t, svc, "ws-1", "run_budget_policy_skipped"); n != 1 {
t.Errorf("run_budget_policy_skipped entries = %d, want exactly 1 (deduped)", n)
}
}
// TestLogPolicyObservability_SkippedPolicy_NewDayWritesAgain covers the
// other side of AC-OFFICE-BUDGET-002.13's bound: the dedup is per UTC day,
// not forever, so a later day's evaluation writes a fresh entry. The first
// entry is backdated directly (CreateActivityEntry always stamps real
// wall-clock time, not the evaluation instant passed to
// logPolicyObservability, which is always time.Now().UTC() in production)
// to simulate "written yesterday" without waiting a real day.
func TestLogPolicyObservability_SkippedPolicy_NewDayWritesAgain(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
policies := []models.PreLaunchPolicyResult{
{PolicyID: "policy-skip-newday", Skipped: true, SkipIssues: models.PolicyValidationIssues{NonPositiveLimit: true}},
}
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
svc.ExecSQL(t, `UPDATE office_activity_log SET created_at = ? WHERE action = ?`,
time.Now().UTC().Add(-25*time.Hour), "run_budget_policy_skipped")
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-2", policies, time.Now())
if n := countActivityAction(t, svc, "ws-1", "run_budget_policy_skipped"); n != 2 {
t.Errorf("run_budget_policy_skipped entries across two days = %d, want 2", n)
}
}
// TestLogPolicyObservability_DegradedNonBlocking_WritesAdmittedEntry covers
// AC-OFFICE-BUDGET-004.4/-004.7: a policy whose window was pricing-degraded
// but which did not block (degradation exempted it, or the limit was not
// reached) gets an operator-visible, distinctly-actioned entry.
func TestLogPolicyObservability_DegradedNonBlocking_WritesAdmittedEntry(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
policies := []models.PreLaunchPolicyResult{
{PolicyID: "policy-degraded-1", Degraded: true, DegradationBlocked: false, LimitExceeded: false},
}
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
details, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted")
if !ok {
t.Fatal("expected run_budget_policy_degraded_admitted activity entry")
}
if !strings.Contains(details, "policy-degraded-1") {
t.Errorf("details = %q, want policy id policy-degraded-1", details)
}
}
// TestLogPolicyObservability_DegradedButLimitExceeded_NoAdmittedEntry
// covers AC-OFFICE-BUDGET-004.6: when the limit was also reached, the
// degradation fact belongs on the block entry alone (already carried by
// finishPolicyBlock's "degraded" field) -- this policy is not "admitted",
// so it must not also get a degraded-admitted entry.
func TestLogPolicyObservability_DegradedButLimitExceeded_NoAdmittedEntry(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
policies := []models.PreLaunchPolicyResult{
{PolicyID: "policy-degraded-exceeded", Degraded: true, DegradationBlocked: false, LimitExceeded: true},
}
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
if _, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted"); ok {
t.Error("a policy whose limit was exceeded must not get a degraded-admitted entry")
}
}
// TestLogPolicyObservability_DegradedAndBlocked_NoAdmittedEntry covers the
// symmetric case: a policy whose degradation criterion itself blocked
// (DegradationBlocked) is reported via the block entry, not this one.
func TestLogPolicyObservability_DegradedAndBlocked_NoAdmittedEntry(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
policies := []models.PreLaunchPolicyResult{
{PolicyID: "policy-degraded-blocked", Degraded: true, DegradationBlocked: true, LimitExceeded: false},
}
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", policies, time.Now())
if _, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted"); ok {
t.Error("a policy that blocked via degradation must not also get a degraded-admitted entry")
}
}
// TestLogPolicyObservability_DefaultCeilingDegraded_NamesBuiltInDefault
// covers AC-OFFICE-BUDGET-004.8's "or stating that the ceiling was the
// built-in default" alternative to naming a policy id.
func TestLogPolicyObservability_DefaultCeilingDegraded_NamesBuiltInDefault(t *testing.T) {
svc := newTestService(t)
ctx := context.Background()
def := models.PreLaunchPolicyResult{
IsDefault: true, Degraded: true, DegradationBlocked: false, LimitExceeded: false,
}
service.LogPolicyObservabilityForTest(svc, ctx, "ws-1", "run-1", []models.PreLaunchPolicyResult{def}, time.Now())
details, ok := activityDetails(t, svc, "ws-1", "run_budget_policy_degraded_admitted")
if !ok {
t.Fatal("expected run_budget_policy_degraded_admitted activity entry for the built-in default")
}
if !strings.Contains(details, "built_in_default") {
t.Errorf("details = %q, want the built-in default named", details)
}
}
@@ -2,6 +2,8 @@ package service
import (
"context"
"database/sql"
"errors"
"fmt"
"github.com/kandev/kandev/internal/office/models"
@@ -13,16 +15,30 @@ func (s *Service) ListAgentsFromConfig(ctx context.Context, workspaceID string)
return s.repo.ListAgentInstances(ctx, workspaceID)
}
// GetAgentFromConfig looks up an agent by ID or name.
// GetAgentFromConfig looks up an agent by ID or name. The error it returns
// wraps sql.ErrNoRows if, and only if, both underlying lookups genuinely
// found no matching row -- never if either failed for another reason (a
// transient I/O error). Callers that must tell "no such agent" apart from
// a transient failure (AC-OFFICE-BUDGET-001.13) use errors.Is(err,
// sql.ErrNoRows) rather than a second lookup or a new sentinel type; this
// is the same two calls as before, just no longer collapsing a real error
// into the generic not-found string.
func (s *Service) GetAgentFromConfig(ctx context.Context, idOrName string) (*models.AgentInstance, error) {
if agent, err := s.repo.GetAgentInstance(ctx, idOrName); err == nil {
agent, errByID := s.repo.GetAgentInstance(ctx, idOrName)
if errByID == nil {
return agent, nil
}
agent, err := s.repo.GetAgentInstanceByNameAny(ctx, idOrName)
if err != nil {
return nil, fmt.Errorf("agent not found: %s", idOrName)
agent, errByName := s.repo.GetAgentInstanceByNameAny(ctx, idOrName)
if errByName == nil {
return agent, nil
}
return agent, nil
if !errors.Is(errByID, sql.ErrNoRows) {
return nil, errByID
}
if !errors.Is(errByName, sql.ErrNoRows) {
return nil, errByName
}
return nil, fmt.Errorf("agent not found: %s: %w", idOrName, sql.ErrNoRows)
}
// ListSkillsFromConfig returns all skills for a workspace.
@@ -148,6 +148,36 @@ func (s *Service) escalateFailure(
return nil
}
// failRunNoEscalation performs escalateFailure's non-escalating half for a
// budget-admission fault (AC-OFFICE-BUDGET-001.17/-006.4): it marks the run
// permanently failed and records one operator-visible activity entry
// naming cause, but does not re-fetch the agent and does not call
// queueCEOAgentError. A run failed by a budget-admission fault must not
// queue any new run, by any path.
func (s *Service) failRunNoEscalation(
ctx context.Context, run *models.Run, agent *models.AgentInstance,
cause budgetDeferralCause, policyID string,
) error {
if err := s.FailRun(ctx, run.ID); err != nil {
return fmt.Errorf("fail run: %w", err)
}
s.clearAgentWorking(ctx, run.AgentProfileID, run.ID)
fields := map[string]string{activityFieldCeiling: ceilingNotDetermined}
if policyID != "" {
fields["policy_id"] = policyID
}
s.LogActivityWithRun(ctx, agent.WorkspaceID, "system", "scheduler",
cause.failedAction(), "agent", run.AgentProfileID,
mustJSON(fields), run.ID, "")
s.logger.Warn("run permanently failed by budget admission fault",
zap.String("run_id", run.ID),
zap.String("agent", agent.Name),
zap.Int("retry_count", run.RetryCount))
return nil
}
// queueCEOAgentError finds the CEO agent in the workspace and queues an
// agent_error run for it. When the failing run's agent IS the CEO, the
// escalation is skipped rather than re-queuing the CEO to handle its own
+7 -6
View File
@@ -56,16 +56,17 @@ const (
// Run outcome constants (docs/specs/task-delivery-ledger/spec.md, "Office run
// outcome"). Written into runs.outcome alongside status='finished' at each of
// the six terminal call sites; NULL on the failed path and on every
// the seven terminal call sites; NULL on the failed path and on every
// pre-activation row. RunOutcomeProcessed is the only value
// RunCountsByDayForAgent counts as succeeded. Every other value buckets into
// skipped.
const (
RunOutcomeProcessed = "processed"
RunOutcomeBudgetBlocked = "budget_blocked"
RunOutcomeIdleSkipped = "idle_skipped"
RunOutcomeAgentInactive = "agent_inactive"
RunOutcomeTaskTreeHeld = "task_tree_held"
RunOutcomeProcessed = "processed"
RunOutcomeBudgetBlocked = "budget_blocked"
RunOutcomeIdleSkipped = "idle_skipped"
RunOutcomeAgentInactive = "agent_inactive"
RunOutcomeTaskTreeHeld = "task_tree_held"
RunOutcomeBudgetUnmeasurable = "budget_unmeasurable"
)
// CoalesceWindowSeconds is the default coalescing window.
@@ -2,6 +2,8 @@ package service
import (
"context"
"database/sql"
"errors"
"fmt"
"time"
@@ -201,12 +203,25 @@ func (si *SchedulerIntegration) processRun(ctx context.Context, run *models.Run)
"reason": run.Reason,
})
// Guard: check agent status.
// Guard: check agent status. AC-OFFICE-BUDGET-001.13 gives the two ways
// this lookup can fail different dispositions: a genuine "no such
// agent" (soft-deleted or never existed) is cancelled, never retried or
// escalated, since an orphaned run has no workspace and therefore no
// ceiling that could ever be evaluated; a transient lookup error is
// deferred/retried on the same terms as an evaluator fault and, at
// MaxRetryCount, failed without escalation (AC-OFFICE-BUDGET-006.4) --
// neither disposition may queue a run for any other agent
// (AC-OFFICE-BUDGET-001.17), so neither uses the generic
// HandleRunFailure/escalateFailure path, which does exactly that.
agent, err := si.svc.GetAgentFromConfig(ctx, agentInstanceID)
if err != nil {
si.logger.Error("failed to get agent instance",
zap.String("run_id", runID), zap.Error(err))
_ = si.svc.HandleRunFailure(ctx, run, err)
if errors.Is(err, sql.ErrNoRows) {
si.cancelUnresolvableAgentRun(ctx, run)
return
}
si.deferWorkspaceLookupFailure(ctx, run)
return
}
@@ -254,8 +269,8 @@ func (si *SchedulerIntegration) processRun(ctx context.Context, run *models.Run)
return
}
// Pre-execution budget check.
if !si.checkBudget(ctx, run, agent, taskID) {
// Pre-launch budget admission (AC-OFFICE-BUDGET-001.14's five gates).
if !si.admitRun(ctx, run, agent) {
return
}
@@ -831,38 +846,6 @@ func (si *SchedulerIntegration) requeueContendedCheckout(ctx context.Context, ru
}
}
// checkBudget runs pre-execution budget checks. Returns true if allowed.
func (si *SchedulerIntegration) checkBudget(
ctx context.Context, run *models.Run,
agent *models.AgentInstance, taskID string,
) bool {
projectID := si.extractProjectID(ctx, run.Payload)
allowed, reason, err := si.svc.CheckPreExecutionBudget(
ctx, agent.ID, projectID, agent.WorkspaceID)
if err != nil {
si.logger.Error("budget check failed",
zap.String("run_id", run.ID), zap.Error(err))
return true // fail-open on error
}
if !allowed {
si.logger.Info("run skipped (budget exceeded)",
zap.String("run_id", run.ID), zap.String("reason", reason))
si.releaseCheckoutIfNeeded(ctx, run)
si.svc.clearAgentWorking(ctx, agent.ID, run.ID)
_ = si.svc.FinishRun(ctx, run.ID, RunOutcomeBudgetBlocked)
si.svc.LogActivityWithRun(ctx, agent.WorkspaceID,
"scheduler", "office-scheduler",
"run_budget_blocked", "run", run.ID,
mustJSON(map[string]string{
"agent": agent.Name,
"agent_id": agent.ID,
"reason": reason,
}), run.ID, "")
return false
}
return true
}
// releaseCheckoutIfNeeded releases the task checkout the given run may hold.
// Delegates to the owner-scoped releaseTaskCheckoutForRun (Review round 3)
// rather than the unscoped repo.ReleaseTaskCheckout: every call site here
@@ -4,11 +4,13 @@ package service
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"regexp"
"strings"
"time"
"github.com/kandev/kandev/internal/agentctl/types/streams"
"github.com/kandev/kandev/internal/common/logger"
@@ -360,6 +362,22 @@ type BudgetEvaluator interface {
// pause). The office service discards the per-policy results; the
// costs package is responsible for any side effects.
EvaluateBudget(ctx context.Context, workspaceID, agentInstanceID, projectID string) error
// EvaluatePreLaunch and EvaluateDefaultCeiling back the pre-launch
// admission gates of REQ-OFFICE-BUDGET-001/-003/-006
// (internal/office/service/budget_admission.go). Unlike
// CheckPreExecutionBudget/EvaluateBudget above, neither has a
// nil-evaluator fallback: "no evaluator wired" is its own admission gate
// (AC-OFFICE-BUDGET-001.5/.6), decided by the caller before either method
// is invoked, never a fail-open default inside it.
EvaluatePreLaunch(
ctx context.Context,
workspaceID, agentInstanceID, projectID string,
hasProject bool,
provenance shared.RunProvenance,
at time.Time,
) (models.PreLaunchResult, error)
EvaluateDefaultCeiling(ctx context.Context, workspaceID string, at time.Time) (models.PreLaunchPolicyResult, error)
}
// SetBudgetChecker wires the costs.CostService (or a test fake) as the
@@ -749,6 +767,46 @@ func (s *Service) CheckBudget(ctx context.Context, workspaceID, agentInstanceID,
return s.budgetChecker.EvaluateBudget(ctx, workspaceID, agentInstanceID, projectID)
}
// errBudgetEvaluatorNotConfigured is returned by EvaluatePreLaunch and
// EvaluateDefaultCeiling when no BudgetEvaluator is wired. Unlike
// CheckBudget's no-op, both calls always need a real disposition -- there
// is no zero-value PreLaunchResult/PreLaunchPolicyResult that means
// anything -- so a nil budgetChecker is a distinguishable error rather than
// a silent no-op. Safe today only because admitRun's gate 2
// (budget_admission.go) already checks budgetChecker == nil before either
// is ever called; this guard is what keeps a future caller that skips gate
// 2 from a nil-pointer dereference instead.
var errBudgetEvaluatorNotConfigured = errors.New("office: no budget evaluator configured")
// EvaluatePreLaunch delegates to the wired BudgetEvaluator for the
// pre-launch admission gates (budget_admission.go). Callers must check
// gate 2 (evaluator presence, s.budgetChecker == nil) themselves before
// calling this — see the BudgetEvaluator doc comment above.
func (s *Service) EvaluatePreLaunch(
ctx context.Context,
workspaceID, agentInstanceID, projectID string,
hasProject bool,
provenance shared.RunProvenance,
at time.Time,
) (models.PreLaunchResult, error) {
if s.budgetChecker == nil {
return models.PreLaunchResult{}, errBudgetEvaluatorNotConfigured
}
return s.budgetChecker.EvaluatePreLaunch(ctx, workspaceID, agentInstanceID, projectID, hasProject, provenance, at)
}
// EvaluateDefaultCeiling delegates to the wired BudgetEvaluator for gate 5
// of budget_admission.go. See EvaluatePreLaunch above for the nil-evaluator
// caveat.
func (s *Service) EvaluateDefaultCeiling(
ctx context.Context, workspaceID string, at time.Time,
) (models.PreLaunchPolicyResult, error) {
if s.budgetChecker == nil {
return models.PreLaunchPolicyResult{}, errBudgetEvaluatorNotConfigured
}
return s.budgetChecker.EvaluateDefaultCeiling(ctx, workspaceID, at)
}
// CreateBudgetPolicy creates a new budget policy.
func (s *Service) CreateBudgetPolicy(ctx context.Context, policy *models.BudgetPolicy) error {
return s.repo.CreateBudgetPolicy(ctx, policy)
@@ -2,6 +2,7 @@ package service
import (
"context"
"expvar"
"fmt"
"testing"
"time"
@@ -168,6 +169,55 @@ func ProcessRunForTest(svc *Service, ctx context.Context, run *models.Run) {
si.processRun(ctx, run)
}
// Exported mirrors of resolveRunProject's unexported projectResolution
// values, for external test packages using ResolveRunProjectForTest.
const (
ProjectResolutionNoneForTest = int(projectResolutionNone)
ProjectResolutionFoundForTest = int(projectResolutionFound)
ProjectResolutionLookupErrorForTest = int(projectResolutionLookupError)
ProjectResolutionUnparseableForTest = int(projectResolutionUnparseable)
ProjectResolutionTaskNotFoundForTest = int(projectResolutionTaskNotFound)
)
// ResolveRunProjectForTest exposes resolveRunProject for external test
// packages, so gate 4's project-resolution outcomes
// (AC-OFFICE-BUDGET-006.7) can be tested directly rather than through the
// full scheduler pipeline, which independently gates on task existence in
// checkoutTask before admitRun/resolveRunProject ever runs.
func ResolveRunProjectForTest(svc *Service, ctx context.Context, payload string) (projectID string, resolution int) {
si := &SchedulerIntegration{svc: svc, logger: svc.logger}
pid, res := si.resolveRunProject(ctx, payload)
return pid, int(res)
}
// AdmitRunForTest exposes admitRun directly for external test packages, so
// gate 1's "agent found but carries no workspace identifier" branch
// (AC-OFFICE-BUDGET-001.13) can be tested against a constructed
// *models.AgentInstance rather than through the full scheduler pipeline.
// The repository's own agentInstanceFilter (workspace_id must be non-empty) makes an
// empty-WorkspaceID agent unreachable via GetAgentFromConfig, the only real
// caller processRun uses to obtain admitRun's agent argument -- the same
// "structurally unreachable via the full pipeline, but a real and correctly
// implemented branch of the function itself" situation already recorded for
// resolveRunProject's task-not-found and lookup-error outcomes.
func AdmitRunForTest(svc *Service, ctx context.Context, run *models.Run, agent *models.AgentInstance) bool {
si := &SchedulerIntegration{svc: svc, logger: svc.logger}
return si.admitRun(ctx, run, agent)
}
// LogPolicyObservabilityForTest exposes logPolicyObservability for external
// test packages, so the skip/degraded-admitted entries and their
// per-policy-per-day dedup (AC-OFFICE-BUDGET-002.13/-004.8) can be tested
// directly against a chosen set of PreLaunchPolicyResult values, without
// needing a real admission evaluation (stored policies, spend events) to
// produce them.
func LogPolicyObservabilityForTest(
svc *Service, ctx context.Context, workspaceID, runID string, policies []models.PreLaunchPolicyResult, at time.Time,
) {
si := &SchedulerIntegration{svc: svc, logger: svc.logger}
si.logPolicyObservability(ctx, workspaceID, runID, policies, at)
}
// BuildEnvVarsForTest exposes buildEnvVars for external test packages.
func BuildEnvVarsForTest(
si *SchedulerIntegration,
@@ -202,6 +252,34 @@ func BuildSkillManifestForTest(
// with the office-tier delivery code. Coverage moved into
// internal/agent/runtime/lifecycle/skill.
// BudgetMetricValueForTest reads the current value of an AC-OFFICE-BUDGET-
// 005.4 expvar counter for external test packages, by its published
// /debug/vars name (e.g. "office_budget_blocked_by_limit_total") and map
// key (e.g. "provenance=unattended"). Reading through the global expvar
// registry, rather than the package-private *expvar.Map vars directly,
// means a test also pins the exact published name a real /debug/vars
// scrape would see. Returns 0 for a key that hasn't been incremented yet.
func BudgetMetricValueForTest(t *testing.T, name, label string) int64 {
t.Helper()
v := expvar.Get(name)
if v == nil {
t.Fatalf("no expvar registered under %q", name)
}
m, ok := v.(*expvar.Map)
if !ok {
t.Fatalf("expvar %q is a %T, want *expvar.Map", name, v)
}
got := m.Get(label)
if got == nil {
return 0
}
i, ok := got.(*expvar.Int)
if !ok {
t.Fatalf("expvar %q[%q] is a %T, want *expvar.Int", name, label, got)
}
return i.Value()
}
// GetWakeReceiptForTest exposes the repo's parent_child_wake_receipts read
// so ParentWakeReconciler tests can assert a paused/unresolved-assignee
// skip leaves no partial receipt behind.
@@ -0,0 +1,59 @@
package shared
// RunProvenance classifies a run as attended or unattended, per
// REQ-OFFICE-BUDGET-007 (docs/specs/office/requirements/budget-run-provenance.md).
// A person plausibly caused an attended run and is plausibly waiting on it.
type RunProvenance int
const (
// RunProvenanceUnattended is the safe default for any reason not on the
// attended allowlist, including one the build has never seen.
RunProvenanceUnattended RunProvenance = iota
RunProvenanceAttended
)
// Attended reports whether p classifies as attended.
func (p RunProvenance) Attended() bool { return p == RunProvenanceAttended }
// attendedRunReasons is the exact 20-literal allowlist of
// AC-OFFICE-BUDGET-007.2: 16 current reasons plus 4 legacy literals. Every
// other value, including one the build does not recognize, classifies as
// unattended (RunProvenanceUnattended's zero value).
//
// Polarity warning: this is the OPPOSITE safe default from
// IsPeriodicTasklessWake, which reads the same runs.reason column for the
// idle-skip gate. Do not reuse that classifier here — see the glossary
// (docs/specs/office/glossary.md, "Budget enforcement").
var attendedRunReasons = map[string]struct{}{
"task_assigned": {},
"task_comment": {},
"task_review_requested": {},
"task_changes_requested": {},
"task_blockers_resolved": {},
"task_children_completed": {},
"approval_resolved": {},
"routine_dispatch_event": {},
"manual_resume_after_failure": {},
"task_mentioned": {},
"task_reopened": {},
"task_reopened_via_comment": {},
"task_unblocked": {},
"task_ready_to_close": {},
"stage_pending": {},
"stage_changes_requested": {},
// Legacy literals, still reachable on rows queued before the named
// constants above existed.
"review_started": {},
"approval_started": {},
"blockers_resolved": {},
"children_completed": {},
}
// ClassifyRunProvenance implements AC-OFFICE-BUDGET-007.1/.2: a total
// function of reason, computed once per run and never revised by any gate.
func ClassifyRunProvenance(reason string) RunProvenance {
if _, ok := attendedRunReasons[reason]; ok {
return RunProvenanceAttended
}
return RunProvenanceUnattended
}
@@ -0,0 +1,218 @@
package shared_test
import (
"go/ast"
"go/parser"
"go/token"
"path/filepath"
"runtime"
"strconv"
"testing"
)
// This test implements AC-OFFICE-BUDGET-007.3: it derives the inventory of
// every run-reason string literal in the Office source by reading the
// source with go/ast — never by matching constant identifiers, and never
// from a list of literals maintained alongside it — and fails the build
// when one is classified by neither the attended allowlist
// (AC-OFFICE-BUDGET-007.2, shared.ClassifyRunProvenance) nor the explicit
// unattended list (AC-OFFICE-BUDGET-007.4, attendedForTest/unattendedForTest
// below). It reads plain .go files with go/parser, not golang.org/x/tools/go/packages:
// alias declarations (e.g. RunReasonHeartbeat = shared.RunReasonHeartbeat) are
// recognized syntactically (RHS is not a string *ast.BasicLit) and skipped
// rather than resolved, which is sufficient because the aliased constant's
// package is itself one of the seven enumerated blocks this test scans.
//
// attendedForTest and unattendedForTest are declared here, independently of
// shared.attendedRunReasons and of each other. AC-OFFICE-BUDGET-007.4
// requires the unattended list never be computed as attendedForTest's
// complement — a derived list would make every literal a member of one set
// by construction, and the test could never fail.
var attendedForTest = map[string]bool{
"task_assigned": true,
"task_comment": true,
"task_review_requested": true,
"task_changes_requested": true,
"task_blockers_resolved": true,
"task_children_completed": true,
"approval_resolved": true,
"routine_dispatch_event": true,
"manual_resume_after_failure": true,
"task_mentioned": true,
"task_reopened": true,
"task_reopened_via_comment": true,
"task_unblocked": true,
"task_ready_to_close": true,
"stage_pending": true,
"stage_changes_requested": true,
"review_started": true,
"approval_started": true,
"blockers_resolved": true,
"children_completed": true,
}
var unattendedForTest = map[string]bool{
"agent_error": true,
"budget_alert": true,
"heartbeat": true,
"routine_dispatch": true,
"routine_dispatch_cron": true,
"routine_trigger": true,
}
// runReasonBlock names one of AC-OFFICE-BUDGET-007.3's seven enumerated
// declaration blocks, located by relative file path plus an anchor constant
// name already known to live in that block — never by line number.
type runReasonBlock struct {
label string
relPath string
anchorName string
}
var runReasonBlocks = []runReasonBlock{
{"a", "../scheduler/run.go", "RunReasonTaskAssigned"},
{"b (RunReason*)", "../service/run.go", "RunReasonTaskAssigned"},
{"b (legacyRunReason*)", "../service/run.go", "legacyRunReasonBlockersResolved"},
{"c", "./runreasons.go", "RunReasonRoutineDispatch"},
{"d", "../routing/types.go", "WakeReasonHeartbeat"},
{"e", "../../runs/commentkeys/commentkeys.go", "TaskCommentReason"},
{"f", "../onboarding/service.go", "runReasonTaskAssigned"},
{"g", "../service/failure.go", "RunReasonManualResumeAfterFailure"},
}
// excludedIdentifiers is AC-OFFICE-BUDGET-007.3's exact six-entry exclusion
// list: constants that share an enumerated block with a run reason but are
// not themselves one. Exclusion is by name, never by inferring intent from
// the string value.
var excludedIdentifiers = map[string]bool{
"RoutineSourceCron": true, // shared.RoutineSourceCron
"TaskCommentPrefix": true, // commentkeys.TaskCommentPrefix
"EngineDispatchedValue": true, // commentkeys.EngineDispatchedValue
"InboxKindAgentRunFailed": true,
"InboxKindAgentPausedAfterFails": true,
"autoPauseReasonPrefix": true,
}
func thisDir(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("runtime.Caller(0) failed; cannot locate test file for relative source paths")
}
return filepath.Dir(file)
}
// findConstBlock parses path and returns the *ast.GenDecl (Tok == CONST)
// containing a ValueSpec named anchor. Fails the test — never skips or
// returns a smaller inventory — when the file can't be parsed or the
// anchor isn't found, per AC-OFFICE-BUDGET-007.3's "shall fail rather than
// pass on the smaller inventory" when a block was renamed, moved, or deleted.
func findConstBlock(t *testing.T, path, anchor string) *ast.GenDecl {
t.Helper()
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
if err != nil {
t.Fatalf("parse %s: %v", path, err)
}
for _, decl := range f.Decls {
gen, ok := decl.(*ast.GenDecl)
if !ok || gen.Tok != token.CONST {
continue
}
for _, spec := range gen.Specs {
vs, ok := spec.(*ast.ValueSpec)
if !ok {
continue
}
for _, name := range vs.Names {
if name.Name == anchor {
return gen
}
}
}
}
t.Fatalf("anchor constant %q not found in %s — enumerated block moved, renamed, "+
"or deleted; AC-OFFICE-BUDGET-007.3 requires the build fail here rather than "+
"silently shrink the run-reason inventory", anchor, path)
return nil
}
// literalsInBlock returns every string-literal constant value declared
// directly in gen (an alias RHS — a *ast.SelectorExpr or *ast.Ident rather
// than a string *ast.BasicLit — contributes no new literal and is skipped,
// per AC-OFFICE-BUDGET-007.3), excluding any name in excludedIdentifiers.
func literalsInBlock(gen *ast.GenDecl) map[string]bool {
out := map[string]bool{}
for _, spec := range gen.Specs {
vs, ok := spec.(*ast.ValueSpec)
if !ok {
continue
}
for i, name := range vs.Names {
if excludedIdentifiers[name.Name] {
continue
}
if i >= len(vs.Values) {
continue // iota-style repeated spec with no literal of its own
}
lit, ok := vs.Values[i].(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
continue // alias RHS (SelectorExpr/Ident) — no new literal
}
val, err := strconv.Unquote(lit.Value)
if err != nil {
continue
}
out[val] = true
}
}
return out
}
func TestRunReasonInventory_EveryLiteralIsClassified(t *testing.T) {
dir := thisDir(t)
if overlap := intersect(attendedForTest, unattendedForTest); len(overlap) > 0 {
t.Fatalf("attendedForTest and unattendedForTest are not disjoint: %v", overlap)
}
seen := map[string][]string{} // literal -> blocks it was found in
for _, block := range runReasonBlocks {
path := filepath.Join(dir, block.relPath)
gen := findConstBlock(t, path, block.anchorName)
for literal := range literalsInBlock(gen) {
seen[literal] = append(seen[literal], block.label)
}
}
if len(seen) == 0 {
t.Fatal("inventory came back empty — every enumerated block failed to parse " +
"or contribute a literal; this test cannot have passed by accident")
}
for literal, blocks := range seen {
inAttended := attendedForTest[literal]
inUnattended := unattendedForTest[literal]
if !inAttended && !inUnattended {
t.Errorf("run-reason literal %q (declared in block(s) %v) is classified by "+
"neither AC-OFFICE-BUDGET-007.2's attended allowlist nor "+
"AC-OFFICE-BUDGET-007.4's unattended list — classify it in "+
"shared.attendedRunReasons (and mirror the choice in this test's "+
"attendedForTest/unattendedForTest) before merging", literal, blocks)
}
if inAttended && inUnattended {
t.Errorf("run-reason literal %q is in both attendedForTest and "+
"unattendedForTest — the two lists must be disjoint", literal)
}
}
}
func intersect(a, b map[string]bool) []string {
var out []string
for k := range a {
if b[k] {
out = append(out, k)
}
}
return out
}
@@ -0,0 +1,98 @@
package shared_test
import (
"testing"
"github.com/kandev/kandev/internal/office/shared"
)
// TestClassifyRunProvenance_AttendedAllowlist pins AC-OFFICE-BUDGET-007.2's
// exact 20-literal attended allowlist (16 current + 4 legacy).
func TestClassifyRunProvenance_AttendedAllowlist(t *testing.T) {
attended := []string{
"task_assigned",
"task_comment",
"task_review_requested",
"task_changes_requested",
"task_blockers_resolved",
"task_children_completed",
"approval_resolved",
"routine_dispatch_event",
"manual_resume_after_failure",
"task_mentioned",
"task_reopened",
"task_reopened_via_comment",
"task_unblocked",
"task_ready_to_close",
"stage_pending",
"stage_changes_requested",
"review_started",
"approval_started",
"blockers_resolved",
"children_completed",
}
if len(attended) != 20 {
t.Fatalf("test fixture drift: want 20 attended literals, got %d", len(attended))
}
for _, reason := range attended {
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceAttended {
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceAttended", reason, got)
}
}
}
// TestClassifyRunProvenance_UnattendedExplicitList pins AC-OFFICE-BUDGET-007.4's
// exact 6-literal unattended list.
func TestClassifyRunProvenance_UnattendedExplicitList(t *testing.T) {
unattended := []string{
"agent_error",
"budget_alert",
"heartbeat",
"routine_dispatch",
"routine_dispatch_cron",
"routine_trigger",
}
if len(unattended) != 6 {
t.Fatalf("test fixture drift: want 6 unattended literals, got %d", len(unattended))
}
for _, reason := range unattended {
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceUnattended {
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceUnattended", reason, got)
}
}
}
// TestClassifyRunProvenance_UnknownReasonIsUnattended pins AC-OFFICE-BUDGET-007.2's
// safe default: a value the build has never seen classifies unattended, never
// as a third state and never exempt from a gate.
func TestClassifyRunProvenance_UnknownReasonIsUnattended(t *testing.T) {
for _, reason := range []string{"", "some_future_reason_nobody_has_written_yet"} {
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceUnattended {
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceUnattended (safe default)", reason, got)
}
}
}
// TestClassifyRunProvenance_PolarityDiffersFromIsPeriodicTasklessWake pins the
// glossary's polarity warning: routine_dispatch is non-periodic for the
// idle-skip gate but unattended for budget enforcement — the same literal,
// opposite safe answer. A shared implementation would invert one of them.
func TestClassifyRunProvenance_PolarityDiffersFromIsPeriodicTasklessWake(t *testing.T) {
reason := shared.RunReasonRoutineDispatch
if shared.IsPeriodicTasklessWake(reason) {
t.Fatalf("test assumption violated: IsPeriodicTasklessWake(%q) should be false", reason)
}
if got := shared.ClassifyRunProvenance(reason); got != shared.RunProvenanceUnattended {
t.Errorf("ClassifyRunProvenance(%q) = %v, want RunProvenanceUnattended even though "+
"IsPeriodicTasklessWake treats it as non-periodic", reason, got)
}
}
func TestRunProvenance_Attended(t *testing.T) {
if !shared.RunProvenanceAttended.Attended() {
t.Error("RunProvenanceAttended.Attended() = false, want true")
}
if shared.RunProvenanceUnattended.Attended() {
t.Error("RunProvenanceUnattended.Attended() = true, want false")
}
}
@@ -17,7 +17,12 @@ describe("budget label maps", () => {
"notify_only",
"pause_agent",
]);
expect(Object.keys(BUDGET_PERIOD_LABEL_KEYS).sort()).toEqual(["monthly", "total"]);
expect(Object.keys(BUDGET_PERIOD_LABEL_KEYS).sort()).toEqual([
"daily",
"monthly",
"total",
"yearly",
]);
});
it("resolves every mapped key to real copy", () => {
+2
View File
@@ -89,7 +89,9 @@ export const CONCURRENCY_POLICY_LABEL_KEYS: Record<string, string> = {
* identifier.
*/
export const BUDGET_PERIOD_LABEL_KEYS: Record<string, string> = {
daily: "office:budgetPeriodDaily",
monthly: "office:budgetPeriodMonthly",
yearly: "office:budgetPeriodYearly",
total: "office:budgetPeriodTotal",
};
@@ -8,6 +8,7 @@ import { listBudgets, deleteBudget } from "@/lib/api/domains/office-api";
import type { BudgetPolicy } from "@/lib/state/slices/office/types";
import { BudgetPolicyCard } from "./budget-policy-card";
import { CreateBudgetForm } from "./create-budget-form";
import { DefaultCeilingCard } from "./default-ceiling-card";
import { useTranslation } from "react-i18next";
// Module-level `t` for the error-only strings inside the fetching effect below:
// putting the hook's `t` in that dep array would re-issue the request on every
@@ -63,6 +64,8 @@ export function BudgetsTab({ workspaceId }: { workspaceId: string }) {
</Button>
</div>
<DefaultCeilingCard workspaceId={workspaceId} />
{showCreate && (
<CreateBudgetForm
workspaceId={workspaceId}
@@ -84,9 +84,15 @@ function FormFields({
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="daily" className="cursor-pointer">
{t("office:daily")}
</SelectItem>
<SelectItem value="monthly" className="cursor-pointer">
{t("office:monthly")}
</SelectItem>
<SelectItem value="yearly" className="cursor-pointer">
{t("office:yearly")}
</SelectItem>
<SelectItem value="total" className="cursor-pointer">
{t("office:total")}
</SelectItem>
@@ -146,7 +152,7 @@ export function CreateBudgetForm({ workspaceId, onCreated, onCancel }: Props) {
// Budgets are stored as hundredths of a cent (subcents) to
// match cost_subcents semantics — see apps/web/lib/utils.ts:formatDollars.
limitSubcents: Math.round(parseFloat(state.limitDollars || "0") * 10000),
period: state.period as "monthly" | "total",
period: state.period as "daily" | "monthly" | "yearly" | "total",
alertThresholdPct: parseInt(state.alertPct, 10) || 80,
actionOnExceed: state.action as "notify_only" | "pause_agent" | "block_new_tasks",
});
@@ -0,0 +1,149 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
const getDefaultCeilingMock = vi.fn<(workspaceId: string) => Promise<{ limit_subcents: number }>>();
const setDefaultCeilingMock =
vi.fn<(workspaceId: string, limitSubcents: number) => Promise<{ limit_subcents: number }>>();
vi.mock("@/lib/api/domains/office-api", () => ({
getDefaultCeiling: (workspaceId: string) => getDefaultCeilingMock(workspaceId),
setDefaultCeiling: (workspaceId: string, limitSubcents: number) =>
setDefaultCeilingMock(workspaceId, limitSubcents),
}));
const toastError = vi.fn();
const toastSuccess = vi.fn();
vi.mock("@/lib/toast/sonner", () => ({
toast: {
success: (...args: unknown[]) => toastSuccess(...args),
error: (...args: unknown[]) => toastError(...args),
},
}));
const EDIT_BUTTON_NAME = "Edit default ceiling";
const SAVE_BUTTON_NAME = "Save";
import { DefaultCeilingCard } from "./default-ceiling-card";
afterEach(() => {
cleanup();
vi.clearAllMocks();
});
// deferred returns a promise plus its resolver, so a test can control exactly
// when a fetch "arrives" relative to a workspace switch.
function deferred<T>() {
let resolve!: (value: T) => void;
const promise = new Promise<T>((res) => {
resolve = res;
});
return { promise, resolve };
}
describe("DefaultCeilingCard", () => {
it("ignores a stale workspace's response that resolves after switching workspaces", async () => {
const wsA = deferred<{ limit_subcents: number }>();
const wsB = deferred<{ limit_subcents: number }>();
getDefaultCeilingMock.mockImplementationOnce(() => wsA.promise);
getDefaultCeilingMock.mockImplementationOnce(() => wsB.promise);
const { rerender } = render(<DefaultCeilingCard workspaceId="ws-a" />);
await waitFor(() => expect(getDefaultCeilingMock).toHaveBeenCalledWith("ws-a"));
rerender(<DefaultCeilingCard workspaceId="ws-b" />);
await waitFor(() => expect(getDefaultCeilingMock).toHaveBeenCalledWith("ws-b"));
// ws-b's response arrives first, then ws-a's stale response arrives late.
await act(async () => {
wsB.resolve({ limit_subcents: 200000 });
await wsB.promise;
});
await screen.findByText("$20.00");
await act(async () => {
wsA.resolve({ limit_subcents: 500000 });
await wsA.promise;
});
expect(screen.getByText("$20.00")).toBeTruthy();
expect(screen.queryByText("$50.00")).toBeNull();
});
it("resets in-progress edits when the workspace changes", async () => {
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
const { rerender } = render(<DefaultCeilingCard workspaceId="ws-a" />);
await screen.findByText("$10.00");
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
expect(screen.getByRole("spinbutton")).toBeTruthy();
rerender(<DefaultCeilingCard workspaceId="ws-b" />);
expect(screen.queryByRole("spinbutton")).toBeNull();
});
it("does not keep the replacement workspace busy after a stale save settles", async () => {
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
const pendingSave = deferred<{ limit_subcents: number }>();
setDefaultCeilingMock.mockImplementationOnce(() => pendingSave.promise);
const { rerender } = render(<DefaultCeilingCard workspaceId="ws-a" />);
await screen.findByText("$10.00");
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
fireEvent.change(screen.getByRole("spinbutton"), { target: { value: "20" } });
fireEvent.click(screen.getByRole("button", { name: SAVE_BUTTON_NAME }));
expect(
(screen.getByRole("button", { name: SAVE_BUTTON_NAME }) as HTMLButtonElement).disabled,
).toBe(true);
rerender(<DefaultCeilingCard workspaceId="ws-b" />);
await screen.findByText("$10.00");
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
expect(
(screen.getByRole("button", { name: SAVE_BUTTON_NAME }) as HTMLButtonElement).disabled,
).toBe(false);
expect((screen.getByRole("button", { name: "Cancel" }) as HTMLButtonElement).disabled).toBe(
false,
);
await act(async () => {
pendingSave.resolve({ limit_subcents: 200000 });
await pendingSave.promise;
});
});
it("rejects a non-positive draft ceiling without calling the API", async () => {
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
render(<DefaultCeilingCard workspaceId="ws-a" />);
await screen.findByText("$10.00");
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
const input = screen.getByRole("spinbutton");
fireEvent.change(input, { target: { value: "0" } });
await act(async () => {
fireEvent.click(screen.getByRole("button", { name: SAVE_BUTTON_NAME }));
});
expect(setDefaultCeilingMock).not.toHaveBeenCalled();
expect(toastError).toHaveBeenCalledWith("Default ceiling must be greater than zero");
});
it("rejects a non-finite or sub-cent draft ceiling without calling the API", async () => {
getDefaultCeilingMock.mockResolvedValue({ limit_subcents: 100000 });
render(<DefaultCeilingCard workspaceId="ws-a" />);
await screen.findByText("$10.00");
fireEvent.click(screen.getByRole("button", { name: EDIT_BUTTON_NAME }));
const input = screen.getByRole("spinbutton", { name: "Default Ceiling" });
fireEvent.change(input, { target: { value: "0.001" } });
await act(async () => {
fireEvent.click(screen.getByRole("button", { name: SAVE_BUTTON_NAME }));
});
expect(setDefaultCeilingMock).not.toHaveBeenCalled();
expect(toastError).toHaveBeenCalledWith("Default ceiling must be greater than zero");
});
});
@@ -0,0 +1,160 @@
"use client";
import { useEffect, useRef, useState } from "react";
import { Button } from "@kandev/ui/button";
import { Input } from "@kandev/ui/input";
import { Card, CardContent, CardHeader, CardTitle } from "@kandev/ui/card";
import { IconPencil } from "@tabler/icons-react";
import { toast } from "@/lib/toast/sonner";
import { getDefaultCeiling, setDefaultCeiling } from "@/lib/api/domains/office-api";
import { formatDollars } from "@/lib/utils";
import { useTranslation } from "react-i18next";
type Props = {
workspaceId: string;
};
type EditorProps = {
draftDollars: string;
saving: boolean;
onDraftChange: (value: string) => void;
onSave: () => void;
onCancel: () => void;
};
function DefaultCeilingEditor({
draftDollars,
saving,
onDraftChange,
onSave,
onCancel,
}: EditorProps) {
const { t } = useTranslation();
return (
<div className="flex flex-col gap-2 sm:flex-row sm:items-center">
<Input
className="h-8 w-full text-sm [@media(pointer:coarse)]:min-h-11 sm:w-32"
type="number"
min="0.01"
step="0.01"
value={draftDollars}
onChange={(e) => onDraftChange(e.target.value)}
aria-label={t("office:defaultCeiling")}
autoFocus
/>
<Button
size="sm"
className="w-full cursor-pointer [@media(pointer:coarse)]:min-h-11 sm:w-auto"
disabled={saving}
onClick={onSave}
>
{t("office:saveDefaultCeiling")}
</Button>
<Button
variant="ghost"
size="sm"
className="w-full cursor-pointer [@media(pointer:coarse)]:min-h-11 sm:w-auto"
disabled={saving}
onClick={onCancel}
>
{t("common:cancel")}
</Button>
</div>
);
}
// DefaultCeilingCard makes the built-in default spend ceiling
// (AC-OFFICE-BUDGET-003.5) visible and editable without inspecting the
// database. It is visually and structurally distinct from a
// BudgetPolicyCard: no scope/action/period controls, since the default is
// always workspace-scoped, always daily, and always blocking
// (AC-OFFICE-BUDGET-003.2/.3) — only its limit is operator-tunable.
export function DefaultCeilingCard({ workspaceId }: Props) {
const { t } = useTranslation();
const [limitSubcents, setLimitSubcents] = useState<number | null>(null);
const [editing, setEditing] = useState(false);
const [draftDollars, setDraftDollars] = useState("");
const [saving, setSaving] = useState(false);
const activeWorkspaceId = useRef(workspaceId);
useEffect(() => {
activeWorkspaceId.current = workspaceId;
setLimitSubcents(null);
setEditing(false);
setDraftDollars("");
setSaving(false);
getDefaultCeiling(workspaceId)
.then((res) => {
if (activeWorkspaceId.current !== workspaceId) return;
setLimitSubcents(res.limit_subcents);
})
.catch((err) => {
if (activeWorkspaceId.current !== workspaceId) return;
toast.error(err instanceof Error ? err.message : t("office:failedToLoadDefaultCeiling"));
});
// eslint-disable-next-line react-hooks/exhaustive-deps -- toast/t are stable; re-fetch only on workspace change
}, [workspaceId]);
const startEditing = () => {
setDraftDollars(limitSubcents == null ? "" : (limitSubcents / 10000).toFixed(2));
setEditing(true);
};
const handleSave = async () => {
const draftValue = Number(draftDollars);
if (!Number.isFinite(draftValue) || draftValue < 0.01) {
toast.error(t("office:defaultCeilingMustBePositive"));
return;
}
const nextSubcents = Math.round(draftValue * 10000);
const targetWorkspaceId = workspaceId;
setSaving(true);
try {
const res = await setDefaultCeiling(targetWorkspaceId, nextSubcents);
if (activeWorkspaceId.current !== targetWorkspaceId) return;
setLimitSubcents(res.limit_subcents);
setEditing(false);
toast.success(t("office:defaultCeilingUpdated"));
} catch (err) {
if (activeWorkspaceId.current !== targetWorkspaceId) return;
toast.error(err instanceof Error ? err.message : t("office:failedToUpdateDefaultCeiling"));
} finally {
if (activeWorkspaceId.current === targetWorkspaceId) setSaving(false);
}
};
return (
<Card>
<CardHeader className="flex flex-row items-center justify-between pb-2">
<CardTitle className="text-sm">{t("office:defaultCeiling")}</CardTitle>
{!editing && (
<Button
variant="ghost"
size="icon-sm"
className="cursor-pointer [@media(pointer:coarse)]:h-11 [@media(pointer:coarse)]:w-11"
onClick={startEditing}
aria-label={t("office:editDefaultCeiling")}
>
<IconPencil className="h-4 w-4" />
</Button>
)}
</CardHeader>
<CardContent className="space-y-2">
<p className="text-xs text-muted-foreground">{t("office:defaultCeilingDescription")}</p>
{editing ? (
<DefaultCeilingEditor
draftDollars={draftDollars}
saving={saving}
onDraftChange={setDraftDollars}
onSave={handleSave}
onCancel={() => setEditing(false)}
/>
) : (
<div className="text-lg font-semibold">
{limitSubcents == null ? t("common:loading") : formatDollars(limitSubcents)}
</div>
)}
</CardContent>
</Card>
);
}
@@ -0,0 +1,113 @@
import { test, expect } from "../../fixtures/office-fixture";
import { officeTopbarTitle } from "../../helpers/office-topbar";
import { waitForHttp } from "../../helpers/causal-waits";
// Covers the frontend surface added by REQ-OFFICE-BUDGET-002.9/.12 (daily/
// yearly period options) and REQ-OFFICE-BUDGET-003.5 (built-in default
// ceiling, readable/writable without inspecting the database).
test.describe("Office budget enforcement UI", () => {
test.beforeEach(async ({ testPage }) => {
await testPage.goto("/office/workspace/costs");
await expect(officeTopbarTitle(testPage)).toHaveText(/Costs/i, { timeout: 10_000 });
await testPage.getByRole("tab", { name: "Budgets" }).click();
});
test("default ceiling card shows the built-in default and can be edited", async ({
testPage,
}) => {
const initialLoad = waitForHttp(testPage, "GET", /\/budgets\/default$/);
await testPage.reload();
await testPage.getByRole("tab", { name: "Budgets" }).click();
await initialLoad;
// Shipped default is 500,000 subcents == $50.00 (AC-OFFICE-BUDGET-003.9)
// until a workspace overrides it.
const card = testPage.getByText("Default Ceiling").locator("..").locator("..");
await expect(card.getByText("$50.00")).toBeVisible();
await card.getByRole("button", { name: "Edit default ceiling" }).click();
const input = card.getByRole("spinbutton");
await input.fill("75.50");
const saved = waitForHttp(testPage, "PUT", /\/budgets\/default$/, {
predicate: (r) => r.status() === 200,
});
await card.getByRole("button", { name: "Save" }).click();
await saved;
await expect(card.getByText("$75.50")).toBeVisible();
// Reload to prove the write actually persisted server-side, not just in
// local component state.
const reloadFetch = waitForHttp(testPage, "GET", /\/budgets\/default$/);
await testPage.reload();
await testPage.getByRole("tab", { name: "Budgets" }).click();
await reloadFetch;
await expect(
testPage.getByText("Default Ceiling").locator("..").locator("..").getByText("$75.50"),
).toBeVisible();
});
test("create-budget period select offers exactly daily, monthly, yearly, total", async ({
testPage,
}) => {
await testPage.getByRole("button", { name: "Add Policy" }).click();
// Period is the 4th FormField (Scope Type, Scope ID, Limit, Period, ...);
// scope it via the visible "Period" label rather than a bare role query,
// since the form has several comboboxes.
const periodField = testPage
.locator("div", { has: testPage.getByText("Period", { exact: true }) })
.last();
await periodField.getByRole("combobox").click();
const listbox = testPage.getByRole("listbox");
await expect(listbox.getByRole("option", { name: "Daily" })).toBeVisible();
await expect(listbox.getByRole("option", { name: "Monthly" })).toBeVisible();
await expect(listbox.getByRole("option", { name: "Yearly" })).toBeVisible();
await expect(listbox.getByRole("option", { name: "Total" })).toBeVisible();
// Exactly these four - no fifth/unexpected option leaking through.
await expect(listbox.getByRole("option")).toHaveCount(4);
});
test("selecting a daily period in create-budget wires through to the POST body", async ({
testPage,
officeSeed,
}) => {
await testPage.getByRole("button", { name: "Add Policy" }).click();
const scopeIdField = testPage
.locator("div", { has: testPage.getByText("Scope ID", { exact: true }) })
.last();
await scopeIdField.getByPlaceholder("Entity ID").fill(officeSeed.workspaceId);
const limitField = testPage
.locator("div", { has: testPage.getByText("Limit ($)", { exact: true }) })
.last();
await limitField.getByRole("spinbutton").fill("12.34");
const periodField = testPage
.locator("div", { has: testPage.getByText("Period", { exact: true }) })
.last();
await periodField.getByRole("combobox").click();
await testPage.getByRole("option", { name: "Daily" }).click();
const posted = waitForHttp(testPage, "POST", /\/budgets$/);
await testPage.getByRole("button", { name: "Create Policy" }).click();
const response = await posted;
expect(response.status()).toBe(201);
const requestBody = JSON.parse(response.request().postData() ?? "{}") as Record<
string,
unknown
>;
expect(requestBody).toMatchObject({
scope_type: "workspace",
scope_id: officeSeed.workspaceId,
limit_subcents: 123400,
period: "daily",
alert_threshold_pct: 80,
action_on_exceed: "notify_only",
});
});
});
@@ -0,0 +1,45 @@
import { test, expect } from "../../fixtures/office-fixture";
import { officeTopbarTitle } from "../../helpers/office-topbar";
import { waitForHttp } from "../../helpers/causal-waits";
test.describe("Office budget enforcement on mobile", () => {
test("edits the default ceiling with reachable controls", async ({ testPage }) => {
await testPage.goto("/office/workspace/costs");
await expect(officeTopbarTitle(testPage)).toHaveText(/Costs/i, { timeout: 10_000 });
const defaultLoad = waitForHttp(testPage, "GET", /\/budgets\/default$/);
await testPage.getByRole("tab", { name: "Budgets" }).tap();
await defaultLoad;
const card = testPage.getByText("Default Ceiling").locator("..").locator("..");
await expect(card.getByText(/\$\d+\.\d{2}/)).toBeVisible();
const edit = card.getByRole("button", { name: "Edit default ceiling" });
const editBox = await edit.boundingBox();
expect(editBox?.width).toBeGreaterThanOrEqual(44);
expect(editBox?.height).toBeGreaterThanOrEqual(44);
await edit.tap();
const input = card.getByRole("spinbutton");
await expect(input).toHaveAccessibleName("Default Ceiling");
await input.fill("75.50");
const save = card.getByRole("button", { name: "Save" });
const cancel = card.getByRole("button", { name: "Cancel" });
for (const button of [save, cancel]) {
const box = await button.boundingBox();
expect(box?.width).toBeGreaterThanOrEqual(44);
expect(box?.height).toBeGreaterThanOrEqual(44);
}
const saved = waitForHttp(testPage, "PUT", /\/budgets\/default$/, {
predicate: (response) => response.status() === 200,
});
await save.tap();
await saved;
await expect(card.getByText("$75.50")).toBeVisible();
expect(await testPage.evaluate(() => document.documentElement.scrollWidth)).toBeLessThanOrEqual(
await testPage.evaluate(() => document.documentElement.clientWidth),
);
});
});
+20 -25
View File
@@ -4,7 +4,6 @@ import type {
AgentProfile,
Project,
CostSummary,
BudgetPolicy,
Routine,
RoutineTrigger,
RoutineRun,
@@ -64,6 +63,7 @@ export {
gitPull,
gitPush,
} from "./office-extended-api";
export { listBudgets, createBudget, updateBudget, deleteBudget } from "./office-budget-api";
export type {
ImportDiff,
ImportPreview,
@@ -423,37 +423,32 @@ type CostBreakdownItemRaw = {
total_subcents: number;
};
// --- Budget Policies ---
// --- Built-in default spend ceiling (AC-OFFICE-BUDGET-003.5) ---
export function listBudgets(workspaceId: string, options?: ApiRequestOptions) {
return fetchJson<{ budgets: BudgetPolicy[] }>(
`${BASE}/workspaces/${workspaceId}/budgets`,
options,
);
// DefaultCeilingRaw is the wire shape of GET/PUT .../budgets/default
// (internal/office/costs/dto.go's DefaultCeilingResponse /
// SetDefaultCeilingRequest, both `{"limit_subcents": ...}`). Named "Raw"
// and read as snake_case directly by the caller, matching this file's
// existing CostBreakdownItemRaw convention, rather than assuming a
// camelCase field the backend does not send.
type DefaultCeilingRaw = { limit_subcents: number };
export function getDefaultCeiling(workspaceId: string, options?: ApiRequestOptions) {
return fetchJson<DefaultCeilingRaw>(`${BASE}/workspaces/${workspaceId}/budgets/default`, options);
}
export function createBudget(
export function setDefaultCeiling(
workspaceId: string,
data: Partial<BudgetPolicy>,
limitSubcents: number,
options?: ApiRequestOptions,
) {
return fetchJson<BudgetPolicy>(`${BASE}/workspaces/${workspaceId}/budgets`, {
return fetchJson<DefaultCeilingRaw>(`${BASE}/workspaces/${workspaceId}/budgets/default`, {
...options,
init: { method: "POST", body: JSON.stringify(data), ...options?.init },
});
}
export function updateBudget(id: string, data: Partial<BudgetPolicy>, options?: ApiRequestOptions) {
return fetchJson<BudgetPolicy>(`${BASE}/budgets/${id}`, {
...options,
init: { method: "PATCH", body: JSON.stringify(data), ...options?.init },
});
}
export function deleteBudget(id: string, options?: ApiRequestOptions) {
return fetchJson<void>(`${BASE}/budgets/${id}`, {
...options,
init: { method: "DELETE", ...options?.init },
init: {
method: "PUT",
body: JSON.stringify({ limit_subcents: limitSubcents }),
...options?.init,
},
});
}
@@ -0,0 +1,104 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("@/lib/config", () => ({
getBackendConfig: () => ({ apiBaseUrl: "http://api.test" }),
}));
import { createBudget, listBudgets, updateBudget } from "./office-api";
type FetchInput = Parameters<typeof fetch>[0];
type FetchInit = Parameters<typeof fetch>[1];
const fetchSpy = vi.fn<(...args: [FetchInput, FetchInit?]) => Promise<Response>>();
const WORKSPACE_ID = "workspace-1";
beforeEach(() => {
fetchSpy.mockReset();
vi.stubGlobal("fetch", fetchSpy);
});
afterEach(() => vi.unstubAllGlobals());
function jsonResponse(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
status,
headers: { "Content-Type": "application/json" },
});
}
function lastCall(): { url: string; init: FetchInit | undefined } {
const call = fetchSpy.mock.calls.at(-1);
if (!call) throw new Error("expected fetch to have been called");
return { url: String(call[0]), init: call[1] };
}
const camelBudget = {
scopeType: "workspace" as const,
scopeId: WORKSPACE_ID,
limitSubcents: 123400,
period: "daily" as const,
alertThresholdPct: 80,
actionOnExceed: "block_new_tasks" as const,
};
const snakeBudget = {
id: "budget-1",
workspace_id: WORKSPACE_ID,
scope_type: "workspace",
scope_id: WORKSPACE_ID,
limit_subcents: 123400,
period: "daily",
alert_threshold_pct: 80,
action_on_exceed: "block_new_tasks",
created_at: "2026-01-01T00:00:00Z",
updated_at: "2026-01-01T00:00:00Z",
};
describe("budget policy api", () => {
it("maps camelCase fields to the backend snake_case create body", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ budget: snakeBudget }, 201));
const result = await createBudget(WORKSPACE_ID, camelBudget);
expect(lastCall().init?.method).toBe("POST");
expect(JSON.parse(String(lastCall().init?.body))).toEqual({
scope_type: "workspace",
scope_id: WORKSPACE_ID,
limit_subcents: 123400,
period: "daily",
alert_threshold_pct: 80,
action_on_exceed: "block_new_tasks",
});
expect(result.scopeType).toBe("workspace");
expect(result.limitSubcents).toBe(123400);
});
it("maps a partial camelCase patch to snake_case", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ budget: snakeBudget }));
await updateBudget("budget-1", { limitSubcents: 200000, actionOnExceed: "notify_only" });
expect(lastCall().init?.method).toBe("PATCH");
expect(JSON.parse(String(lastCall().init?.body))).toEqual({
limit_subcents: 200000,
action_on_exceed: "notify_only",
});
});
it("normalizes snake_case list responses for the web model", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ budgets: [snakeBudget] }));
const result = await listBudgets(WORKSPACE_ID);
expect(result.budgets).toEqual([
expect.objectContaining({
id: "budget-1",
workspaceId: WORKSPACE_ID,
scopeType: "workspace",
scopeId: WORKSPACE_ID,
limitSubcents: 123400,
alertThresholdPct: 80,
actionOnExceed: "block_new_tasks",
}),
]);
});
});
@@ -0,0 +1,75 @@
import { fetchJson, type ApiRequestOptions } from "../client";
import type { BudgetPolicy } from "@/lib/state/slices/office/types";
const BASE = "/api/v1/office";
type RawBudgetPolicy = Record<string, unknown>;
function budgetField(raw: RawBudgetPolicy, camelKey: string, snakeKey: string): unknown {
return raw[camelKey] ?? raw[snakeKey];
}
function normalizeBudget(raw: unknown): BudgetPolicy {
const budget = raw as RawBudgetPolicy;
return {
id: String(budgetField(budget, "id", "id") ?? ""),
workspaceId: String(budgetField(budget, "workspaceId", "workspace_id") ?? ""),
scopeType: budgetField(budget, "scopeType", "scope_type") as BudgetPolicy["scopeType"],
scopeId: String(budgetField(budget, "scopeId", "scope_id") ?? ""),
limitSubcents: Number(budgetField(budget, "limitSubcents", "limit_subcents") ?? 0),
period: budgetField(budget, "period", "period") as BudgetPolicy["period"],
alertThresholdPct: Number(budgetField(budget, "alertThresholdPct", "alert_threshold_pct") ?? 0),
actionOnExceed: budgetField(
budget,
"actionOnExceed",
"action_on_exceed",
) as BudgetPolicy["actionOnExceed"],
createdAt: String(budgetField(budget, "createdAt", "created_at") ?? ""),
updatedAt: String(budgetField(budget, "updatedAt", "updated_at") ?? ""),
};
}
function budgetPayload(data: Partial<BudgetPolicy>): Record<string, unknown> {
return {
scope_type: data.scopeType,
scope_id: data.scopeId,
limit_subcents: data.limitSubcents,
period: data.period,
alert_threshold_pct: data.alertThresholdPct,
action_on_exceed: data.actionOnExceed,
};
}
type BudgetResponse = { budget: unknown };
export function listBudgets(workspaceId: string, options?: ApiRequestOptions) {
return fetchJson<{ budgets: unknown[] }>(
`${BASE}/workspaces/${workspaceId}/budgets`,
options,
).then((res) => ({ budgets: (res.budgets ?? []).map((budget) => normalizeBudget(budget)) }));
}
export function createBudget(
workspaceId: string,
data: Partial<BudgetPolicy>,
options?: ApiRequestOptions,
) {
return fetchJson<BudgetResponse>(`${BASE}/workspaces/${workspaceId}/budgets`, {
...options,
init: { method: "POST", body: JSON.stringify(budgetPayload(data)), ...options?.init },
}).then((res) => normalizeBudget(res.budget));
}
export function updateBudget(id: string, data: Partial<BudgetPolicy>, options?: ApiRequestOptions) {
return fetchJson<BudgetResponse>(`${BASE}/budgets/${id}`, {
...options,
init: { method: "PATCH", body: JSON.stringify(budgetPayload(data)), ...options?.init },
}).then((res) => normalizeBudget(res.budget));
}
export function deleteBudget(id: string, options?: ApiRequestOptions) {
return fetchJson<void>(`${BASE}/budgets/${id}`, {
...options,
init: { method: "DELETE", ...options?.init },
});
}
@@ -0,0 +1,55 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("@/lib/config", () => ({
getBackendConfig: () => ({ apiBaseUrl: "http://api.test" }),
}));
import { getDefaultCeiling, setDefaultCeiling } from "./office-api";
type FetchInput = Parameters<typeof fetch>[0];
type FetchInit = Parameters<typeof fetch>[1];
const fetchSpy = vi.fn<(...args: [FetchInput, FetchInit?]) => Promise<Response>>();
const WORKSPACE_ID = "workspace-1";
const URL = `http://api.test/api/v1/office/workspaces/${WORKSPACE_ID}/budgets/default`;
beforeEach(() => {
fetchSpy.mockReset();
vi.stubGlobal("fetch", fetchSpy);
});
afterEach(() => vi.unstubAllGlobals());
function jsonResponse(body: unknown): Response {
return new Response(JSON.stringify(body), {
status: 200,
headers: { "Content-Type": "application/json" },
});
}
function lastCall(): { url: string; init: FetchInit | undefined } {
const call = fetchSpy.mock.calls.at(-1);
if (!call) throw new Error("expected fetch to have been called");
return { url: String(call[0]), init: call[1] };
}
describe("built-in default ceiling api", () => {
it("reads the effective limit from the snake_case wire response", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ limit_subcents: 500_000 }));
const res = await getDefaultCeiling(WORKSPACE_ID);
expect(lastCall().url).toBe(URL);
expect(res.limit_subcents).toBe(500_000);
});
it("PUTs a snake_case body and returns the updated limit", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ limit_subcents: 1_000_000 }));
const res = await setDefaultCeiling(WORKSPACE_ID, 1_000_000);
expect(lastCall().url).toBe(URL);
expect(lastCall().init?.method).toBe("PUT");
expect(JSON.parse(String(lastCall().init?.body))).toEqual({ limit_subcents: 1_000_000 });
expect(res.limit_subcents).toBe(1_000_000);
});
});
+1 -1
View File
@@ -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;
+12
View File
@@ -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",
+12
View File
@@ -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": "Źōōḿ ōũţ",
+12
View File
@@ -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",
+12
View File
@@ -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": "缩小",
+12
View File
@@ -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": "縮小",
+3 -3
View File
@@ -425,8 +425,8 @@
"portableConfigNotFound": "未找到",
"portableConfigNotFoundHint": "這只是編輯提示。你可以先儲存設定,稍後再新增該檔案。",
"portableConfigTitle": "代理程式設定檔",
"allowUserNamespacesTitle": "使用者名稱空間支援",
"allowUserNamespacesDescription": "允許在容器內建立無特權的使用者名稱空間和執行掛載操作。啟用類似 bwrap 的沙箱工具。",
"allowUserNamespacesTitle": "使用者命名空間支援",
"allowUserNamespacesDescription": "允許在容器內建立無特權的使用者命名空間和執行掛載操作。啟用類似 bwrap 的沙箱工具。",
"allowUserNamespacesNote": "此設定僅影響新建立的容器。現有任務環境必須重置才能使更改生效。",
"allowUserNamespacesWarning": "這會為選擇啟用的容器停用 Docker 預設的 AppArmor 限制。僅為需要使用者名稱空間沙箱的可信代理執行環境啟用。"
"allowUserNamespacesWarning": "這會為選擇啟用的容器停用 Docker 預設的 AppArmor 限制。僅為需要使用者命名空間沙箱的可信代理執行環境啟用。"
}
+12
View File
@@ -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": "縮小",
+58
View File
@@ -0,0 +1,58 @@
---
status: draft
system: office
specification_version: 1
owners:
- kandev
---
# Office glossary
Shared vocabulary for Office specifications. Terms are grouped by the capability
that defines them; a capability's requirement documents reference this file
rather than restating a definition, so one term cannot drift between documents.
## Budget enforcement
Defined by [Office: Pre-Launch Budget Enforcement](requirements/budget-enforcement.md)
and used by [Budget Admission
Integrity](requirements/budget-admission-integrity.md), [Built-In Default Spend
Ceiling](requirements/budget-default-ceiling.md), [Budget Measurement
Integrity](requirements/budget-measurement-integrity.md) and [Budget Enforcement
Observability](requirements/budget-observability.md).
- **Run provenance:** the classification of a run as *attended* or
*unattended*, derived from `runs.reason`.
- **Attended run:** a run whose reason is in the attended allowlist
(`AC-OFFICE-BUDGET-007.2`). A person plausibly caused it and is plausibly
waiting on it.
- **Unattended run:** any run that is not attended, **including any reason the
allowlist does not recognize**.
- **Subcent:** one hundredth of a United States cent, i.e. `1 USD = 10_000`
subcents. Already the storage unit of `office_cost_events.cost_subcents` and
`office_budget_policies.limit_subcents`.
- **Priced spend:** the sum of `cost_subcents` over the cost events a policy's
scope selects (`AC-OFFICE-BUDGET-002.15`) and whose `occurred_at` falls in the
evaluation window, which by construction counts an unpriced event as zero.
- **Unpriced event:** a cost event with `cost_source = 'unpriced'`. A NULL
`cost_source` is **not** an unpriced event — it is a legacy row written
before the cost contract added the column, and it carries a real cost.
- **Pricing-degraded window:** an evaluation window containing at least one
unpriced event.
- **Evaluator fault:** the pre-execution budget evaluator returning a non-nil
error. A missing evaluator is a distinct state, not a fault.
- **Evaluation window:** the half-open interval `[cutoff, now)` a policy's
period selects, with `cutoff` computed in UTC.
- **Admission gate:** one of the five ordered checks in
`AC-OFFICE-BUDGET-001.14` that can stop a run before launch.
- **Applicable policy:** a policy selected for a run by
`AC-OFFICE-BUDGET-001.15`.
> **Polarity warning for implementers.** `IsPeriodicTasklessWake` classifies
> the ambiguous legacy reason `routine_dispatch` as **non**-periodic, because
> for the idle-skip gate the safe answer is "do not skip". For budget
> enforcement the safe answer is the opposite: the same literal is
> **unattended**, because the safe answer here is "do not spend". Reusing
> `IsPeriodicTasklessWake` for provenance would invert this and fail open on
> exactly the legacy cron rows it is meant to catch.
@@ -0,0 +1,218 @@
---
status: draft
system: office
created: 2026-09-06
owners:
- kandev
---
# Office: Budget Admission Integrity Requirements
## Overview
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies which
admission gate stops a run and what disposition the run gets. That contract
rests on two properties its own criteria never state: that every applicable
policy was actually evaluated, and that evaluating them changed nothing.
Neither holds in the code this capability replaces.
The pre-launch evaluator iterates the applicable policies and, when one
policy's spend query fails, logs the failure and continues, returning a partial
result set and no error. Its caller therefore cannot distinguish "no policy
blocked this run" from "the policy that would have blocked it was never
evaluated". Separately, the per-policy evaluation is not a query: on the same
pre-launch call path it writes `budget.alert` and `budget.exceeded` activity
entries and can flip an agent to `paused` — side effects
[costs.md](costs.md) owns and which
[budget-enforcement.md](budget-enforcement.md)'s Out of scope disclaims.
This document owns those two properties, completeness and inertness, together
with the two identifier-resolution failures that reach the same fail-open
outcome by a different route. It does not decide which gate blocks a run; that
stays in the companion document.
## Terminology
This document uses this capability's shared vocabulary, defined in the [Office
glossary](../glossary.md) under **Budget enforcement** — in particular
*attended run*, *unattended run*, *evaluator fault*, *applicable policy*,
*admission gate*, *evaluation window*, and *priced spend*.
- **Admission evaluation:** the whole of the work the five admission gates of
`AC-OFFICE-BUDGET-001.14` perform for one run, from provenance classification
through to the launch or non-launch decision.
- **Unevaluated policy:** an applicable policy for which the system could not
produce both a priced-spend figure and a pricing-degradation determination.
A policy the system deliberately declines to evaluate under
`AC-OFFICE-BUDGET-002.5`, `-002.11` or `-002.14` is **not** an unevaluated
policy: those criteria decide its disposition, whereas this term names a
policy whose disposition could not be decided. The term names an *attempted*
evaluation that failed, never one the system chose not to begin: because
`AC-OFFICE-BUDGET-006.1` requires every applicable policy be attempted, "not
yet reached" is not a state an applicable policy can be left in, and a policy
the ordering of `AC-OFFICE-BUDGET-001.9` did not select is therefore not an
unevaluated policy.
## Requirements
### REQ-OFFICE-BUDGET-006: The admission decision is complete and inert
**Intent:** A ceiling that is evaluated against some of the applicable policies
is not a ceiling, and an admission test that mutates state is not a test. Both
failures are silent, and both survive every criterion in the companion
documents, because those criteria specify what each gate decides and never
specify that the inputs to that decision were all present or that reaching it
cost nothing.
The completeness half matters most on the path this capability exists to fix.
`REQ-OFFICE-BUDGET-001`'s intent is that no Office run launches without a
ceiling having been evaluated; a partial result set admits the run while
reporting no error at all, so the promise fails without any observable symptom.
The inertness half matters because `AC-OFFICE-BUDGET-001.9` stops at the first
blocking policy. Any side effect produced per policy therefore starts depending
on how far down the ordered list the admission decision happened to walk, which
would make an operator-visible alert and an agent's paused state a function of
policy creation order rather than of spend.
**User story:** As an operator running Office unattended, I want the ceiling to
be computed from every policy that applies and to change nothing on its way to a
decision, so that a launch means the ceiling held rather than that part of it
went missing.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-006.1:** When any applicable policy selected under
`AC-OFFICE-BUDGET-001.15` is an unevaluated policy, the system shall treat
that as an evaluator fault and dispose of the run under
`AC-OFFICE-BUDGET-001.3`, and shall not decide admission from the policies it
did evaluate. Admitting a run on a partial set reproduces the fail-open this
capability exists to remove, because the unevaluated policy may be the one
that blocks; and because the failure is per policy rather than per call, it
produces no error for `AC-OFFICE-BUDGET-001.3` to fire on unless this
criterion makes one. Completeness therefore fixes the evaluation model: the
system shall attempt every applicable policy before any of them decides
admission, and shall apply `AC-OFFICE-BUDGET-001.9`'s first-in-order selection
only to a fully evaluated set. Without that two-phase reading the two criteria
contradict each other — stopping at the first blocking policy would leave a
later erroring policy undetected, which is exactly the partial set this
requirement exists to reject, while treating an unvisited policy as
unevaluated would make every multi-policy run a fault. This lifts to the
policy loop the pattern `AC-OFFICE-BUDGET-001.14` already fixes within a
single policy, where the degradation determination is made even for a policy
whose limit test has already decided to block.
- **AC-OFFICE-BUDGET-006.2:** The admission evaluation shall not write a
`budget.alert` or a `budget.exceeded` activity entry, and shall not change any
agent's status. Those side effects belong to the post-event evaluation path
governed by [costs.md](costs.md), which continues to produce them on its own
schedule, unchanged and unconstrained by this capability. This criterion holds
whatever the admission outcome: in particular, an applicable policy whose
action is `pause_agent` and whose limit is reached shall block the run under
`AC-OFFICE-BUDGET-001.7` **without** pausing the agent as part of that
decision. The agent's pause remains the post-event path's to perform when the
next cost event lands. Stated so the change is a decision rather than a
side effect of `AC-OFFICE-BUDGET-001.9`'s stop at the first blocking policy,
which would otherwise make the set of alerts fired and agents paused depend on
how many policies the admission walk happened to visit.
- **AC-OFFICE-BUDGET-006.3:** When the run's project identifier cannot be
determined because its lookup failed, the system shall treat that as an
evaluator fault and dispose of the run under `AC-OFFICE-BUDGET-001.3`, rather
than evaluating the run as one that carries no project identifier. A failed
lookup and a run that genuinely has no project are different states:
`AC-OFFICE-BUDGET-001.15` makes every `project`-scoped policy inapplicable to
the second, so applying that rule to the first lets a transient failure
silently remove a whole class of ceiling with no operator-visible symptom. A
run carrying no task, or a task that resolves successfully to no project, is
the second state and is not a fault. `AC-OFFICE-BUDGET-006.7` classifies every
outcome of the resolution, including the two this criterion's error/no-project
split does not by itself decide.
- **AC-OFFICE-BUDGET-006.4:** When a run deferred by any cause this capability
introduces other than the evaluator error itself — the workspace-lookup error
branch of `AC-OFFICE-BUDGET-001.13`, an unevaluated policy
(`AC-OFFICE-BUDGET-006.1`), or a failed project lookup
(`AC-OFFICE-BUDGET-006.3`) — has already reached `MaxRetryCount`, the system
shall fail the run and record an operator-visible activity entry naming that
cause. The entry shall not name an evaluator error.
`AC-OFFICE-BUDGET-001.4` is written for a run scheduled for retry by
`AC-OFFICE-BUDGET-001.3` and requires its entry name the evaluator error,
which is false for all three; because those three defer *under*
`AC-OFFICE-BUDGET-001.3`'s terms, without this criterion each reaches
`MaxRetryCount` with a disposition that is either unstated or mislabelled.
They reach it on the ordinary path rather than an exotic one: the retry
backoff schedule exhausts `MaxRetryCount` well before the staleness bound
`AC-OFFICE-BUDGET-001.18` applies, so a sustained outage arrives here and
never there.
- **AC-OFFICE-BUDGET-006.7:** The run's project identifier shall be resolved at
the start of gate 4 of `AC-OFFICE-BUDGET-001.14`, after gate 3 has succeeded,
so that a run whose evaluator errors and whose project lookup would also fail
has one determinate disposition rather than one depending on which lookup the
implementation happens to run first. Resolution has four outcomes and each has
a stated disposition, mirroring the error/empty split
`AC-OFFICE-BUDGET-001.13` makes for the workspace. (a) The payload is
well-formed and carries no task identifier, or the task resolves and carries
no project: the run genuinely has no project, no `project`-scoped policy
applies to it under `AC-OFFICE-BUDGET-001.15`, and this is not a fault.
(b) The lookup returns an error: an evaluator fault under
`AC-OFFICE-BUDGET-006.3`, deferred and retried. (c) The payload cannot be
parsed: the system shall not read this as outcome (a), because a payload it
cannot parse is no evidence that no task identifier was present; it shall
cancel the run rather than retry or fail it, and record an operator-visible
activity entry naming the unparseable payload. (d) The lookup succeeds and the
named task does not exist: the system shall likewise cancel the run, naming
the missing task. Cases (c) and (d) are permanent conditions no retry can
clear, so deferring them would spend the run's whole retry budget on something
that cannot resolve — the reasoning `AC-OFFICE-BUDGET-001.5` already applies
to an absent evaluator. A run cancelled here shall not re-enter the queue.
- **AC-OFFICE-BUDGET-006.5:** Each state this requirement introduces shall be
distinguishable, by the queryable activity-entry field
`AC-OFFICE-BUDGET-005.3` establishes, from `budget_blocked` and from every
other state that criterion enumerates: an evaluator fault raised by an
unevaluated policy (`AC-OFFICE-BUDGET-006.1`), one raised by a failed project
lookup (`AC-OFFICE-BUDGET-006.3`), and a deferral failed at `MaxRetryCount`
under `AC-OFFICE-BUDGET-006.4`, itself distinguishable by which of that
criterion's three causes produced it. The first two share
`AC-OFFICE-BUDGET-001.3`'s disposition with the evaluator fault proper and
shall still be distinguishable from it and from each other, because the three
have different operator remedies. An entry concerning an unevaluated policy —
whether the deferral under `AC-OFFICE-BUDGET-006.1` or its failure under
`AC-OFFICE-BUDGET-006.4` — shall name the policy it could not evaluate; every
other entry named here shall state that no ceiling was determined, per
`AC-OFFICE-BUDGET-005.5`. The two cancellations of `AC-OFFICE-BUDGET-006.7` —
an unparseable payload (c) and a task that does not exist (d) — are further
states on these same terms, distinguishable from each other and from the
failed-lookup deferral of (b), because an operator repairs a malformed payload
and a deleted task differently.
- **AC-OFFICE-BUDGET-006.6:** The system shall expose counters for each state in
`AC-OFFICE-BUDGET-006.5`, in the same `/debug/vars` surface and under the same
labelling and counting rules as `AC-OFFICE-BUDGET-005.4` — which means the two
deferral counters count deferral *attempts* rather than runs, under that
criterion's rule for every deferral counter, while a run failed at
`MaxRetryCount` increments one counter per cause named in
`AC-OFFICE-BUDGET-006.4`, not one counter shared across the three, each
counting runs once per run. Sharing one counter would satisfy this criterion
while defeating `AC-OFFICE-BUDGET-006.5`'s requirement that the causes stay
distinguishable. The two cancellations of `AC-OFFICE-BUDGET-006.7` likewise
carry one counter each, counting runs once per run.
## Out of scope
- **Changing the post-event evaluation path.** `AC-OFFICE-BUDGET-006.2` removes
two side effects from the *admission* path only. When `budget.alert` and
`budget.exceeded` fire, what `alert_threshold_pct` means, and when a
`pause_agent` policy pauses an agent all remain governed by
[costs.md](costs.md), on the post-event path, unchanged.
- **Unpausing an agent paused by the post-event path.** A known separate defect,
named in [budget-enforcement.md](budget-enforcement.md)'s Out of scope and not
fixed here.
- **Retrying an unevaluated policy in isolation.** `AC-OFFICE-BUDGET-006.1`
defers the whole run rather than re-evaluating the one policy that failed.
A per-policy retry inside a single admission decision would need its own
budget and its own bound, and would sit inside the gate sequence
`AC-OFFICE-BUDGET-001.14` fixes.
- **Distinguishing which underlying failure made a policy unevaluated.** A
timeout, a closed database and a malformed stored row all produce one state
here. The activity entry names the policy, per `AC-OFFICE-BUDGET-006.5`; it
does not classify the cause.
- **Retention or pruning of the activity entries this capability writes.**
- **The system design for this capability.** Where completeness is enforced and
how the admission path is separated from the post-event path belong in the
paired system-design document authored before implementation.
@@ -0,0 +1,132 @@
---
status: draft
system: office
created: 2026-09-06
owners:
- kandev
---
# Office: Built-In Default Spend Ceiling Requirements
## Overview
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies when a
run is admitted against a spend ceiling. Correct enforcement code with zero
policies configured is still no ceiling, and `office_budget_policies` holds
zero rows on the reference install. This document owns the bound that exists on
a fresh install without an operator opting in.
It does not change admission behavior, which stays in the companion document,
and it does not measure spend, which is
[Office: Budget Measurement Integrity](budget-measurement-integrity.md).
## Terminology
This document uses this capability's shared vocabulary, defined in the [Office
glossary](../glossary.md) under **Budget enforcement** — in particular
*attended run*, *unattended run*, *subcent*, *priced spend*, and *evaluation
window*.
- **Built-in default ceiling:** a single operator-tunable limit per workspace,
evaluated for unattended runs when no operator policy supersedes it. It is
**not** a row in `office_budget_policies`; see
`AC-OFFICE-BUDGET-003.7`.
## Requirements
### REQ-OFFICE-BUDGET-003: A default ceiling ships enabled for unattended runs
**Intent:** Beta needs a bound that exists without an operator opting in.
Scoping the default to unattended runs is what makes shipping it safe: attended
work, which is all of the reference install's measured spend, is unaffected by
its presence. The default is a *floor under* the operator's configuration, not
a placeholder the operator's first policy replaces — so a policy that never
blocks cannot remove it, and editing its limit cannot convert it into a policy
that blocks attended work.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-003.1:** When no operator policy supersedes it under
`AC-OFFICE-BUDGET-003.4`, the system shall evaluate unattended runs in that
workspace against the built-in default ceiling.
- **AC-OFFICE-BUDGET-003.2:** The built-in default ceiling shall be 500,000
subcents (50.00 USD) of priced spend per workspace per UTC day, and shall
block on reaching that limit in the manner of a `block_new_tasks` policy.
- **AC-OFFICE-BUDGET-003.3:** The built-in default shall apply to unattended
runs only, and shall never block an attended run, including after an operator
has changed its limit.
- **AC-OFFICE-BUDGET-003.4:** A workspace-scoped `daily` policy shall supersede
the built-in default for that workspace, replacing it rather than being
evaluated in addition to it, **only when that policy's action is
`pause_agent` or `block_new_tasks`**. A workspace-scoped `daily` policy whose
action is `notify_only` shall not supersede the built-in default, and both
shall be evaluated: the operator's policy notifies and the built-in default
still blocks. A policy that never blocks shall not remove the shipped
ceiling. A policy skipped under `AC-OFFICE-BUDGET-002.5`,
`AC-OFFICE-BUDGET-002.11` or `AC-OFFICE-BUDGET-002.14` shall not supersede the
built-in default either: a policy that is not evaluated cannot stand in for the
ceiling it displaces, so a malformed row restores the built-in ceiling rather
than removing every bound. Nor shall a run deferred or failed under
`AC-OFFICE-BUDGET-006.1`, or cancelled under `AC-OFFICE-BUDGET-006.7`, reach
this gate at all — an admission decision that
could not be completed does not become a decision that the default did not
apply.
- **AC-OFFICE-BUDGET-003.5:** The built-in default's limit shall be readable and
writable by an operator through the same surface that manages budget
policies, and its current effective value shall be visible there without
inspecting the database.
- **AC-OFFICE-BUDGET-003.6:** When the built-in default blocks a run, the
activity entry shall state that the ceiling was the built-in default and not
an operator-created policy.
- **AC-OFFICE-BUDGET-003.7:** Writing the built-in default's limit under
`AC-OFFICE-BUDGET-003.5` shall update a single durable per-workspace setting
addressed by a stable identifier, and shall not create, update, or delete any
row in `office_budget_policies`. The value shall not appear in the policy
list API's results, and the written value shall remain the built-in default:
it shall stay unattended-only under `AC-OFFICE-BUDGET-003.3` and shall
continue to be reported as the built-in default under
`AC-OFFICE-BUDGET-003.6`. Editing the limit shall not cause the default to be
superseded under `AC-OFFICE-BUDGET-003.4`.
- **AC-OFFICE-BUDGET-003.8:** When an operator writes a built-in default limit
less than or equal to zero, the system shall reject the write with a
validation error and leave the previous effective value in force.
- **AC-OFFICE-BUDGET-003.9:** When no operator has written a limit for a
workspace, that workspace's effective built-in default shall be the value in
`AC-OFFICE-BUDGET-003.2`. Reading the effective value shall return a limit
for every workspace, and shall never report the ceiling as absent.
- **AC-OFFICE-BUDGET-003.10:** When two operators write the built-in default's
limit for the same workspace concurrently, the last write ordered by the
setting's own commit shall be the effective value, and no write shall leave
the workspace with no effective limit.
- **AC-OFFICE-BUDGET-003.11:** The built-in default shall be evaluated by the
same criteria as a workspace-scoped `daily` policy whose action is
`block_new_tasks`, with its effective limit standing in for the policy limit
wherever those criteria name one. In particular the measurement-integrity
criteria apply to it: its window is `daily` under
`AC-OFFICE-BUDGET-002.1`, its spend is priced spend under
`AC-OFFICE-BUDGET-004.1`, and a pricing-degraded window blocks an unattended
run against it under `AC-OFFICE-BUDGET-004.3` and carries
`AC-OFFICE-BUDGET-005.7`'s outcome. Without this, a fresh install — whose
only ceiling is the built-in default — would never test for pricing
degradation at all, and measurement integrity would not in fact be a
precondition for shipping the default.
## Out of scope
- **Turning the ceiling off entirely.** There is no "disable" switch. An
operator who wants no effective unattended bound raises the limit, or creates
a workspace-scoped `daily` policy with a blocking action and a limit high
enough not to bind, which supersedes the default under
`AC-OFFICE-BUDGET-003.4`. Named so the absence of an off switch is a decision
rather than an omission.
- **Per-run, per-routine, per-agent and per-project defaults.** The built-in
default is per workspace per UTC day only. Operator policies already carry
`agent` and `project` scopes; nothing here ships a default for them.
- **Changing the default's value per install, per profile, or per environment
variable.** The shipped value is a constant, overridable only per workspace
through `AC-OFFICE-BUDGET-003.5`.
- **Notifying an operator that the built-in default is in force.**
`AC-OFFICE-BUDGET-003.6` requires attribution on a block; nothing here
announces the ceiling before it first binds.
- **Retention or pruning of the activity entries this capability writes.**
@@ -0,0 +1,316 @@
---
status: draft
system: office
created: 2026-09-06
owners:
- kandev
---
# Office: Pre-Launch Budget Enforcement Requirements
## Overview
[Office: Cost Tracking & Budget Management](costs.md) establishes that budget
policies exist and that `notify_only`, `pause_agent` and `block_new_tasks` are
their actions. It does not say what happens when the mechanism itself is absent,
broken, or measuring the wrong window. All three currently resolve to "launch
the agent anyway" — no evaluator wired returns allowed, an evaluator error
returns allowed behind an explicit `// fail-open on error` comment, and
`office_budget_policies` holds zero rows on the reference install — so an Office
run has no spend ceiling under any circumstance.
Fail-open is right while a human is watching a run start: a transient fault
should not block work somebody is waiting on. That does not extend to an
unattended schedule. A `*/5` routine that fails open on an evaluator error is a
loop with no upper bound on cost, running while nobody is looking, whose only
feedback arrives on a bill.
That argument survives here in one place only. An evaluator that is entirely
**absent** is a deployment fact no run can change, so an attended run launches
against it (`AC-OFFICE-BUDGET-001.6`). An evaluator that **errors** is not: the
error may clear, so every run defers and retries regardless of provenance
(`AC-OFFICE-BUDGET-001.3`), and a fault outliving the retry budget fails the run
rather than launching it, again regardless of provenance
(`AC-OFFICE-BUDGET-001.4`). Deferring is what keeps a transient fault from
blocking attended work; this spec does not fail open on an evaluator error for
anybody.
This capability gives the unattended loop a ceiling enforced **before** launch
and makes the inert states observable instead of silent. Office owns the
contract because the states are defined by Office primitives: the run queue,
reason, outcome and cost ledger. It bounds spend; it does not price models,
change how cost events are produced, or recover an overspent workspace.
The capability spans six documents. This one owns the admission decision;
[Run Provenance Classification](budget-run-provenance.md) the attended/
unattended split every gate here reads; [Budget Admission
Integrity](budget-admission-integrity.md) that the decision sees every
applicable policy and changes nothing on its way to one; [Built-In Default Spend
Ceiling](budget-default-ceiling.md) the bound that ships enabled; [Budget
Measurement Integrity](budget-measurement-integrity.md) the number the ceiling
is compared against, a precondition for both; and [Budget Enforcement
Observability](budget-observability.md) which state fired.
## Prior art
**Receipt, internal wiki leg: NOT RUN, tooling unavailable.** Config resolved via
`@henry` to `OBSIDIAN_VAULT_PATH=/Users/henry/Documents/henry/wiki`,
`QMD_WIKI_COLLECTION=wiki`. Every read of that path returns `EPERM` (macOS TCC on
`~/Documents`), confirmed two ways: `index.md` and `hot.md` EPERM while a
nonexistent sibling returns not-found, so the vault is present and the denial is
access control. No `qmd`, `obsidian-wiki` or `obsidian-cli` on PATH, no QMD MCP
tool exposed. Re-run before treating this spec as settled: a recorded standing
position on fail-open gates would outrank the reasoning here.
**Receipt, vendor leg: SUBSTITUTED.** `saas-kb` and its `search_fsm_docs` are not
exposed in this session, so the `ai_sdlc` slice could not be queried; a public web
search ran instead. Vendor claims, not evidence. Self-hosted **OpenHands** ships
no built-in hard cost cap while its cloud product offers exactly the scheduled
runs this spec is about; **Devin** bills opaque ACU consumption with no published
pre-launch ceiling; provider caps are reported as advisory or too coarse to catch
a loop running for hours. The recurring practitioner finding is that
observability is not enforcement. One credible **dissenting** view holds
monitoring should precede hard caps, since a cap can stop a high-priority
workflow midstream — which is why the [built-in
default](budget-default-ceiling.md) gates unattended runs only.
**Receipt, in-repo prior art: READ.** `shared.IsPeriodicTasklessWake`
(`office/shared/runreasons.go`) already classifies provenance from `runs.reason`
with a deliberate safe default for the ambiguous legacy literal; this spec reuses
its shape and inverts its polarity, per the glossary's warning. [Office Stall
Visibility](stall-visibility.md) sets the precedent for a detect-only safety
capability. The Office run-outcome vocabulary
([task-delivery-ledger](../../task-delivery-ledger/spec.md)) already gives each
terminal shape a distinct `runs.outcome`, including `budget_blocked` — so this
spec extends that vocabulary rather than establishing it, correcting the
originating card's claim that the shape is not yet distinguishable.
**What we are doing differently.** Every vendor position found is either "no cap"
or "opaque cap". This spec makes the ceiling explicit, pins its window and
currency, ships it enabled for the unattended path only, and makes each inert
state individually observable rather than collapsed into one boolean.
## Terminology
This capability's shared vocabulary — *run provenance*, *attended run*,
*unattended run*, *subcent*, *priced spend*, *unpriced event*, *pricing-degraded
window*, *evaluator fault*, *evaluation window*, *admission gate*, *applicable
policy*, and the polarity warning about `IsPeriodicTasklessWake` — is defined
once in the [Office glossary](../glossary.md) under **Budget enforcement**, and
is normative for every document of this capability.
## Requirements
### REQ-OFFICE-BUDGET-001: Unattended runs have a pre-launch spend ceiling
**Intent:** Remove the fail-open paths so that no Office run launches without a
ceiling having been evaluated, while keeping a *transient* evaluator fault from
blocking work a person is waiting on — without letting a persistent one launch
an unbounded run.
**User story:** As an operator running Office unattended, I want a schedule to
stop launching when it has spent its ceiling or when the ceiling cannot be
evaluated, so that a runaway loop costs a bounded amount rather than an
unbounded one.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-001.1:** The provenance every criterion below relies on
shall be the one `REQ-OFFICE-BUDGET-007` in [Run Provenance
Classification](budget-run-provenance.md) produces, computed once before any
policy is read. No gate in this document shall recompute or revise it, so two
gates evaluating the same run cannot disagree about whether it is attended.
- **AC-OFFICE-BUDGET-001.2:** Wherever this document says *attended* or
*unattended* it means exactly `AC-OFFICE-BUDGET-007.2`'s classification of the
run's reason, including that criterion's rule that an unrecognized value is
unattended. No criterion here shall introduce a third state, and none shall
treat an unclassifiable run as exempt from a gate.
- **AC-OFFICE-BUDGET-001.3:** When the evaluator reports an error, the system
shall not launch the agent, shall release any task checkout the run holds,
and shall schedule the run for retry, for both attended and unattended runs.
- **AC-OFFICE-BUDGET-001.4:** When a run scheduled for retry under
`AC-OFFICE-BUDGET-001.3` has already reached `MaxRetryCount`, the system
shall fail the run and record an operator-visible activity entry naming the
evaluator error.
- **AC-OFFICE-BUDGET-001.5:** When no budget evaluator is wired and the run is
unattended, the system shall not launch the agent, shall cancel the run rather
than retry or fail it, and shall record an operator-visible activity entry
stating that budget enforcement is unavailable. An absent evaluator is a
deployment state and not a transient fault: it cannot resolve without an
operator changing the deployment, so retrying under
`AC-OFFICE-BUDGET-001.3` would spend the run's whole retry budget on a
condition no retry can clear. A cancelled run shall not re-enter the queue, so
the entries this criterion writes are bounded by the number of runs queued
rather than by scheduler ticks.
- **AC-OFFICE-BUDGET-001.6:** When no budget evaluator is wired and the run is
attended, the system shall launch the agent.
- **AC-OFFICE-BUDGET-001.7:** When an applicable policy's action is
`pause_agent` or `block_new_tasks` and priced spend in its evaluation window
is greater than or equal to its limit, the system shall not launch the agent
and shall finish the run with outcome `budget_blocked`.
- **AC-OFFICE-BUDGET-001.8:** When an applicable policy's action is
`notify_only`, the system shall launch the agent regardless of that policy's
spend, for both attended and unattended runs, **except where
`AC-OFFICE-BUDGET-004.3` in
[budget-measurement-integrity.md](budget-measurement-integrity.md) blocks the
run**. A `notify_only` action is a statement about a known spend figure; a
pricing-degraded window has no trustworthy figure for it to be a statement
about, so `notify_only` does not extend to that case.
- **AC-OFFICE-BUDGET-001.9:** When more than one policy applies, the system
shall evaluate policies ordered by `created_at` ascending, tie-broken by
`id` ascending, and shall block on the first policy that satisfies
`AC-OFFICE-BUDGET-001.7` or `AC-OFFICE-BUDGET-004.3`. Every applicable policy
shall be evaluated against one captured evaluation instant, so that two
policies in the same run cannot observe different windows. Gate 5 of
`AC-OFFICE-BUDGET-001.14` shall evaluate the built-in default against that
same instant, so a policy and the default cannot fall on opposite sides of a
UTC midnight within one run. This ordering selects which policy *decides*; it
never limits which policies are *evaluated*. Every applicable policy shall
have both its limit test and its pricing-degradation determination completed
before this ordering selects one, per `AC-OFFICE-BUDGET-006.1`, so blocking on
the first such policy cannot leave a later one unevaluated. The rule is
internal to gate 4: the gate sequence of `AC-OFFICE-BUDGET-001.14` still stops
at the first gate yielding a non-launch decision.
- **AC-OFFICE-BUDGET-001.10:** When two runs are evaluated concurrently against
the same policy, each shall observe the spend committed at its own evaluation
instant; the check is an admission test and not a reservation, so the ceiling
can be exceeded by the cost of the runs already in flight when it was
crossed. The system shall not hold a lock across launch to prevent this.
- **AC-OFFICE-BUDGET-001.11:** When a run is blocked or deferred by any
criterion in this capability, the system shall not have launched an agent
process, minted a runtime token, or assembled a prompt for that run.
- **AC-OFFICE-BUDGET-001.12:** When a run is blocked or deferred by any
criterion in this capability — including a block by
`AC-OFFICE-BUDGET-004.3` or by the built-in default — the system shall
release the task checkout that run holds, scoped to that run as its owner,
before the run reaches its terminal or retry-scheduled state. A run that
never held a checkout shall not clear another run's checkout.
- **AC-OFFICE-BUDGET-001.13:** A run carries no workspace identifier of its
own; its workspace is that of the agent instance the run names. Resolving the
workspace therefore means resolving that agent instance, and this criterion
constrains the disposition of that resolution wherever it already happens
rather than adding a second one. When the workspace cannot be resolved, the
system shall not launch the agent, for both attended and unattended runs. An
unresolvable workspace shall not be evaluated as a workspace with no policies
and no spend, and shall not change the run's provenance. The two ways
resolution can fail have different dispositions. When the lookup returns an
error, the run shall be deferred and retried on the same terms as an evaluator
fault (`AC-OFFICE-BUDGET-001.3`, `AC-OFFICE-BUDGET-001.16`,
`AC-OFFICE-BUDGET-001.18`, and at `MaxRetryCount`
`AC-OFFICE-BUDGET-006.4`), an I/O failure being transient. When the lookup
succeeds and yields no agent instance, or yields one carrying no workspace
identifier, the run shall be cancelled rather than retried or failed, an
orphaned run having no ceiling that could ever be evaluated. Each cancellation
shall record its own operator-visible activity entry, and a cancelled run shall
not re-enter the queue. Neither disposition shall queue a run for any other
agent, per `AC-OFFICE-BUDGET-001.17`.
- **AC-OFFICE-BUDGET-001.14:** The admission gates shall be evaluated in this
order, and the first gate that yields a non-launch decision shall determine
the run's disposition, with no later gate evaluated: (1) workspace resolution
(`AC-OFFICE-BUDGET-001.13`); (2) evaluator presence
(`AC-OFFICE-BUDGET-001.5`, `AC-OFFICE-BUDGET-001.6`); (3) evaluator
invocation (`AC-OFFICE-BUDGET-001.3`); (4) applicable policies in
`AC-OFFICE-BUDGET-001.9` order, each tested for limit
(`AC-OFFICE-BUDGET-001.7`) then for pricing degradation
(`AC-OFFICE-BUDGET-004.3`); (5) the built-in default
(`AC-OFFICE-BUDGET-003.1`), tested for limit then for pricing degradation in
the same order as gate 4, per `AC-OFFICE-BUDGET-003.11`. A run that reaches
the end of the sequence without a non-launch decision shall launch.
This ordering is ordinal among *these* gates only: it does not reorder the
checks Office already performs before launch and this capability does not
govern, and gate 1 constrains the disposition of the workspace resolution
wherever that resolution already occurs rather than requiring a second one.
The run's project identifier is resolved at the start of gate 4, after gate 3
has succeeded, per `AC-OFFICE-BUDGET-006.7`.
"Tested for limit then for pricing degradation" at gates 4 and 5 fixes which
criterion decides the disposition, not what gets computed: the
pricing-degradation determination of `AC-OFFICE-BUDGET-004.2` shall be made for
every policy this sequence evaluates, including one whose limit test has
already decided to block, because `AC-OFFICE-BUDGET-004.6` requires the
activity entry carry it in exactly that case.
- **AC-OFFICE-BUDGET-001.15:** A policy applies to a run when its scope matches
that run: a `workspace`-scoped policy applies to every run in its workspace;
an `agent`-scoped policy applies when its `scope_id` equals the run's agent
instance identifier; a `project`-scoped policy applies when its `scope_id`
equals the run's project identifier. When the run carries no project
identifier, no `project`-scoped policy applies to it; when it carries no
agent instance identifier, no `agent`-scoped policy applies to it. A policy
shall never apply by both identifiers being empty. A failure to *determine*
either identifier is not the same as the run lacking it: for the agent
instance see `AC-OFFICE-BUDGET-001.13`, for the project
`AC-OFFICE-BUDGET-006.3`.
- **AC-OFFICE-BUDGET-001.16:** A deferral under `AC-OFFICE-BUDGET-001.3` shall
increment the same `runs.retry_count` the run's other retry classes use, so
that `MaxRetryCount` bounds a run's total retries across all causes rather
than granting evaluator faults their own budget, and shall schedule the retry
no sooner than the first delay in the existing retry backoff schedule. The
system shall not requeue a deferred run within the same scheduler tick.
- **AC-OFFICE-BUDGET-001.17:** Failing a run under `AC-OFFICE-BUDGET-001.4`
shall not queue any new run, and in particular shall not queue an escalation
run for another agent. A broken evaluator shall not cause an agent launch by
any path.
- **AC-OFFICE-BUDGET-001.18:** When a run deferred under
`AC-OFFICE-BUDGET-001.3` is too old to retry under the existing retry
staleness bound, the system shall cancel it rather than retry or fail it, and
shall record an operator-visible activity entry naming budget deferral as the
cause of the cancellation.
### Companion requirements
`REQ-OFFICE-BUDGET-005` (each state individually observable) is specified in
[Budget Enforcement Observability](budget-observability.md), and
`REQ-OFFICE-BUDGET-007` (provenance is a total function of the run's reason) in
[Run Provenance Classification](budget-run-provenance.md), which
`AC-OFFICE-BUDGET-001.1` and `AC-OFFICE-BUDGET-001.2` bind these gates to.
`REQ-OFFICE-BUDGET-006` (the admission decision is complete and inert) is
specified in [Budget Admission Integrity](budget-admission-integrity.md) and
constrains the gates above: a partially evaluated policy set is an evaluator
fault (`AC-OFFICE-BUDGET-006.1`), and reaching any decision here writes no alert
entry and changes no agent's status (`AC-OFFICE-BUDGET-006.2`).
## Out of scope
- **Reserving budget across concurrent launches.** `AC-OFFICE-BUDGET-001.10`
deliberately admits overshoot bounded by in-flight concurrency; a true
reservation needs a durable counter decremented at launch and reconciled at
completion. Named so the overshoot is a decision, not an omission.
- **Duplicate delivery of one run row to two consumers.** That single-consumer
contract is the existing run-claim mechanism's. `AC-OFFICE-BUDGET-001.10`
covers two *different* runs, not one run twice.
- **Exactly-once delivery of activity entries and counters.** Every Office expvar
counter is best-effort; a crash between a block and its increment loses it and
does not reverse the block.
- **Token-rate circuit breaking.** Watching consumption *rate* to catch a loop
before it spends its ceiling is a complementary control; this spec bounds total
spend per window only.
- **Per-run and per-routine ceilings.** A per-window workspace ceiling bounds
total cost, which is what NFR-5 requires; two more scopes would multiply the
policy-precedence surface for no additional bound. A future requirement can add
them within this evaluation model.
- **Distinguishing an agent-caused event wake from a human-caused one.**
`AC-OFFICE-BUDGET-007.2` classifies `task_comment`, `task_mentioned`,
`task_children_completed` and `task_blockers_resolved` as attended, though an
agent can cause all of them. Without a causation identifier the run row cannot
tell them apart, and classifying them unattended would apply the built-in
default to the bulk of ordinary event-driven work. A known gap; closing it
depends on the causation-id work tracked as the runaway-chain card.
- **Repairing the inbox "Mark fixed" action.** `manual_resume_after_failure` is
attended because only an operator click queues it, but that click is separately
broken: the agent stays paused and the requeue is rejected and swallowed as a
warning, so a budget test passing on that reason is not evidence the recovery
flow works. Card `497b1f63`; not fixed here.
- **Unpausing an agent that a `pause_agent` policy paused.** The existing "mark
fixed" path does not unpause. A separate known defect.
- **Currencies other than United States dollars.** The storage unit is fixed at
subcents of USD.
- **Alert thresholds and the post-event evaluation path.**
`alert_threshold_pct`, the `budget.alert` and `budget.exceeded` entries, and
the agent-pause side effect of a post-event evaluation remain governed by
[costs.md](costs.md). This spec constrains only the pre-launch admission
decision, which `AC-OFFICE-BUDGET-006.2` requires produce none of them, so the
two paths do not overlap.
- **Retention or pruning of the activity entries this capability writes.**
- **The system design.** The technical path, including where provenance
classification lives and how the built-in default's setting is stored, belongs
in a paired system-design document authored first.
@@ -0,0 +1,277 @@
---
status: draft
system: office
created: 2026-09-06
owners:
- kandev
---
# Office: Budget Measurement Integrity Requirements
## Overview
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies when a
run is admitted against a spend ceiling. That contract is only as strong as the
number the ceiling is compared against, and today that number is wrong in two
independent ways: a policy's declared period does not select the window it
names, and spend whose price is unknown is counted as zero. Both weaken
enforcement silently, and both must be closed before the daily default ceiling
in [Built-In Default Spend Ceiling](budget-default-ceiling.md) can ship.
This document owns the measurement. It does not change admission behavior,
which stays in the companion documents, and it does not price models.
## Terminology
This document uses this capability's shared vocabulary, defined in the [Office
glossary](../glossary.md) under **Budget enforcement** — in particular
*subcent*, *priced spend*, *unpriced event*, *pricing-degraded window*,
*attended run*, *unattended run*, and *evaluation window*.
## Requirements
### REQ-OFFICE-BUDGET-002: A policy means what it says
**Intent:** The period contract disagrees across four layers. The model enum
declares `daily`, `monthly`, `yearly`, and both handlers validate against it
(`office/costs/handler.go:144`, `:178`). The evaluator recognizes only
`monthly` and returns the zero time otherwise, which its consumers read as "no
filter", so a `daily` or `yearly` policy silently measures **lifetime** spend.
On the reference install lifetime spend is 281,106,390 subcents against a
busiest day of 23,813,441, so a daily policy would be permanently exceeded from
creation, with no error and no log. Meanwhile the create form offers only
`monthly` and `total`, and `total` is not in the enum, so choosing it returns
HTTP 400 — the UI's second of two options cannot save. Backend tests
(`office/costs/budgets_test.go:305`) exercise `total`, a value the product
rejects. A shipped daily default is unsafe until this is closed.
The same requirement also covers policy *validity*, because a malformed policy
disarms the ceiling by the same silent mechanism a wrong window does.
`limit_subcents` carries no CHECK constraint, so a non-positive limit is
storable, and an `agent`- or `project`-scoped policy with an empty `scope_id`
matches every run whose corresponding identifier is also empty. Criteria
`AC-OFFICE-BUDGET-002.6`, `-002.7` and `-002.11` close the write path and the
rows stored before it closed. They belong to this requirement rather than a
separate one because the failure mode is identical: a policy that appears to
bound spend and does not.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-002.1:** When a policy's period is `daily`, its evaluation
window shall start at the most recent UTC midnight at or before the
evaluation instant.
- **AC-OFFICE-BUDGET-002.2:** When a policy's period is `monthly`, its
evaluation window shall start at 00:00:00 UTC on the first day of the
evaluation instant's UTC month.
- **AC-OFFICE-BUDGET-002.3:** When a policy's period is `yearly`, its evaluation
window shall start at 00:00:00 UTC on 1 January of the evaluation instant's
UTC year.
- **AC-OFFICE-BUDGET-002.4:** Every evaluation window shall be computed in UTC,
and shall not shift with the host's local time zone or its daylight-saving
transitions.
- **AC-OFFICE-BUDGET-002.5:** When a policy carries a period value the build
does not recognize, the system shall not evaluate that policy as a lifetime
window; it shall skip the policy and record an operator-visible activity
entry naming the policy and the unrecognized value. A skipped policy shall
not supersede the built-in default under `AC-OFFICE-BUDGET-003.4`, so
skipping the only workspace-scoped `daily` policy restores the built-in
ceiling rather than removing every bound.
- **AC-OFFICE-BUDGET-002.6:** When a policy is created or updated with a limit
less than or equal to zero, the system shall reject the write with a
validation error rather than storing a policy that blocks every run.
- **AC-OFFICE-BUDGET-002.7:** When a policy is created or updated with scope
`agent` or `project` and an empty scope identifier, the system shall reject
the write with a validation error, rather than storing a policy that matches
every run whose corresponding identifier is also empty.
- **AC-OFFICE-BUDGET-002.8:** `total` shall be a declared period value whose
evaluation window is unbounded below, so that the lifetime window is
selected by name rather than by falling through from an unrecognized value.
- **AC-OFFICE-BUDGET-002.9:** Every period value the policy-management surface
offers shall be accepted by the write API, and every declared period value
shall be offered by that surface. Selecting any offered period and saving
shall create a policy rather than return a validation error.
- **AC-OFFICE-BUDGET-002.10:** Priced spend for an evaluation window shall be
summed over cost events whose `office_cost_events.occurred_at` falls in that
window, not over an insertion or ingestion timestamp, so that a delayed write
is counted against the period in which the spend occurred. `occurred_at` is
`NOT NULL` in the stored schema, so no null-timestamp branch is required. A
cost event whose `occurred_at` is after the evaluation instant shall be
excluded from that evaluation, so a clock-skewed or back-dated write cannot
be counted against a window that has not begun.
- **AC-OFFICE-BUDGET-002.11:** When a stored policy carries a limit less than or
equal to zero, the system shall skip that policy and record an
operator-visible activity entry naming the policy and its limit, in the same
manner as `AC-OFFICE-BUDGET-002.5`, rather than blocking every run in the
workspace. A policy skipped under this criterion shall not supersede the
built-in default under `AC-OFFICE-BUDGET-003.4`, on the same reasoning
`AC-OFFICE-BUDGET-002.5` states: a workspace-scoped `daily` policy carrying a
blocking action and a non-positive limit would otherwise satisfy that
supersession test while being skipped itself, leaving the workspace with no
unattended ceiling at all — the exact failure this capability exists to
remove. `AC-OFFICE-BUDGET-002.6` prevents new such rows; this criterion
covers rows stored before it shipped.
- **AC-OFFICE-BUDGET-002.12:** A test shall fail the build when the set of
period values the policy-management surface offers differs from the set the
write API declares. The test shall derive both sets by reading their
respective sources rather than comparing against a list maintained alongside
them, so that adding a period value on either side cannot silently reproduce
the defect `AC-OFFICE-BUDGET-002.9` exists to fix. The check shall live in the
backend Go test suite, so that `make -C apps/backend test` is its single gate
rather than the parity being split across two pipelines and enforced by
neither. It shall derive the declared set from the `BudgetPeriod` enum's own
validation, and the offered set by reading the policy-creation form component
under `apps/web/app/office/workspace/costs/`, and shall fail on any value
present in one set and absent from the other.
- **AC-OFFICE-BUDGET-002.13:** An activity entry required by
`AC-OFFICE-BUDGET-002.5`, `AC-OFFICE-BUDGET-002.11` or
`AC-OFFICE-BUDGET-002.14` shall be recorded at most once per policy per UTC
day, rather than once per evaluation, so that a frequently scheduled routine
re-evaluating one malformed policy does not write an unbounded stream of
identical entries. The bound is per policy in aggregate, not per violated
criterion: a policy violating more than one of those criteria shall produce one
entry naming every violation detected, not one entry per violation. The bound
is best-effort under concurrency, on the same reasoning as the counters — two
runs evaluating the same policy concurrently may each observe that no entry
exists yet and each write one, because `AC-OFFICE-BUDGET-001.10` forbids
holding a lock across the decision. A duplicate entry is acceptable; this
bound exists to stop a per-evaluation stream, not to guarantee uniqueness.
- **AC-OFFICE-BUDGET-002.14:** When a stored policy carries a scope type the
build does not recognize, an action the build does not recognize, or a scope
of `agent` or `project` with an empty scope identifier, the system shall skip
that policy and record an operator-visible activity entry naming the policy
and the offending field, in the same manner as `AC-OFFICE-BUDGET-002.5`, and
that policy shall not supersede the built-in default under
`AC-OFFICE-BUDGET-003.4`. Skipping is the disposition for every stored policy
the build cannot evaluate as written; together with `AC-OFFICE-BUDGET-002.5`
and `AC-OFFICE-BUDGET-002.11` this makes that rule total over the policy row,
so no malformed field is left to a code path that silently treats the policy
as bounding nothing. For the empty-scope-identifier case this is the
observable form of an exclusion `AC-OFFICE-BUDGET-001.15` already requires:
the two agree that the policy does not bound the run, and this criterion adds
the operator-visible record. `AC-OFFICE-BUDGET-002.6` and
`AC-OFFICE-BUDGET-002.7` prevent new such rows; this criterion covers rows
stored before they shipped and rows written by any path that bypasses the
write API. A policy skipped here is not an unevaluated policy under
`AC-OFFICE-BUDGET-006.1`, whose disposition could not be decided; this one's
is decided here.
- **AC-OFFICE-BUDGET-002.15:** A policy's evaluation shall select the cost
events it measures by scope, and the same selection shall serve both the
priced-spend sum of `AC-OFFICE-BUDGET-004.1` and the pricing-degradation
determination of `AC-OFFICE-BUDGET-004.2`. A `workspace`-scoped policy, and
the built-in default under `AC-OFFICE-BUDGET-003.11`, shall select every cost
event incurred by an agent instance belonging to that workspace — the same
derivation `AC-OFFICE-BUDGET-001.13` uses to give a run its workspace.
Selection shall not depend on the continued existence of the event's task: an
event carrying no task identifier, or one whose task row has since been
deleted, shall still count against its workspace. Otherwise deleting a task
would retroactively lower spend already incurred, and a taskless periodic wake
— the unattended shape this capability most exists to bound — would be exempt
from the ceiling. An `agent`-scoped policy shall select events whose agent
instance equals its `scope_id`. A `project`-scoped policy shall select events
by the project recorded on the cost event itself when the spend occurred, not
by the current project of the event's task, so that reparenting a task does
not move historical spend between ceilings. Where an event cannot be
attributed to the scope at all it is outside that policy's measurement and is
not an unevaluated policy under `AC-OFFICE-BUDGET-006.1`, which concerns a
policy the system could not evaluate rather than an event it did not select.
### REQ-OFFICE-BUDGET-004: Unpriced spend cannot silently raise the ceiling
**Intent:** When no price can be resolved for a turn's tokens, Office records
the cost event with `cost_subcents = 0` and `cost_source = 'unpriced'`
(`office/service/prompt_usage_cost.go`, the three `CostSourceUnpriced`
branches of `resolveCostForUsage`), so tokens whose price is unknown are
invisible to every sum the ceiling is computed from. Enforcement therefore
weakens exactly when pricing breaks. Note that `cost_source` is the
price-resolution flag and is deliberately distinct from `estimated`, which is a
usage-authority flag. The two are independent, and the code is explicit about
it: `resolveCostForUsage` copies `estimated` from the reported usage on every
branch, the three unpriced branches included, so an unpriced row can carry
`estimated` either way and neither flag implies the other. Degradation must
therefore be determined from `cost_source`, never from `estimated`. The reference install
shows this is real but rare — 3 unpriced events in 4,672 — which is why the
rule below reacts to unpriced events only as the ceiling is approached, rather
than blocking on a single stray row.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-004.1:** The ceiling comparison shall use priced spend, in
subcents, denominated in United States dollars.
- **AC-OFFICE-BUDGET-004.2:** When evaluating a policy, the system shall also
determine whether the evaluation window is pricing-degraded, counting only
events whose `cost_source` is `unpriced` and treating a NULL `cost_source` as
priced. The determination shall not read the `estimated` column.
- **AC-OFFICE-BUDGET-004.3:** When the evaluation window is pricing-degraded,
priced spend is greater than or equal to 50 percent of the policy limit, and
the run is unattended, the system shall not launch the agent. The 50 percent
comparison shall be exact and shall not be computed by halving the limit with
integer division: the threshold is reached when twice the priced spend is
greater than or equal to the limit. Truncating an odd subcent limit would move
the threshold down by half a subcent and fire the criterion early,
deterministically and invisibly. This is the comparison every criterion in this
document means by "50 percent of the policy limit". This criterion
applies whatever the policy's action, and overrides
`AC-OFFICE-BUDGET-001.8`'s admission of a `notify_only` policy: a
`notify_only` action expresses a judgement about a known spend figure, and a
pricing-degraded window has no trustworthy figure for it to be a judgement
about.
- **AC-OFFICE-BUDGET-004.4:** When the evaluation window is pricing-degraded and
priced spend is below 50 percent of the policy limit, this criterion shall not
block the run, and the system shall record that the window was
pricing-degraded under `AC-OFFICE-BUDGET-004.8`. Whether the run launches is
then determined by the remaining gates of `AC-OFFICE-BUDGET-001.14`: a later
policy in `AC-OFFICE-BUDGET-001.9`'s order, or the built-in default at gate 5,
may still block it.
- **AC-OFFICE-BUDGET-004.5:** The system shall not substitute an assumed,
averaged, or interpolated price for an unpriced event when computing spend.
- **AC-OFFICE-BUDGET-004.6:** A pricing-degraded block shall be distinguishable
from a limit-exceeded block by a queryable field on the activity entry, per
`AC-OFFICE-BUDGET-005.3`. Where the blocked run's priced spend did not reach
the policy limit, it shall additionally carry the distinct run outcome
required by `AC-OFFICE-BUDGET-005.7`; where the limit was also reached, the
outcome is `budget_blocked` and the degradation is carried by the activity
entry alone.
- **AC-OFFICE-BUDGET-004.7:** When the evaluation window is pricing-degraded,
priced spend is greater than or equal to 50 percent of the policy limit, and
the run is **attended**, this criterion shall not block the run, and the
system shall record that the window was pricing-degraded under
`AC-OFFICE-BUDGET-004.8`. Pricing degradation shall never block an attended
run. Whether the run launches is determined by the remaining gates of
`AC-OFFICE-BUDGET-001.14`; in particular a limit reached under
`AC-OFFICE-BUDGET-001.7` still blocks the run at gate 4, which tests limit
before degradation.
- **AC-OFFICE-BUDGET-004.8:** The record required by `AC-OFFICE-BUDGET-004.4`
and `AC-OFFICE-BUDGET-004.7` shall be an operator-visible activity entry
carrying the same queryable field `AC-OFFICE-BUDGET-005.3` uses to distinguish
a pricing-degraded block, set to a value distinct from that block's, so an
admitted degraded window and a blocked one cannot be confused by a query. One
entry shall be written per policy whose window was pricing-degraded and which
did not block, naming that policy identifier, or stating that the ceiling was
the built-in default. It shall be recorded at most once per policy per UTC
day, in the manner of `AC-OFFICE-BUDGET-002.13`, so that a frequently
scheduled routine running in a persistently degraded window does not write an
unbounded stream of identical entries.
## Out of scope
- **Admission behavior.** Whether a run launches, defers, or is blocked is
specified in [Office: Pre-Launch Budget Enforcement](budget-enforcement.md);
the criteria here that stop a run do so by feeding that document's gates.
- **Pricing lookup itself.** How a model's rate is resolved, and the
`models.dev` cache behavior, remain governed by [costs.md](costs.md).
- **Repairing the unpriced write path.** Nothing here changes how an unpriced
cost event is recorded; `cost_subcents = 0` with `cost_source = 'unpriced'`
remains the stored shape, and this document only stops that shape from
silently raising a ceiling.
- **Backfilling historical rows.** The reference install holds 1,135 cost
events with a NULL `cost_source`, written before the column existed. They are
treated as priced and are not re-derived.
- **Migrating existing policies.** No requirement here rewrites a stored policy
whose period is currently interpreted as lifetime, or whose limit is
non-positive; the operator-visible entries in `AC-OFFICE-BUDGET-002.5` and
`AC-OFFICE-BUDGET-002.11` are the migration signal.
- **Making the 50 percent degradation threshold configurable.** It is a
constant. A future requirement can make it a policy field within the same
evaluation model.
@@ -0,0 +1,143 @@
---
status: draft
system: office
created: 2026-09-06
owners:
- kandev
---
# Office: Budget Enforcement Observability Requirements
## Overview
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) specifies when a
run is admitted against a spend ceiling, and can stop a run for several
distinct reasons. This document owns making which reason fired legible to an
operator. It does not change admission behavior.
The failure this capability exists to remove was silent. A ceiling that stops a
loop without saying which of several things happened reproduces the same
blindness one layer up.
## Terminology
This document uses this capability's shared vocabulary, defined in the [Office
glossary](../glossary.md) under **Budget enforcement** — in particular *run
provenance*, *attended run*, *unattended run*, *evaluator fault*,
*pricing-degraded window*, and *admission gate*.
## Requirements
### REQ-OFFICE-BUDGET-005: Each inert or blocking state is individually observable
**Intent:** The failure this capability exists to remove was silent. A ceiling
that stops a loop without saying which of several things happened reproduces
the same blindness one layer up. `runs.outcome` already distinguishes
`budget_blocked` from the other terminal shapes; the states this spec adds
need the same treatment rather than being folded into it.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-005.1:** A run blocked because a policy limit or the
built-in default's limit was reached shall carry outcome `budget_blocked`.
That outcome shall mean the limit was actually reached, and no other state in
this capability shall use it.
- **AC-OFFICE-BUDGET-005.2:** A run deferred by an evaluator fault
(`AC-OFFICE-BUDGET-001.3`) shall not carry outcome `budget_blocked`, because
no ceiling was determined to have been reached.
- **AC-OFFICE-BUDGET-005.3:** Each of the following shall be distinguishable
from `budget_blocked` and from each other by a field on its activity entry
that is queryable without parsing free text: a block because no evaluator was
wired (`AC-OFFICE-BUDGET-001.5`); a deferral because the workspace lookup
errored and a cancellation because the lookup yielded no workspace, which
`AC-OFFICE-BUDGET-001.13` gives different dispositions and which shall
therefore be distinguishable from each other and not collapsed into one
unresolvable-workspace state; a deferral by evaluator fault
(`AC-OFFICE-BUDGET-001.3`), distinguishable from the workspace-lookup deferral
even though the two share a retry path; a cancellation of a stale deferral
(`AC-OFFICE-BUDGET-001.18`); and a block by a pricing-degraded window
(`AC-OFFICE-BUDGET-004.3`, in
[budget-measurement-integrity.md](budget-measurement-integrity.md)). A
queryable activity-entry field is the uniform mechanism; an outcome value is
required only where `AC-OFFICE-BUDGET-005.7` names one.
`AC-OFFICE-BUDGET-006.5` adds five further states to this list, on the same
terms.
- **AC-OFFICE-BUDGET-005.4:** The system shall expose counters, in the same
`/debug/vars` surface as the existing Office metrics, for: runs blocked by
limit, runs deferred by evaluator fault, runs blocked by absent evaluator,
runs deferred by a workspace-lookup error, runs cancelled as having no
resolvable workspace, runs cancelled as stale deferrals,
runs blocked by pricing degradation, runs admitted against the built-in
default, and runs admitted against a pricing-degraded window
(`AC-OFFICE-BUDGET-004.8`). Each counter shall be labelled by run provenance,
using the provenance `AC-OFFICE-BUDGET-007.1` produced. Each counter shall
count runs, once per run, with one exception: every deferral counter shall
count deferral *attempts*, matching `AC-OFFICE-BUDGET-005.6`'s
one-entry-per-attempt rule, so a run deferred four times before failing
increments it four times. Without that exception stated, the same run could be
counted once or four times and neither reading would be wrong.
The counter for runs admitted against a pricing-degraded window shall increment
only for a run whose final disposition was launch, and not once per
`AC-OFFICE-BUDGET-004.8` entry. That entry is written per non-blocking degraded
policy, and a later policy in `AC-OFFICE-BUDGET-001.9`'s order — or the
built-in default at gate 5 — may still block the run, so counting entries would
report a blocked run as admitted.
- **AC-OFFICE-BUDGET-005.5:** Every activity entry this capability writes that
acted on a policy or on the built-in default shall name the policy identifier
it acted on, or state explicitly that the ceiling was the built-in default.
An entry written before any ceiling was determined — the evaluator-fault
deferral, the absent-evaluator cancellation, both workspace-resolution
outcomes of `AC-OFFICE-BUDGET-001.13`, the stale-deferral cancellation, the
failed-project-lookup deferral (`AC-OFFICE-BUDGET-006.3`) and a deferral failed
at `MaxRetryCount` under `AC-OFFICE-BUDGET-006.4`, and both cancellations of
`AC-OFFICE-BUDGET-006.7` —
shall instead state explicitly that no ceiling was determined, and shall not
name a policy. The deferral an unevaluated policy raises
(`AC-OFFICE-BUDGET-006.1`) is the single exception, and so is its failure at
`MaxRetryCount`: no ceiling was determined in either, but the policy that could
not be evaluated is known and shall be named, because it is the only pointer an
operator has to the row to inspect.
- **AC-OFFICE-BUDGET-005.6:** When the same run is deferred more than once —
whether by repeated evaluator faults, by repeated workspace-lookup errors
(`AC-OFFICE-BUDGET-001.13`), or by the faults `AC-OFFICE-BUDGET-006.1` and
`AC-OFFICE-BUDGET-006.3` raise — the system shall record one activity entry per
deferral attempt, each naming the attempt number and which cause produced it,
and shall not coalesce them into a single entry. This rule covers every
deferral this capability schedules, so no deferral cause is left to a builder's
choice between one entry per attempt and one per run.
- **AC-OFFICE-BUDGET-005.7:** A run blocked by `AC-OFFICE-BUDGET-004.3` whose
priced spend did not reach the applicable limit shall carry the
`runs.outcome` value `budget_unmeasurable`, reserved for a block caused by
unmeasurable spend rather than by a limit being reached, and shall not carry
`budget_blocked`.
Adding that value extends the Office run-outcome vocabulary owned by
[task-delivery-ledger](../../task-delivery-ledger/spec.md), whose enumeration
shall be updated in the same change rather than gaining an undeclared value.
Updating the enumeration alone is not sufficient: that document also states,
unqualified, that a run blocked by the pre-execution budget check finishes
with `budget_blocked`, both as an acceptance statement for the Office run
outcome and as a row in its mapping table from the `checkBudget` code site.
Both become false for a `budget_unmeasurable` block, and both remain live
canon. Every statement in that document that maps a pre-execution budget block
to `budget_blocked` shall be narrowed to the limit-reached case in the same
change, so no reader of the ledger alone concludes that every budget block
carries `budget_blocked`. The same applies to any statement in that document
that fixes the *cardinality* of the enumeration rather than mapping a block to
a value — it states that the writer writes one of five values on the finished
path — which this addition also makes false, and which a change that updated
only the enumeration and the mapping statements would leave stale.
## Out of scope
- **Exactly-once delivery of activity entries and counters.** Every Office
expvar counter is best-effort by construction; a crash between a block and
its counter increment loses the increment and does not reverse the block.
`AC-OFFICE-BUDGET-005.4` requires the counters exist and are labelled, not
that they are transactional with the run's state change.
- **A dashboard, alert, or digest over these counters and entries.** This
document requires the states be individually queryable; presenting them is
governed by [costs.md](costs.md) and the inbox surfaces.
- **Retention or pruning of the activity entries this capability writes.**
- **Renaming or restructuring the existing `budget_blocked` outcome or the
`run_budget_blocked` activity entry.** `AC-OFFICE-BUDGET-005.1` constrains
what they mean; it does not rename them.
@@ -0,0 +1,149 @@
---
status: draft
system: office
created: 2026-09-06
owners:
- kandev
---
# Office: Run Provenance Classification Requirements
## Overview
[Office: Pre-Launch Budget Enforcement](budget-enforcement.md) decides whether a
run launches. Four of its criteria, and the whole of [Built-In Default Spend
Ceiling](budget-default-ceiling.md), turn on whether the run is *attended* or
*unattended*. This document owns that classification: what it reads, what it
returns for every possible input, and the build-time test that stops a new run
reason from silently changing a run's provenance.
It is separated from the admission decision because it is the decision's
**input**, not one of its gates: classification happens once, before any policy
is read, and no gate may revise it. Keeping it here also keeps the admission
document inside its size limit, which three consecutive rounds of edits have
pressed against.
## Terminology
This capability's shared vocabulary, including *run provenance*, *attended run*,
*unattended run* and the polarity warning about `IsPeriodicTasklessWake`, is
defined in the [Office glossary](../glossary.md) under **Budget enforcement**.
## Requirements
### REQ-OFFICE-BUDGET-007: A run's provenance is a total function of its reason
**Intent:** Every criterion that treats attended and unattended runs differently
needs an answer for every run, including a run carrying a reason the build has
never seen. A classifier with a gap would hand those runs to whichever branch the
implementation happened to fall through to, which is how a safety gate acquires
an unexamined default.
The safe default here is the opposite of the one the idle-skip gate uses on the
same column, and that inversion is the single most likely implementation
mistake; it is recorded as a warning in the glossary rather than left to be
rediscovered.
**User story:** As an operator running Office unattended, I want a run's
provenance decided by an explicit list rather than by a fallthrough, so that
adding a wake reason cannot quietly exempt it from the ceiling.
#### Acceptance criteria
- **AC-OFFICE-BUDGET-007.1:** When a run is dequeued for processing, the system
shall classify its provenance as attended or unattended from `runs.reason`,
before evaluating any policy. Classification is a total function of the
reason string: it shall succeed for every value, and no later gate shall
change the provenance it produced.
- **AC-OFFICE-BUDGET-007.2:** The attended allowlist shall be exactly:
`task_assigned`, `task_comment`, `task_review_requested`,
`task_changes_requested`, `task_blockers_resolved`,
`task_children_completed`, `approval_resolved`, `routine_dispatch_event`,
`manual_resume_after_failure`, `task_mentioned`, `task_reopened`,
`task_reopened_via_comment`, `task_unblocked`, `task_ready_to_close`,
`stage_pending`, `stage_changes_requested`, and the legacy literals
`review_started`, `approval_started`, `blockers_resolved`,
`children_completed`. Every other value, **including a value the build does
not recognize**, shall classify as unattended.
- **AC-OFFICE-BUDGET-007.3:** A test shall fail the build when a run-reason
string literal exists in the Office source that the provenance classifier
places in neither the attended allowlist of `AC-OFFICE-BUDGET-007.2` nor the
explicit unattended list of `AC-OFFICE-BUDGET-007.4`. The test shall derive
its inventory by reading the source, not from a list of literals maintained
alongside it, and shall fail on an unclassified literal at build time rather
than on an unrecognized value at run time.
**The inventory shall be derived from an enumerated set of declaration
blocks, and never by matching constant identifiers.** Identifier matching
cannot work here and shall not be reintroduced: a live run reason is declared
today under three unrelated naming conventions — `RunReason*`, `WakeReason*`
and `TaskCommentReason` — so no identifier pattern narrow enough to exclude
non-run-reason constants also covers all three. The enumerated blocks shall
be exactly: (a) the run-reason constant block in
`internal/office/scheduler/run.go`; (b) both constant blocks in
`internal/office/service/run.go`, the `RunReason*` block and the separate
`legacyRunReason*` block; (c) the run-reason constant block in
`internal/office/shared/runreasons.go`; (d) the `WakeReason*` constant block
in `internal/office/routing/types.go`, which declares three of
`AC-OFFICE-BUDGET-007.4`'s six unattended literals under a doc comment
stating that its values must stay in sync with the scheduler constants;
(e) the constant block in `internal/runs/commentkeys` declaring
`TaskCommentReason`, a live run reason declared outside `internal/office`;
(f) the `runReasonTaskAssigned` constant in
`internal/office/onboarding`; and (g) the constant block in
`internal/office/service/failure.go` declaring
`RunReasonManualResumeAfterFailure`. Block (g) is in the same package as
block (b) but a different file, so enumerating a package's run reasons by one
file does not reach it. Each block shall be identified by package and
declaration and never by line number. When an enumerated block cannot be
located, because it was renamed, moved or deleted, the test shall fail rather
than pass on the smaller inventory, so that a refactor cannot silently empty
the net.
**Within an enumerated block every constant is inventoried by default.** A
constant in one of those blocks that is not a run reason shall be excluded
only by being named in an exclusion list carried with the test, which today
shall be exactly `shared.RoutineSourceCron`, `commentkeys.TaskCommentPrefix`,
`commentkeys.EngineDispatchedValue`, `InboxKindAgentRunFailed`,
`InboxKindAgentPausedAfterFails` and `autoPauseReasonPrefix`. The last three
share block (g) with its one run reason; `InboxKindAgentRunFailed` is an inbox
kind whose value reads exactly like a run reason, which is why exclusion is by
name rather than by inferring intent from the value. Inclusion is the default
so that a reason added to an existing block fails the build until somebody
classifies it, which is the purpose of this criterion; exclusion is by name so
that removing a literal from the inventory is a deliberate and reviewable act
rather than a consequence of how it was spelled. A constant declared as an
alias of another enumerated constant contributes no new literal.
**A declaration block outside the enumeration is not covered**, which is the
cost of enumerating rather than matching, and the test shall carry a comment
saying so: a run reason declared in an unlisted block will not be caught, and
extending the enumeration is part of adding such a block to the tree.
`AC-OFFICE-BUDGET-007.2`'s unattended catch-all remains the runtime safe
default for exactly that case.
Membership shall be decided by exact string equality and never by substring,
so that `task_reopened` is not conflated with `task_reopened_via_comment`,
and a literal declared in more than one block shall count once. A literal
appearing in both `AC-OFFICE-BUDGET-007.2`'s allowlist and
`AC-OFFICE-BUDGET-007.4`'s list shall also fail the test, the two being
disjoint by construction. This test exists so that adding a reason cannot
silently change a run's provenance.
- **AC-OFFICE-BUDGET-007.4:** The explicit unattended list
`AC-OFFICE-BUDGET-007.3` tests against shall be exactly: `agent_error`,
`budget_alert`, `heartbeat`, `routine_dispatch`, `routine_dispatch_cron`,
`routine_trigger`. It shall be maintained as an enumeration in its own right
and shall never be computed as the complement of `AC-OFFICE-BUDGET-007.2`'s
allowlist. A derived list would make `AC-OFFICE-BUDGET-007.3`'s test a
tautology that no newly added reason could ever fail, since every literal
would be a member of one list or the other by construction — which would leave
the build-time net this requirement exists to provide with nothing to catch.
This list is a build-time artifact only. It does not narrow
`AC-OFFICE-BUDGET-007.2`'s runtime rule, under which a value in neither list,
including one the build has never seen, still classifies as unattended.
## Out of scope
- **Distinguishing an agent-caused event wake from a human-caused one.** Named
and reasoned about in [budget-enforcement.md](budget-enforcement.md)'s Out of
scope; `AC-OFFICE-BUDGET-007.2`'s allowlist is what that exclusion constrains.
- **Changing `IsPeriodicTasklessWake` or the idle-skip gate.** That classifier
reads the same column with the opposite safe default and is left untouched.
- **A causation identifier on the run row.** Provenance here is derived from
`runs.reason` alone.
@@ -0,0 +1,581 @@
---
status: draft
system: office
requirements:
- REQ-OFFICE-BUDGET-001
- REQ-OFFICE-BUDGET-002
- REQ-OFFICE-BUDGET-003
- REQ-OFFICE-BUDGET-004
- REQ-OFFICE-BUDGET-005
- REQ-OFFICE-BUDGET-006
- REQ-OFFICE-BUDGET-007
created: 2026-09-07
owners:
- kandev
---
# Office: Pre-Launch Budget Enforcement System Design
## Purpose and boundaries
This design replaces the three fail-open paths named in
[budget-enforcement.md](../requirements/budget-enforcement.md) with a five-gate
admission decision that runs inside `SchedulerIntegration.processRun`
(`internal/office/service/scheduler_integration.go`), immediately after task
checkout and before executor resolution. It owns: run-provenance
classification, the gate sequence and its dispositions, per-state activity
entries and counters, measurement-window and pricing-degradation correctness,
and a new durable per-workspace default-ceiling setting. It does not change the
post-event evaluation path (`costs.CostService.EvaluateBudget`,
`costs/budgets.go`), which continues to fire `budget.alert` / `budget.exceeded`
and pause agents on its own schedule, unconstrained by this design.
Adjacent contracts used and not owned:
- `internal/office/service/retry.go` — `MaxRetryCount`, the backoff schedule,
`isRetryStale`/`retryMaxAge`. Reused, not reimplemented.
- `internal/office/service/scheduler_runs.go` — `FinishRun`, `FailRun`,
`transitionRunTerminal`, `releaseTaskCheckoutForRun`.
- `internal/office/service/activity.go` — `LogActivityWithRun`.
- `internal/office/repository/sqlite/costs.go` — cost-event and
budget-policy storage; extended, not replaced.
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `REQ-OFFICE-BUDGET-007` | [Provenance classification](#provenance-classification) |
| `REQ-OFFICE-BUDGET-001` | [The five-gate admission decision](#the-five-gate-admission-decision) |
| `REQ-OFFICE-BUDGET-006` | [Two-phase policy evaluation](#two-phase-policy-evaluation), [Inertness](#inertness) |
| `REQ-OFFICE-BUDGET-002` | [Measurement integrity](#measurement-integrity) |
| `REQ-OFFICE-BUDGET-004` | [Pricing degradation](#pricing-degradation) |
| `REQ-OFFICE-BUDGET-003` | [Built-in default ceiling](#built-in-default-ceiling) |
| `REQ-OFFICE-BUDGET-005` | [Observability: activity entries and counters](#observability-activity-entries-and-counters) |
## Provenance classification
New file `internal/office/shared/runprovenance.go`, beside the existing
`IsPeriodicTasklessWake` this design deliberately does not touch (per
[budget-run-provenance.md](../requirements/budget-run-provenance.md)'s Out of
scope and the glossary's polarity warning):
```go
type RunProvenance int
const (
RunProvenanceUnattended RunProvenance = iota
RunProvenanceAttended
)
func ClassifyRunProvenance(reason string) RunProvenance
```
An unexported `map[string]struct{}` literal holds the 20-literal allowlist of
`AC-OFFICE-BUDGET-007.2` verbatim (16 current + 4 legacy). `processRun` calls
this exactly once, before gate 1, and threads the result through every gate
via a small `admissionCtx` struct (see below) rather than recomputing it —
satisfying `AC-OFFICE-BUDGET-001.1`'s "computed once, never revised".
### Build-time completeness test
`internal/office/shared/runprovenance_completeness_test.go`
(`package shared_test`) implements `AC-OFFICE-BUDGET-007.3` using plain
`go/parser`/`go/ast` per file, never a line-oriented regex — the X2 design
note. This is an implementation-time refinement from the originally-planned
`golang.org/x/tools/go/packages` + `go/types`: that combination is an
unnecessary new direct dependency (currently only transitive in `go.sum`)
and spawns `go list` subprocesses under the hood, which is a source of CI
fragility this test doesn't need to accept. The AC's actual requirements —
never regex/identifier-matching, fail hard on a missing block, an alias
contributes no new literal — hold under the simpler approach without
weakening what the test proves; see below for how alias handling differs.
For each of the seven blocks the test is hard-coded with **(file path
relative to the test file via `runtime.Caller(0)`, anchor constant name)**:
the anchor is one identifier already known to live in that block
(`RunReasonTaskAssigned` for (a) in `scheduler/run.go`,
`RunReasonTaskAssigned` for (b1) in `service/run.go`,
`legacyRunReasonBlockersResolved` for (b2) in the same file,
`RunReasonRoutineDispatch` for (c) in `shared/runreasons.go`,
`WakeReasonHeartbeat` for (d) in `routing/types.go`, `TaskCommentReason` for
(e) in `runs/commentkeys/commentkeys.go`, `runReasonTaskAssigned` for (f) in
`onboarding/service.go`, `RunReasonManualResumeAfterFailure` for (g) in
`service/failure.go`). For each anchor the test parses that one file with
`go/parser` (`parser.ParseFile`, `SkipObjectResolution`), finds the
top-level `*ast.GenDecl` with `Tok == token.CONST` containing a
`*ast.ValueSpec` naming the anchor, and fails the test (not skips) when no
such declaration exists — an enumerated block that was renamed, moved, or
deleted must fail the build rather than silently shrink the inventory.
Blocks (b1) and (b2) both resolve to `service/run.go`; naming the file per
block (rather than per package) is also what disambiguates block (g), which
shares a package with (b) but lives in a different file (`failure.go` vs
`run.go`).
Once a block's `GenDecl` is located, every `ValueSpec` in it whose RHS is a
string `*ast.BasicLit` contributes that literal (via `strconv.Unquote`); a
`ValueSpec` whose RHS is anything else — a `*ast.SelectorExpr` or
`*ast.Ident`, i.e. an alias like `RunReasonHeartbeat =
shared.RunReasonHeartbeat` — is skipped rather than resolved. This is
sufficient, not a weaker substitute for `go/types` resolution: an aliased
constant's underlying literal is itself already covered by scanning its own
enumerated block, so skipping the alias syntactically loses no literal from
the union. Names present in the fixed six-entry exclusion list of
`AC-OFFICE-BUDGET-007.3` are dropped before dedup/membership checks.
The test asserts, over the union of all seven blocks minus exclusions:
every resolved string is a member of exactly one of two Go string sets
declared directly in the test file — `attendedForTest` (the 20 literals of
`AC-OFFICE-BUDGET-007.2`, kept textually identical to
`shared.attendedRunReasons`, not derived from it, so the assertion is not
checking the production map against itself) and `unattendedForTest` (the 6
literals of `AC-OFFICE-BUDGET-007.4`, maintained as its own literal slice —
never `allReasons - attendedForTest`, which is what makes the test capable of
failing at all). A literal in both, or in neither, fails with the offending
block and literal named in the message.
## The five-gate admission decision
New file `internal/office/service/budget_admission.go`. `processRun` calls
one entry point immediately after `checkoutTask` succeeds, replacing today's
`checkBudget`:
```go
// admitRun runs AC-OFFICE-BUDGET-001.14's five gates in order and returns
// true only when the run should launch. False means admitRun has already
// driven the run to its terminal, retry, or cancelled disposition.
func (si *SchedulerIntegration) admitRun(ctx context.Context, run *models.Run, taskID string) bool
```
`admitRun` builds one `admissionCtx` carrying: the provenance
(`shared.ClassifyRunProvenance(run.Reason)`, computed once), the captured
evaluation instant (`time.Now().UTC()`, captured once — `AC-OFFICE-BUDGET-001.9`'s
"one captured evaluation instant"), and threads it through gates 1-5. Each
gate returns a small `(admit bool, terminal bool)` — `terminal=false` with
`admit=false` means "deferred; caller must return", so a single `if !gate() {
return false }` chain at the call site reproduces `AC-OFFICE-BUDGET-001.14`'s
"first gate that yields a non-launch decision, no later gate evaluated"
structurally, without a shared mutable "have we decided" flag that a future
edit could reorder around.
1. **Workspace resolution** (`gateWorkspace`). Reuses the *existing*
`GetAgentFromConfig` call already made earlier in `processRun` (per
`AC-OFFICE-BUDGET-001.14`'s "constrains the disposition of the workspace
resolution wherever it already occurs rather than requiring a second
one") — `admitRun` receives the already-resolved `*models.AgentInstance`
from its caller instead of re-fetching it. Per the **W2 human
disposition**, `GetAgentFromConfig`'s error contract is not reshaped: an
error from this call (already handled by `processRun` before `admitRun`
is even reached — see [Control flow](#control-flow-inside-processrun))
defers under the same terms as gate 3. `admitRun` itself only sees the
success case and applies `AC-OFFICE-BUDGET-001.13`'s empty-workspace
branch: `agent.WorkspaceID == ""` cancels (not deferred), writing the
`run_budget_workspace_unresolvable` activity entry.
2. **Evaluator presence** (`gateEvaluatorPresence`). `si.svc.budgetChecker ==
nil`: unattended cancels
(`run_budget_no_evaluator`), attended launches (falls through).
3. **Evaluator invocation** (`gateEvaluatorInvocation`). Calls the evaluator
once via the new richer method (below). A non-nil error is an evaluator
fault: `admitBudgetDeferral` (shared with gates 4/5's fault paths, see
below) defers under `AC-OFFICE-BUDGET-001.3`/`.16`, or fails at
`MaxRetryCount` under `AC-OFFICE-BUDGET-001.4`, tagged
`budgetDeferralCauseEvaluatorFault`.
4. **Applicable policies** (`gateAppliedPolicies`). Resolves the run's
project id per `AC-OFFICE-BUDGET-006.7` (see
[Project resolution](#project-resolution)) then delegates the full
evaluate-then-select to `costs.CostService.EvaluatePreLaunch` (see
[Two-phase policy evaluation](#two-phase-policy-evaluation)).
5. **Built-in default** (`gateBuiltInDefault`). Only reached for an
unattended run whose gate 4 result says no workspace-scoped
blocking-capable `daily` policy was evaluated (superseding it per
`AC-OFFICE-BUDGET-003.4`). Evaluated by the same
`costs.CostService.EvaluateDefaultCeiling` call gate 4 already used to
decide supersession — see [Built-in default ceiling](#built-in-default-ceiling).
Steps 3-5 share one disposition helper,
`(si *SchedulerIntegration) admitBudgetDeferral(ctx, run, cause
budgetDeferralCause) bool`, which increments `run.RetryCount` through the
*existing* `s.scheduleRetry`/`isRetryStale` machinery (so
`AC-OFFICE-BUDGET-001.16`'s "same `runs.retry_count`" and "no sooner than the
first backoff delay" hold for free) but, unlike `HandleRunFailure`, never
calls `escalateFailure`. See [MaxRetryCount without
escalation](#maxretrycount-without-escalation) for why.
### Control flow inside `processRun`
```text
checkoutTask succeeds
-> admitRun(ctx, run, taskID, agent) // replaces checkBudget
gate1 workspace (reuses already-fetched agent)
gate2 evaluator presence
gate3 evaluator invocation
gate4 applicable policies (resolves project id first, AC-006.7)
gate5 built-in default
-> (unchanged) resolveExecutorForRun, prepareAndLaunch
```
`GetAgentFromConfig`'s pre-existing error branch in `processRun` (today:
`HandleRunFailure`) is left as-is for the **non-budget** failure it already
handles (agent truly not found); `AC-OFFICE-BUDGET-001.13`'s deferred-vs-cancel
split for a workspace-lookup **error** specifically is therefore also
satisfied by that existing branch, because `GetAgentFromConfig` returning an
error already routes through `HandleRunFailure` → retry → escalate, which
*is* the "same terms as an evaluator fault" `AC-OFFICE-BUDGET-001.13`
requires — except escalation: `HandleRunFailure`'s existing
`escalateFailure` call queues a CEO run, which
[MaxRetryCount without escalation](#maxretrycount-without-escalation)
requires this capability *not* do for a budget-caused permanent failure.
Because a workspace-lookup error is indistinguishable, at this call site,
from every other reason `GetAgentFromConfig` can fail (the W2 disposition:
"do not reshape `GetAgentFromConfig`'s error contract"), this design accepts
that a workspace lookup failing at `MaxRetryCount` escalates through the
pre-existing generic path rather than the budget-specific
non-escalating one — an intentional, narrow exception to
`AC-OFFICE-BUDGET-001.17`'s "no path" language, justified by W2's own text
("do not reshape... here") and recorded so a later reviewer does not
"fix" it by widening `GetAgentFromConfig`'s contract mid-capability.
### Project resolution
`AC-OFFICE-BUDGET-006.7` needs four outcomes `extractProjectID` cannot
produce (it collapses all four to `""`). New function in
`budget_admission.go`:
```go
type projectResolution int
const (
projectResolutionNone projectResolution = iota // (a) no fault, no project
projectResolutionFound
projectResolutionLookupError // (b) defer, AC-006.3
projectResolutionUnparseable // (c) cancel
projectResolutionTaskNotFound // (d) cancel
)
func (si *SchedulerIntegration) resolveRunProject(ctx context.Context, payload string) (projectID string, res projectResolution)
```
Parses `payload` with `json.Unmarshal` directly (not `ParseRunPayload`, which
swallows unmarshal errors — see budget-admission-integrity.md pinned
evidence) into a small local struct with a `TaskID` field. A parse error is
outcome (c). An empty/absent `task_id` is outcome (a). Otherwise calls
`si.svc.repo.GetTaskBasicInfo`: an error is (b); `info == nil` is (d);
`info.ProjectID` (possibly `""`, still (a)/(found)) otherwise.
## Two-phase policy evaluation
`costs.CostService` gains one new exported method,
`EvaluatePreLaunch(ctx, workspaceID, agentInstanceID, projectID string, hasProject
bool, at time.Time) (PreLaunchResult, error)`, in a new file
`internal/office/costs/prelaunch.go`. It does **not** call the existing
`CheckBudget`/`evaluatePolicy` (those remain the post-event path's, unchanged,
per `AC-OFFICE-BUDGET-006.2`). It:
1. Lists policies for the workspace, filters to applicable ones per
`AC-OFFICE-BUDGET-001.15` (workspace-scoped always applies; agent-scoped
only when `scope_id == agentInstanceID`; project-scoped only when
`hasProject && scope_id == projectID` — the caller's `hasProject` flag,
from `resolveRunProject`, is what keeps a genuinely-project-less run from
ever matching a project policy, distinct from a resolution failure that
never reaches this call at all).
2. For each applicable policy, validates it: period recognized (`daily`,
`monthly`, `yearly`, `total`), `limit_subcents > 0`, `action_on_exceed`
recognized, and (for `agent`/`project` scope) non-empty `scope_id`. A
malformed policy is **skipped** — recorded via the caller's
per-policy-per-day-deduped activity entry (see
[Observability](#observability-activity-entries-and-counters)) — and
excluded from both ordering and default-supersession. This is
`AC-OFFICE-BUDGET-002.5`/`.11`/`.14`; it is explicitly not an "unevaluated
policy".
3. For each surviving (non-skipped) policy, computes priced spend and the
pricing-degradation determination over the *same* scope-selected event set
(`AC-OFFICE-BUDGET-002.15` — see [Measurement
integrity](#measurement-integrity)) for its own period window ending at
`at`. A query error here makes the **whole call** return a non-nil error —
this is what makes `AC-OFFICE-BUDGET-006.1` (an unevaluated policy faults
the run, not a partial admission) true by construction rather than by a
caller remembering to check a length mismatch: there is no code path that
returns a partial `[]PreLaunchPolicyResult` and `err == nil`.
4. Orders the surviving policies by `(created_at ASC, id ASC)` and, in that
order, finds the first whose limit test (`spend >= limit`, action ∈
{`pause_agent`,`block_new_tasks`}) or degradation test (unattended,
`2*spend >= limit`, degraded) fires — but **every** surviving policy's
both tests are computed up front (step 3), so "first" is a selection over
an already-fully-evaluated slice, never a short-circuiting loop.
5. Returns `PreLaunchResult{Decision, Policies []PreLaunchPolicyResult,
WorkspaceDailyBlockingSuperseded bool}` — the last field tells
`gateBuiltInDefault` whether a workspace-scoped, non-skipped, blocking-capable
(`pause_agent`/`block_new_tasks`) `daily` policy existed among the
surviving set, independent of whether it fired
(`AC-OFFICE-BUDGET-003.4` supersedes by existing, not by blocking).
`PreLaunchResult` never triggers `budget.alert`/`budget.exceeded` or an agent
pause — it has no side effects at all, which is what makes
`AC-OFFICE-BUDGET-006.2` (inertness) hold structurally: the method's only
outputs are its two return values.
### Inertness
`EvaluatePreLaunch` and every function it calls are pure reads:
`ListBudgetPolicies`, the two new spend-selection queries below, and
(read-only) `GetWorkspaceBudgetDefault`. None of them writes
`office_activity_log`, flips `agent_profiles.status`, or calls
`UpdateAgentStatusFields`. `pauseAgentForBudget` and `logBudgetAlert`/
`logBudgetExceeded` (existing `costs/budgets.go`) are not imported by
`prelaunch.go`. Activity-entry writing for the *new* budget states happens
one layer up, in `budget_admission.go`, after `EvaluatePreLaunch` returns —
so a policy that decided the run's fate and a policy that merely degraded
both get their entries from the caller, never from the evaluator itself.
## Measurement integrity
### Period fix
`costs/budgets.go`'s `periodCutoff` is replaced by a function on the new
`prelaunch.go` (used by both the pre-launch path and, unchanged in
signature, still callable from the existing post-event path if a later
change wants it — not required here):
```go
func windowStart(period models.BudgetPeriod, at time.Time) (start time.Time, ok bool)
```
`daily` → most recent UTC midnight ≤ `at`; `monthly` → existing behavior;
`yearly` → 1 Jan UTC of `at`'s year; `total` → `ok=true`,
zero `time.Time` (unbounded below, `AC-OFFICE-BUDGET-002.8` — selected by
name, not by falling through). An unrecognized period returns `ok=false`,
which callers treat as "skip this policy" (`AC-OFFICE-BUDGET-002.5`), never
as lifetime.
`models.BudgetPeriod` gains `BudgetPeriodTotal = "total"` in
`internal/office/models/enums.go`, added to `Valid()`. `costs/handler.go`'s
two existing `period.Valid()` checks (create/update) need no change — they
already delegate to the enum.
### Scope-selection queries (`AC-OFFICE-BUDGET-002.15`)
Two new repository methods in `costs.go`, used by **both** the priced-spend
sum and the degradation check (same `WHERE`, different `SELECT`), and by
neither `SumCostsSince` nor `GetCostForProjectSince` — the **W4 human
disposition** explicitly forbids reuse:
```go
// SpendWindow reports priced spend and whether the window contains any
// unpriced event, for one scope, in one query round-trip.
type SpendWindow struct {
PricedSubcents int64
Degraded bool
}
func (r *Repository) SpendWindowForWorkspace(ctx, workspaceID string, start time.Time, hasStart bool, before time.Time) (SpendWindow, error)
func (r *Repository) SpendWindowForAgent(ctx, agentInstanceID string, start time.Time, hasStart bool, before time.Time) (SpendWindow, error)
func (r *Repository) SpendWindowForProject(ctx, projectID string, start time.Time, hasStart bool, before time.Time) (SpendWindow, error)
```
Workspace scope joins `office_cost_events e JOIN agent_profiles a ON
a.id = e.agent_profile_id WHERE a.workspace_id = ?` — never `tasks`, closing
the 138-orphan / 973.76 USD gap `SumCostsSince`'s inner join produces (W4
pinned evidence). Agent scope filters `e.agent_profile_id = ?` directly
(already correct in `GetCostForAgentSince`, but not reused, per W4). Project
scope filters `e.project_id = ?` directly — the column already exists on
`office_cost_events` (`base.go:281`), so unlike the legacy
`GetCostForProject`'s live-task-project join, no query against `tasks` is
needed at all, and reparenting a task cannot move historical spend between
ceilings (`AC-OFFICE-BUDGET-002.15`'s "recorded on the cost event itself...
not... the current project of the event's task"). `hasStart=false` (the
`total` period) omits the lower bound. Every query also filters `e.occurred_at
< ?` (`before`, the captured evaluation instant) — the half-open
`[cutoff, now)` window of `AC-OFFICE-BUDGET-002.10`, closing the
clock-skew/back-dated-write gap. `Degraded` is `COUNT(*) FILTER (WHERE
e.cost_source = 'unpriced') > 0` (SQLite: `SUM(CASE WHEN cost_source =
'unpriced' THEN 1 ELSE 0 END) > 0`), never reading `estimated`.
## Pricing degradation
`gate4`/`gate5`'s per-policy test, applied identically to policies and the
default (`AC-OFFICE-BUDGET-003.11`):
```go
func degradationBlocks(degraded bool, pricedSubcents, limitSubcents int64, provenance shared.RunProvenance) bool {
return degraded && provenance == shared.RunProvenanceUnattended && 2*pricedSubcents >= limitSubcents
}
```
The `2*x >= limit` form is `AC-OFFICE-BUDGET-004.3`'s exact-50%-without-
truncation requirement. `degradationBlocks` overrides `notify_only` (it is
called regardless of action, per `AC-OFFICE-BUDGET-004.3`'s "applies whatever
the policy's action"). When it fires and the plain limit test
(`AC-OFFICE-BUDGET-001.7`) did **not** also fire, the run's outcome is
`RunOutcomeBudgetUnmeasurable` (new constant, `"budget_unmeasurable"`,
`internal/office/service/run.go`) rather than `RunOutcomeBudgetBlocked` —
`AC-OFFICE-BUDGET-005.7`. When both fire, outcome stays `budget_blocked` and
the activity entry alone carries the degradation flag
(`AC-OFFICE-BUDGET-004.6`).
## Built-in default ceiling
New table, added to `createCostTables()` (`base.go`) beside
`office_budget_policies` — a genuinely new table, not a column on an existing
one, because `AC-OFFICE-BUDGET-003.7` requires the setting be addressed by a
stable identifier distinct from any `office_budget_policies` row and never
appear in that table's list results:
```sql
CREATE TABLE IF NOT EXISTS office_budget_default_settings (
workspace_id TEXT PRIMARY KEY,
limit_subcents INTEGER NOT NULL,
updated_at TIMESTAMP NOT NULL
);
```
No migration needed — a brand-new table's `CREATE TABLE IF NOT EXISTS` is
idempotent on both fresh and existing databases (backend `CLAUDE.md`'s
migration rule applies to adding a *column* to an *existing* table, not to a
new table). `costs.go` gains `GetWorkspaceBudgetDefault(ctx, workspaceID)
(int64, error)` (returns `DefaultCeilingSubcents = 500_000` when no row
exists — `AC-OFFICE-BUDGET-003.9`, never an error for "absent") and
`SetWorkspaceBudgetDefault(ctx, workspaceID string, limitSubcents int64)
error` (`INSERT ... ON CONFLICT(workspace_id) DO UPDATE SET
limit_subcents = excluded.limit_subcents, updated_at = excluded.updated_at`
— single-statement last-write-wins, `AC-OFFICE-BUDGET-003.10`, no
read-modify-write race). `CostService` exposes both; `Handler` adds two
routes on the existing budget route group:
```text
GET /workspaces/:wsId/budgets/default -> {"limit_subcents": N}
PUT /workspaces/:wsId/budgets/default -> validates > 0 (else 400, AC-003.8), writes, echoes
```
`gateBuiltInDefault` calls `EvaluateDefaultCeiling(ctx, workspaceID, at
time.Time) (PreLaunchPolicyResult, error)` (same file, same shape as a
single-policy `EvaluatePreLaunch` result, `PolicyID=""`,
`IsDefault=true`), which reads the effective limit, then evaluates it exactly
like a `daily` + `block_new_tasks` policy using
`SpendWindowForWorkspace` — the same query gate 4's workspace-scoped
policies use, so a policy and the default cannot disagree about which events
count in the same window (`AC-OFFICE-BUDGET-001.9`'s "same captured
instant" applies transitively because both gates share `admissionCtx.at`).
## MaxRetryCount without escalation
`AC-OFFICE-BUDGET-001.17` forbids a budget-caused permanent failure from
queuing any new run, "in particular... an escalation run for another agent".
The existing `HandleRunFailure` → `escalateFailure` path queues exactly that
(`queueCEOAgentError`). `admitBudgetDeferral`'s terminal branch therefore
does **not** call `s.escalateFailure`; it calls a new
`(s *Service) failRunNoEscalation(ctx, run *models.Run, cause
budgetDeferralCause) error` (`retry.go` sibling in `budget_admission.go`)
that performs exactly `escalateFailure`'s non-escalating half: `s.FailRun`
plus one `LogActivityWithRun` naming the cause
(`AC-OFFICE-BUDGET-006.4`/`.5`) — no `GetAgentFromConfig` re-fetch for
escalation purposes, no `queueCEOAgentError` call. This is applied uniformly
to all four budget-deferral causes reaching `MaxRetryCount` — the evaluator
fault itself (`AC-OFFICE-BUDGET-001.4`) and the three `AC-OFFICE-BUDGET-006.4`
causes (workspace-lookup error, unevaluated policy, failed project lookup) —
because `AC-OFFICE-BUDGET-006.4` states they "defer... under
`AC-OFFICE-BUDGET-001.3`'s terms", and `AC-OFFICE-BUDGET-001.4` is the
`MaxRetryCount` disposition `AC-OFFICE-BUDGET-001.3` names; treating the
escalation exclusion as applying only to the literally-numbered `.4` while
letting the other three self-escalate a CEO agent would silently reopen the
launch-on-persistent-fault gap this capability exists to close. Documented
here as the resolving reading of an otherwise-textually-narrow cross-reference,
per Build's instruction to record a documented assumption rather than route
back to Spec for a wording gap.
## Observability: activity entries and counters
Every new state writes an `office_activity_log` row via
`LogActivityWithRun` with a distinct `Action` value — `action` is the
existing queryable, un-parsed column
`AC-OFFICE-BUDGET-005.3`/`AC-OFFICE-BUDGET-006.5` require:
| State | `action` | Names policy? | Counter |
| --- | --- | --- | --- |
| Evaluator fault, deferred | `run_budget_evaluator_fault_deferred` | no | `office_budget_deferred_evaluator_fault_total{provenance}` |
| Evaluator fault, failed at max retry | `run_budget_evaluator_fault_failed` | no | `office_budget_failed_evaluator_fault_total{provenance}` |
| No evaluator wired (unattended) | `run_budget_no_evaluator` | no | `office_budget_blocked_no_evaluator_total{provenance}` |
| Workspace lookup errored, deferred | `run_budget_workspace_lookup_deferred` | no | `office_budget_deferred_workspace_lookup_total{provenance}` |
| Workspace lookup failed at max retry | `run_budget_workspace_lookup_failed` | no | `office_budget_failed_workspace_lookup_total{provenance}` |
| Workspace unresolvable, cancelled | `run_budget_workspace_unresolvable` | no | `office_budget_cancelled_no_workspace_total{provenance}` |
| Stale deferral, cancelled | `run_budget_deferral_stale_cancelled` | no | `office_budget_cancelled_stale_total{provenance}` |
| Unevaluated policy, deferred | `run_budget_unevaluated_policy_deferred` | **yes** | `office_budget_deferred_unevaluated_policy_total{provenance}` |
| Unevaluated policy failed at max retry | `run_budget_unevaluated_policy_failed` | **yes** | `office_budget_failed_unevaluated_policy_total{provenance}` |
| Project lookup errored, deferred | `run_budget_project_lookup_deferred` | no | `office_budget_deferred_project_lookup_total{provenance}` |
| Project lookup failed at max retry | `run_budget_project_lookup_failed` | no | `office_budget_failed_project_lookup_total{provenance}` |
| Payload unparseable, cancelled | `run_budget_payload_unparseable` | no | `office_budget_cancelled_unparseable_payload_total{provenance}` |
| Task not found, cancelled | `run_budget_task_not_found` | no | `office_budget_cancelled_task_not_found_total{provenance}` |
| Limit reached, blocked | `run_budget_blocked` (existing) | yes/default | `office_budget_blocked_limit_total{provenance}` |
| Pricing-degraded, blocked | `run_budget_pricing_degraded_blocked` | yes/default | `office_budget_blocked_pricing_degraded_total{provenance}` |
| Pricing-degraded, admitted | `run_budget_pricing_degraded_admitted` | yes/default | `office_budget_admitted_pricing_degraded_total{provenance}`, incremented once per **run** admitted (not per entry), only when the run's final disposition is launch |
| Admitted against built-in default | (no entry — launch is silent by design) | — | `office_budget_admitted_default_total{provenance}` |
Counters live in a new `internal/office/service/budget_metrics_vars.go`,
following the `expvar.NewMap` + label convention of
`internal/office/scheduler/metrics_vars.go` cited in
`stall-visibility.md`. Every deferral counter increments once per deferral
**attempt** (`AC-OFFICE-BUDGET-005.4`/`.6`); every other counter increments
once per run. `AC-OFFICE-BUDGET-002.13`/`.4.8`'s per-policy-per-UTC-day
activity-entry dedup is an in-memory `map[string]civilDay` guarded by a
mutex on `CostService` (best-effort across restarts and concurrent
evaluations, per the criteria's own "best-effort under concurrency" clause —
no new table for a dedup key that is allowed to duplicate).
Every entry that fires before any ceiling was determined states so
explicitly in its JSON `Details` (`"ceiling_determined": false`) and never
sets a `policy_id` field, except the two unevaluated-policy states, which
name the policy id that could not be evaluated (`AC-OFFICE-BUDGET-005.5`).
Every deferral entry's `Details` also carries `"attempt": run.RetryCount + 1`
(`AC-OFFICE-BUDGET-005.6`).
## `runs.outcome` vocabulary change
`RunOutcomeBudgetUnmeasurable = "budget_unmeasurable"` added to
`internal/office/service/run.go`'s outcome block. Companion edit to
[task-delivery-ledger/spec.md](../../task-delivery-ledger/spec.md), same
change: the `runs.outcome` column doc's five-value list becomes six and its
"one of the five values... it never writes ''" sentence becomes six; the
`office/service/scheduler_integration.go:829` mapping-table row is narrowed
to "pre-execution budget block, limit reached" with a new row for the
pricing-degraded-unmeasurable block; the corresponding GIVEN/WHEN/THEN
scenario is narrowed and a new scenario added for the unmeasurable case —
per `AC-OFFICE-BUDGET-005.7`'s explicit requirement that both the
enumeration and every statement fixing its cardinality change together.
## Frontend
`apps/web/app/office/workspace/costs/create-budget-form.tsx`'s period
`Select` gains `daily` and `yearly` options (alongside the existing
`monthly`/`total`) so the offered set matches `BudgetPeriod.Valid()` exactly
— `AC-OFFICE-BUDGET-002.9`. A new Go test,
`internal/office/costs/period_parity_test.go`, implements
`AC-OFFICE-BUDGET-002.12`: it reads `enums.go`'s `BudgetPeriod` `Valid()`
switch cases via `go/ast` (same technique as the provenance completeness
test, smaller in scope — one file, one function) for the declared set, and
reads `create-budget-form.tsx`'s literal `SelectItem value="..."` list under
the period `FormField` via a regex scoped to that file for the offered set
(TypeScript, not Go — `go/ast` cannot parse it), and fails on any
asymmetric difference. This lives in the **Go** suite per
`AC-OFFICE-BUDGET-002.12`'s explicit requirement ("the check shall live in
the backend Go test suite").
`budgets-tab.tsx` gains a `DefaultCeilingCard` (new file,
`default-ceiling-card.tsx`) above the policy list: reads
`GET .../budgets/default`, renders the effective limit in dollars with an
inline edit control that `PUT`s the new value — `AC-OFFICE-BUDGET-003.5`'s
"visible... without inspecting the database". It is visually distinct from a
`BudgetPolicyCard` (no scope/action/period controls — the default is always
workspace-scoped, always `daily`, always blocking) and carries copy stating
it applies to unattended runs only, so an operator does not mistake it for a
policy that also gates attended work.
## Security
No new trust boundary. The two new routes reuse the existing
`officeWorkspaceScopeMiddleware` resolution already applied to
`/workspaces/:wsId/budgets*` (same route group, `registerBudgetRoutes`).
## Related decisions
None new. This design implements the human dispositions already recorded in
the task plan (W2, W3, W4, X2, Y1) rather than introducing its own
architectural choices beyond where noted above (the new table, and the
MaxRetryCount-without-escalation scope reading).
+9 -10
View File
@@ -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**