gmackie/ForgeGraph

Fork 0

feat(budget): Worker runtime budgets — CPU measurement, deploy gate, and fleet analytics #402

Merged

gmackie merged 31 commits from feat/worker-runtime-budgets into main

2026-08-23 21:34:04 +00:00

gmackie commented

2026-08-23 20:23:21 +00:00

Owner

What

Worker runtime budgets: measure and enforce CPU time for Cloudflare Workers, and report compliance across the fleet.

@forgegraph/worker-budget — wraps a Worker's entrypoint (including an OpenNext adapter) to measure CPU time per request, clamp declared cpu_ms, and emit violations as structured telemetry. Cron and marker support included.
Deploy gate — a Worker declaring a limit above its plan, or an agent without the budget capability, is refused before upload instead of failing at the edge. Enforcement runs against a pinned, verified worker artifact with a bounded dependency closure.
Fleet analytics — /runtime-budgets dashboard plus forge budget workers cpu, forge budget violations tail, and forge budget summary.
Honest coverage — CPU and violation telemetry are tracked separately; coverage reads "Complete" only when both streams are complete and lossless with no dropped events, and otherwise names which stream is incomplete and how many events were lost.

Verification

go build ./... and go test ./... in agent/ — green.
tsc --noEmit for apps/web — clean.
vitest run in apps/web — 169 files, 1033 passed, 40 skipped.

Rebased onto main at 18b3f957 with no conflicts.

Note for review

TestImmutableWorkerArtifactRunsInstalledWranglerDryRunWithWritableScratch looked for wrangler and zod under apps/web/node_modules, but pnpm keeps workspace dependencies at the workspace root — so it hard-failed in every environment including CI and never actually exercised Wrangler. It now resolves them by walking up from the app directory the way node resolution does, and skips rather than fails a Go-only checkout. The test now genuinely runs the dry-run (~4s).

🤖 Generated with Claude Code

## What Worker runtime budgets: measure and enforce CPU time for Cloudflare Workers, and report compliance across the fleet. - **`@forgegraph/worker-budget`** — wraps a Worker's entrypoint (including an OpenNext adapter) to measure CPU time per request, clamp declared `cpu_ms`, and emit violations as structured telemetry. Cron and marker support included. - **Deploy gate** — a Worker declaring a limit above its plan, or an agent without the budget capability, is refused before upload instead of failing at the edge. Enforcement runs against a pinned, verified worker artifact with a bounded dependency closure. - **Fleet analytics** — `/runtime-budgets` dashboard plus `forge budget workers cpu`, `forge budget violations tail`, and `forge budget summary`. - **Honest coverage** — CPU and violation telemetry are tracked separately; coverage reads "Complete" only when both streams are complete and lossless with no dropped events, and otherwise names which stream is incomplete and how many events were lost. ## Verification - `go build ./...` and `go test ./...` in `agent/` — green. - `tsc --noEmit` for `apps/web` — clean. - `vitest run` in `apps/web` — 169 files, 1033 passed, 40 skipped. Rebased onto `main` at `18b3f957` with no conflicts. ## Note for review `TestImmutableWorkerArtifactRunsInstalledWranglerDryRunWithWritableScratch` looked for wrangler and zod under `apps/web/node_modules`, but pnpm keeps workspace dependencies at the workspace root — so it hard-failed in every environment including CI and never actually exercised Wrangler. It now resolves them by walking up from the app directory the way node resolution does, and skips rather than fails a Go-only checkout. The test now genuinely runs the dry-run (~4s). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gmackie added 31 commits

2026-08-23 20:23:21 +00:00

updates bd9058f091

feat(worker-budget): @forgegraph/worker-budget — budgets, marker, cron, enforce, OpenNext adapter eb66042470

feat(web): adopt worker-budget — wrapper entry, wrangler main flip, dep 1a395ca0f0

