API Budgeting and Telemetry

Purpose of This Section

This document defines how API usage is monitored, constrained, and interpreted within the architecture. API consumption is not treated as a billing concern. It is treated as a behavioral signal. Unbounded usage enables silent escalation, runaway research loops, and indirect authority expansion. Accordingly, cost, volume, and frequency are elevated to first-class governance controls — mechanisms that constrain behavior as reliably as network isolation or identity separation, but operating through a different medium.

Cost as a Safety Boundary

Every external API call represents an outward action, a dependency on an external system, and a potential amplification of behavior. A single call is negligible; a pattern of calls reveals whether the assistant is operating within its intended scope or drifting beyond it. Hard financial limits provide something that logic alone cannot: a guaranteed stop condition. Budget exhaustion is not a failure state to be recovered from — it is a controlled halt, a point at which the system ceases external activity until the operator intervenes.

This is the same principle applied throughout the architecture: when the system cannot verify that its actions are appropriate, the correct behavior is to stop.

Hard Spend Caps

All API credentials are configured with hard monthly spending caps enforced by the provider wherever possible. These caps are calibrated to be low enough to bound blast radius in the event of compromise or runaway behavior, and high enough to support normal operation without creating artificial friction during routine work. The calibration is necessarily approximate and is revisited as usage patterns stabilize.

The assistant cannot increase these limits, request higher service tiers, or create replacement keys when caps are reached. Exhaustion results in immediate and total loss of API access until the operator intervenes. This ensures that compromise cannot spiral financially — an attacker who gains access to an API key can cause only bounded damage before the key stops working. It also ensures that runaway behavior self-terminates: a research loop that makes progressively more calls hits a wall regardless of whether the assistant recognizes the loop.

Cost functions here as a physical constraint rather than a guideline. The assistant cannot reason its way past a hard cap, and that imperviousness to persuasion is the property that makes it useful as a safety mechanism.

Usage Tracking and Thresholds

The assistant continuously tracks its own API usage, including requests per unit time, cumulative cost, cost per task or activity, and provider-specific usage patterns. This telemetry is collected locally and does not rely solely on provider dashboards, which may lag or present data in formats that are difficult to act on in real time.

Usage thresholds are defined at three levels. Informational thresholds mark normal expected usage milestones and require no action — they exist to confirm that consumption is tracking within anticipated bounds. Warning thresholds indicate elevated or unusual consumption and prompt the operator to evaluate whether the usage pattern is expected. Critical thresholds signal that the system is approaching hard caps or exhibiting anomalous spikes and carry an expectation of immediate review.

Each threshold crossing generates a notification to the operator containing the current usage state, a summary of recent activity, and the suspected cause of the threshold crossing. Thresholds are static by default and may only be changed by the operator. The assistant cannot adjust its own monitoring sensitivity — doing so would allow it to suppress alerts about its own behavior, which is precisely the kind of closed loop this architecture is designed to prevent.

Research Loop Detection

Advanced assistants are particularly prone to a specific failure mode: iterative research that never converges but continues to consume resources. This manifests as repeated refinement queries, slightly varied searches with diminishing returns, recursive summarization without a decision output, or a pattern of “one more pass” behavior that extends indefinitely. The behavior is often well-intentioned — the assistant is genuinely attempting to improve the quality of its answer — but at the infrastructure level it is indistinguishable from runaway automation.

The system flags potential research loops when it detects high query volume with low artifact output, repeated calls with near-identical prompts, increasing cost without corresponding state change, or iterative patterns that lack a defined stopping condition. Detection does not assume intent. It assumes risk. Whether the assistant is stuck in a loop because the question is genuinely hard or because the research strategy is flawed, the appropriate response is the same: pause and consult the operator.

When a research loop is suspected, the assistant pauses further API calls, produces a summary of progress and findings to date, and prompts the operator to decide whether to continue, redirect the effort, or terminate it. The assistant does not attempt to justify continuation — that judgment belongs to the operator, who has the context to determine whether the marginal value of further research exceeds its cost.

Interpreting Cost, Not Optimizing It

Low cost is not inherently good. High cost is not inherently bad. A complex, well-directed research effort may legitimately consume more resources than routine operations. What matters is cost relative to outcome: whether the expenditure is producing useful results or merely accumulating without convergence.

The assistant treats cost patterns as diagnostic signals that can indicate uncertainty, indecision, over-exploration, tool misuse, or ambiguous objectives. These signals are surfaced explicitly to the operator rather than hidden behind efficiency metrics. When a cost anomaly is detected, it prompts clarifying questions: is this effort worth continuing, what decision is this research meant to support, and what would constitute a reasonable stopping condition. This reframes budgeting as a conversation catalyst — a mechanism that triggers useful dialogue between the operator and the assistant — rather than a pure constraint.

Failure Behavior

When API access is unavailable due to budget exhaustion, provider outage, or credential revocation, the assistant stops external calls immediately, documents the interruption in the memory vault, continues offline reasoning where possible, and waits for explicit human direction. Creative workarounds — attempting undeclared alternative services, caching stale results as current, or deferring requests to retry later without disclosure — are prohibited. The correct response to lost API access is to report it and wait, not to improvise around it.

Documentation and Auditability

All budgeting rules, thresholds, and incidents are documented in the shared memory vault. This includes defined limits and their rationale, any changes to threshold levels, budget exhaustion events, and the operator’s decisions following alerts. The resulting record links cost to intent — it shows not only what the assistant spent, but what it was trying to accomplish when it spent it, and what the operator decided to do about it. This record is invaluable for calibrating future budgets and for post-incident analysis when usage patterns deviate from expectations.

Summary

By treating API budgeting and telemetry as governance primitives rather than accounting tools, the architecture ensures that external behavior is bounded, runaway automation is detectable, cost functions as a reliable stopping mechanism, and the operator retains control over exploration depth. Financial limits serve the same role in this architecture that circuit breakers serve in electrical systems: they interrupt the flow of activity when it exceeds safe parameters, regardless of whether the system itself recognizes the danger.

This document establishes how ongoing API usage is governed. The next section addresses alerts and failure behavior as the system’s response to anomalies detected through these and other monitoring mechanisms.