Efficiency Engine — token budgets and loops

Track tokens, predict waste, block loops with efficiency_enforce profiles.

What you will learn

Configure .ags/efficiency.yml
efficiency_track/predict
efficiency_enforce

Prerequisites

Surface

MCP	efficiency_get · efficiency_validate · efficiency_enforce · efficiency_plan · efficiency_track · efficiency_predict · efficiency_compress · efficiency_hotspots · efficiency_analytics · efficiency_forecast · efficiency_orchestrate
Config	.ags/efficiency.yml

What this feature does

Efficiency Engine budgets tokens per operation, detects repeated fix loops, and can compress context. Profiles: free | personal | enterprise via entitlements.

Configuration

Wire these surfaces first: .ags/efficiency.yml.. Treat them as the contract agents must not invent around.

.ags/efficiency.yml yaml

schemaVersion: 1
enabled: true
profile: personal
loopPrevention: true
loopRepeatThreshold: 3
loopWindowMs: 900000
organicGuardrails: true
contextCompression: true
trackHotspots: true
budgets:
  - id: default-operation
    maxTokens: 40000
    wasteWarnRatio: 0.35
  - id: commit-checkpoint
    maxTokens: 12000
    wasteWarnRatio: 0.4
graphArtifact: docs/efficiency-map/latest.json

How to call it

Call these MCP tools through your AGS / tower-gov host — efficiency_get, efficiency_validate, efficiency_enforce, efficiency_plan, efficiency_track, efficiency_predict, efficiency_compress, efficiency_hotspots, efficiency_analytics, efficiency_forecast, efficiency_orchestrate.. Prefer scan/get before validate/diff, and enforce only when the change set is ready.

efficiency_get
efficiency_track during tools
efficiency_predict before bursts
efficiency_enforce

MCP: efficiency_enforce json

{ "budgetId": "default-operation" }

What success looks like

Under budget

No loop hold

efficiency_enforce ok

Common failure modes

Loop threshold exceeded

Entitlement lacks token_efficiency_full

Track without enforce on hot sessions