budget-monitor

Budget Monitor

Runs at invocation start and is polled mid-session. This skill enforces all budget ceilings. cost-tracker aggregates and reports; budget-monitor blocks.

Parameters (passed by adapter)

• userStoryId — from config or prompt (e.g., "PROJ-142")
• agentFamily — e.g., backend-coding-agent
• accumulatedCost — USD total from cost-tracker for this userStoryId across all sessions

Config Keys

Read from .guardrails-agent.json:

• budgets.maxTokensPerSession (default: 100,000)
• budgets.maxInvocationsPerHour (default: 20)
• budgets.maxCostPerStoryUSD (default: 5.00 USD)
• budgets.circuitBreakerCooldownMins (default: 30)
• audit.db.connectionString — pyodbc connection string for SQL Server dual-write (optional)
• audit.db.schema (default: guardrails) — schema owning RateLog and CircuitBreakerState
• audit.db.tablePrefix (default: "") — optional prefix for table names

Checks

1. Token Budget

Estimate the current session's context size (input tokens + expected output).

• At 80% of maxTokensPerSession: P3 INFO — "Token budget at 80% ([used]/[max]). Consider wrapping up this session."
• At 100% of maxTokensPerSession: P1 BLOCK — "Token budget exhausted. Start a new session to continue."

2. Rate Limit

On session start — record the invocation:

• Always append to .guardrails-rate.json: Format: { "userId": "...", "invocations": [{ "timestamp": "...", "agentFamily": "..." }] }
• DB write: If audit.db.connectionString is set, also INSERT into [{audit.db.schema}].[{audit.db.tablePrefix}RateLog]: (Timestamp=now, UserId=userId, AgentFamily=agentFamily). 3-second timeout. Failure → P2 WARN, non-blocking.

Count invocations in the last 60 minutes:

• DB path: If audit.db.connectionString is set:

  SELECT COUNT(*)
  FROM   [{audit.db.schema}].[{audit.db.tablePrefix}RateLog]
  WHERE  UserId = ?
    AND  Timestamp > DATEADD(hour, -1, GETUTCDATE())
  

  If query fails, fall back to JSON file and emit P2 WARN "DB rate read failed: {error}".

• Fallback / no DB: Read .guardrails-rate.json, count entries in last 60 minutes.

• If count >= maxInvocationsPerHour: P1 BLOCK — "Rate limit reached ([count]/[max] per hour). Retry after [next-available-time]."

3. Circuit Breaker

Read state — on session start:

• DB path: If audit.db.connectionString is set:

  SELECT ConsecutiveFailures, LastFailureTimestamp, Tripped, TripTimestamp
  FROM   [{audit.db.schema}].[{audit.db.tablePrefix}CircuitBreakerState]
  WHERE  AgentFamily = ?
  

  If the row is absent, treat as { consecutiveFailures: 0, tripped: false }. If the query fails, fall back to JSON file and emit P2 WARN.
• Fallback / no DB: Read .guardrails-cb-state.json:

  { "consecutiveFailures": 0, "lastFailureTimestamp": null, "tripped": false, "tripTimestamp": null }
  

On session start — trip check:

• If tripped: true: check if (now - tripTimestamp) > circuitBreakerCooldownMins:
  • If cooldown expired: reset state (see write state below) and proceed.
  • If cooldown active: P1 BLOCK — "Circuit breaker is open after [N] consecutive failures. Retry after [cooldown-expiry-time]. Use /guardrails-reset to clear manually."

Write state (UPSERT):

Always write .guardrails-cb-state.json. Additionally, if audit.db.connectionString is set:

MERGE [{audit.db.schema}].[{audit.db.tablePrefix}CircuitBreakerState] AS target
USING (SELECT ? AS AgentFamily) AS src ON target.AgentFamily = src.AgentFamily
WHEN MATCHED THEN
    UPDATE SET ConsecutiveFailures = ?, LastFailureTimestamp = ?, Tripped = ?, TripTimestamp = ?
WHEN NOT MATCHED THEN
    INSERT (AgentFamily, ConsecutiveFailures, LastFailureTimestamp, Tripped, TripTimestamp)
    VALUES (?, ?, ?, ?, ?);

3-second timeout. Failure → P2 WARN, non-blocking.

Incrementing the counter:

• At session end: read state, check gateResults from audit-trail. If the session ended with a P0 BLOCK or token ceiling BLOCK, increment consecutiveFailures and write updated state to both DB and JSON.
• If consecutiveFailures >= 3: set tripped: true, record tripTimestamp.

Resetting the counter:

• On successful session completion (no BLOCK): reset consecutiveFailures to 0, write both destinations.
• On /guardrails-reset command: DELETE from [{schema}].[{prefix}CircuitBreakerState] WHERE AgentFamily = ? AND delete .guardrails-cb-state.json.
• On cooldown expiry: reset to 0 at next session start, write both destinations.

4. User Story Cost Ceiling

If accumulatedCost is null or absent (first session for this userStoryId): treat as 0 (no prior cost).

Read accumulatedCost parameter (provided by cost-tracker rollup). Compare against maxCostPerStoryUSD:

• At 80%: P3 INFO — "Story [userStoryId] cost at 80% ($[accumulated]/$[max]). Approaching budget ceiling."
• At 100%: P1 BLOCK — "Story [userStoryId] has reached its cost ceiling ($[max]). No further sessions will be started for this story without an admin override."

Hook-Level Rate Logging

The run-guardrails-hook script records rate-limit invocations at the hook layer during the session-start phase:

• Writes to both .guardrails-rate.json and [{schema}].[{prefix}RateLog] (if DB configured)
• Uses CLAUDE_USER_ID (fallback: whoami) and CLAUDE_AGENT_FAMILY from environment variables
• The SessionStart hook fires on startup|resume|clear|compact events, ensuring every session opening is counted

Hook-level rate records complement the skill-layer rate check. The hook ensures a RateLog entry is always created even if the skill layer is bypassed.