- apps/web/worker.mjs wraps the OTel-patched OpenNext output with
  withOpenNextBudget (1s default budget; /api/auth/* + SSE exempt by config)
- envConfig resolves FG_BUDGET_MODE / FG_LANE / FG_DEPLOYMENT_ID per request
- main flipped to worker.mjs in prod + staging wrangler configs
- verified: opennext build, wrangler dry-run bundle, __FG_BUDGET__ marker
  present in final minified output

feat(budget): worker runtime budget policy — deploy gate + cpu_ms clamp (TS side) 0520083d40

Workspace opt-in (workspaces.requireWorkerBudget, migration 0090) makes
worker runtime budgets mandatory for Cloudflare Workers deploys:

- deploy preflight gains runtimeBudgetPolicy / workerRuntimeEvidence /
  isCloudflareWorkerApp inputs; when opted in, deploys missing evidence
  are rejected with distinct actionable errors (upgrade forge CLI when no
  evidence at all; add [forge.budget]; import @forgegraph/worker-budget
  for the __FG_BUDGET__ marker; set [observability] enabled = true).
- POST /api/fg/deploy accepts optional workerRuntimeBudget evidence in
  its body schema and feeds workspace policy + evidence into preflight.
- GET /api/agent/bindings emits limits.cpuMs (apps.cpuMsOverride ??
  1000, migration 0091 adds the override + reason columns) when the
  workspace enforces budgets; absent otherwise.
- packages/api/vitest.unit.config.ts: globalSetup-free config so pure
  unit tests run where the emulate-based setup can't.

fix(budget): constrain cpu override reasons 4e6feae427

feat(budget): report worker runtime evidence from forge CLI 3b1aae4259

fix(budget): enforce policy in pinned worker build 43d1962817

fix(budget): preserve Wrangler environment policy d5d0c4d363

fix(budget): recognize versioned Wrangler commands 4d30da45ee

fix(budget): gate deployments by agent capability 3f220e6e58

chore(budget): restore focused route diff 01a1260cc7

fix(budget): harden worker deployment enforcement 72d1602e2b

fix(budget): handle dotted inherited limits cc4e18a728

fix(budget): pin verified worker artifact 3e858f4541

fix(budget): bound worker artifact closure b98bc20238

fix(budget): include worker dependency closure 89b3bfbf36

fix(budget): include workspace dependency closure 22dc0146d7

feat(budget): add fleet runtime analytics APIs 6c014fe81d

fix(budget): make runtime analytics contract and pagination truthful be26801c8a

fix(budget): harden runtime analytics pagination and scoping 210bb705e3

fix(budget): coordinate runtime analytics across isolates d62e96d743

feat(budget): add runtime analytics CLI commands f79d8d8171

fix(budget): harden violations tail contracts 36bd437461

fix(budget): address remaining T3 CLI findings 7af16eb544

fix(budget): render tail JSON usage failures d56afd6fdf

fix(budget): render tail JSON flag errors 516f327072

feat(budget): add runtime budget observability dashboard 7e9c34c4b0

fix(budget): harden runtime dashboard state 07239f5514

fix(budget): stop claiming complete coverage on partial violation telemetry 6a6042bf19

The worker row reported "Complete" whenever CPU telemetry was complete, so a
snapshot with lossy or dropped violation events still read as full coverage.
Coverage now requires both streams complete and lossless with no dropped
events, and the partial case names which stream is incomplete and how many
events were lost.

test(budget): resolve the real wrangler and zod the way node does e83502ee5d

The dry-run integration test looked for both under apps/web/node_modules, but
pnpm keeps workspace dependencies in the workspace root, so the test hard-failed
everywhere including CI and never exercised a real Wrangler. It now walks up
from the app directory the way node resolution does, and skips — rather than
fails — a Go-only checkout with no JS install.

docs(changelog): record worker runtime budgets

CI / gitleaks (pull_request) Successful in 6s

Details

forgegraph/ci CI passed

CI / ci (pull_request) Successful in 9m12s

Details

e2906d856a

gmackie force-pushed feat/worker-runtime-budgets from e2906d856a

CI / gitleaks (pull_request) Successful in 6s

Details

forgegraph/ci CI passed

CI / ci (pull_request) Successful in 9m12s