F35: Agent session spend caps (SDK-level budget enforcement)

[peterkacerik]

Summary

• New SessionBudget class for client-side per-session dollar-denominated budget enforcement
• Bundled static pricing table (50+ models across 7 providers) with synchronous estimateEventCost() function
• Soft warning callbacks at configurable threshold (default 90%), hard limit that blocks further calls
• Sliding-window loop detection for runaway agent prevention
• Enforcement events sent as zero-cost budget_enforcement events for dashboard visibility

Task

Task file: aispendguard-tasks/active/features/F35-agent-session-spend-caps.md

Changes

• src/pricing.ts — NEW: Bundled pricing table ported from app's HARDCODED_PRICES + estimateEventCost() with cache/batch/fast/web-search multipliers
• src/session-budget.ts — NEW: SessionBudget class with check-and-reserve pattern, loop detection, fire-and-forget enforcement events
• src/types.ts — Added re-exports for SessionBudgetConfig, SessionBudgetInfo, LoopDetectionConfig, PriceEntry
• src/index.ts — Added exports for SessionBudget, estimateEventCost, and new types
• tests/pricing.test.mjs — NEW: 16 tests covering known/unknown models, costUsd override, cache/batch/fast multipliers, custom pricing, long-context
• tests/session-budget.test.mjs — NEW: 12 tests covering construction validation, soft/hard limits, loop detection, enforcement event format, reset, concurrency

Testing

• npx tsc --noEmit passes
• Existing tests pass (privacy-guard, circuit-breaker)
• New tests added for: pricing estimation (16 tests), session budget (12 tests)
• All 35 tests pass

Documentation

SDK docs update to be handled separately per task docs section.

[peterkacerik]

Sentinel Code Review — APPROVED

Security Checklist — All Clear

• No injection vulnerabilities — enforcement event tags use hardcoded keys only
• Auth preserved — enforcement events go through existing API key auth pipeline
• Privacy invariant preserved — no prompt/message data stored or transmitted
• Input validated at constructor (maxBudget > 0, softLimitPercent 1-99)
• No hardcoded secrets, no new dependencies
• Concurrency model correct — synchronous check-and-reserve before async gap

Quality Checklist — All Clear

• 28 new tests (16 pricing, 12 session-budget), all passing
• No N+1 queries — pure client-side enforcement
• TypeScript compiles clean
• Fire-and-forget pattern consistent with SDK conventions
• Loop detection sliding window is bounded (no memory leak)
• Boolean guards ensure max 3 enforcement events per session

Regression Check

• No known vulnerability patterns reintroduced (checked all 5 patterns)
• No migration conflicts (no DB changes in this PR)

Documentation

• SDK docs update needed (aispendguard-docs/sdk/) — follow-up task to be created for Veda
• App manual update needed for enforcement badge — follow-up task to be created for Veda

Verdict: APPROVED — proceeding to merge.