Enforce proxy budgets

[mostlydev]

This pull request introduces a comprehensive agent-level budget policy enforcement system, allowing administrators to set and enforce usage budgets for agents. It adds support for configuring budget policies via agent metadata and governance directories, normalizes and enforces these policies at runtime, and provides detailed error responses when limits are exceeded. The changes also include new tests and configuration options to support this feature.

Budget policy enforcement and configuration:

• Added a new BudgetPolicy type to agentctx, and updated agent context loading to support parsing budget policies from agent metadata (metadata.json). This enables agents to have budget constraints like max cost, max requests, time window, and enforcement behavior. [1] [2] [3] [4]
• Introduced the GovernanceDir configuration and environment variable (CLAW_GOVERNANCE_DIR), allowing budget policies to be overridden or enforced centrally via governance files. The server and handler setup code was updated to accept and wire this new directory. [1] [2] [3] [4] [5] [6] [7]

Budget checking and enforcement logic:

• Implemented a new internal/proxy/budget.go module that normalizes, merges, and enforces budget policies, checking recent usage against limits and returning appropriate HTTP errors or soft alerts. This includes logic for loading policy overrides, handling enforcement behaviors, and integrating with session history for usage tracking.
• Integrated budget enforcement into both OpenAI and Anthropic proxy endpoints, so that requests are rejected early with a structured error response if the agent's budget is exceeded or rate-limited. [1] [2]

Testing and validation:

• Added tests to verify correct parsing of budget policies from agent metadata, and to ensure the new configuration environment variable is honored. [1] [2]

Internal API and code improvements:

• Refactored the handler and related functions to accept and propagate the new governance directory and budget policy options, and improved cost recording logic to support budget enforcement. [1] [2] [3] [4] [5] [6]

These changes lay the foundation for robust, configurable budget enforcement at the agent level, supporting both soft and hard enforcement modes and centralized governance.