# DD-24 — Cost-Aware Agents: Budget as a First-Class Constraint

**Course**: Master Course · **Deep-Dive**: DD-24 (Final) · **Duration**: 50 min · **Level**: Senior engineer · **Status**: Complete
**Pillar**: Deep-Dives

> Pi has no budget enforcement. This deep-dive shows how to add it — turning Pi's personal-scale loop into an enterprise-scale loop that won't burn the company's API budget.

## Artifacts

| # | Artifact | File | Purpose |
| --- | --- | --- | --- |
| 01 | Teaching Document | [01-teaching-document.md](01-teaching-document.md) | ~3,800 words. 9 sub-sections: the multiplier stack (1,000x), the cost iceberg (20% visible), the @token_meter interceptor (throttle/rollback/circuit-break), cost-aware tool selection, HITL at thresholds, circuit breakers for runaway loops, TypeScript cost-aware loop, prompt caching (90% discount), the prime directive + C4 E03 connection. Anti-patterns, key terms, references. |
| 02 | Diagrams | [02-diagrams.md](02-diagrams.md) | 6 Mermaid diagrams: multiplier stack (5 mechanisms), cost iceberg (4 layers), interceptor flow (throttle/rollback/break), HITL thresholds (3 tiers), runaway loop + circuit breaker, Pi vs cost-aware loop comparison. Design-system colors. |
| 03 | Slide Deck | [03-slide-deck.html](03-slide-deck.html) | 10-slide reveal.js deck. Dark theme, accent #5eead4. Multiplier stack, iceberg, interceptor, HITL, caching, tool selection, prime directive, the loop, recap. |
| 04 | Teaching Script | [04-teaching-script.md](04-teaching-script.md) | ~2,800 words, verbatim transcript with [SLIDE N] cues across 10 slides. |
| 05 | Flashcards | [05-flashcards.tsv](05-flashcards.tsv) | 22 cards. Header + 22 Q/A with tags (c1::dd24::recall/application/analysis). |
| 06 | Exam | [06-exam.json](06-exam.json) | 15 questions. Bloom distribution: 3 recall / 6 application / 6 analysis. 70% pass. Rationale per question. |
| 07 | Lab Specification | [07-lab-spec.md](07-lab-spec.md) | TypeScript lab: TokenMeter class, costAwareLoop function, mock provider (normal/storm/expensive/throttle), four demos (normal, retry storm with circuit breaker, budget exceeded with rollback, throttle triggered), re-sent-context visualization. 5 stretch goals. |
| 08 | Module Web Page | [08-module-web-page.html](08-module-web-page.html) | Single-file HTML hub: hero with key metrics, claims, objectives, artifacts, key terms, navigation. |
| -- | Metadata | [module-meta.json](module-meta.json) | Concept-deep-dive shape: claims, objectives, subsections, navigation (prev=DD-23, next=none/end). |

## Sub-sections

- **DD-24.1 Why Agents Cost 1,000x More Than Chat** (8 min) — The multiplier stack: re-sent context (62% of bills), tool-call fan-out, retry loops, quadratic attention, context rot. Five mechanisms compounding.
- **DD-24.2 The Invisible Cost Layers** (5 min) — The cost iceberg: LLM inference (~20% TCO), context management (the 62%), retrieval/RAG, orchestration/eval/governance (the hidden 80%). Why Layer-1-only optimization fails.
- **DD-24.3 The @token_meter Interceptor Pattern** (8 min) — The core pattern. Wraps provider calls, tracks cumulative usage, enforces throttle at 80%, rollback at 100%, circuit-break on retry storms. Full TypeScript implementation.
- **DD-24.4 Cost-Aware Tool Selection** (5 min) — Annotating tools with cost. Model routing (RouteLLM: 85% cost cut at 95% quality). Switching models mid-session based on task phase.
- **DD-24.5 Human-in-the-Loop at Cost Thresholds** (5 min) — Three tiers: log (50%), warn+choice (80%), hard stop (100%). Alert-fatigue avoidance.
- **DD-24.6 Circuit Breakers for Runaway Loops** (5 min) — Four trip conditions: consecutive retries, total retries, fan-out depth, tokens-per-minute. Manual reset. Why automatic reset is dangerous.
- **DD-24.7 A Cost-Aware Execution Loop in TypeScript** (8 min) — Real code. Wraps Pi's loop with TokenMeter, beforeCall/afterCall, throttle switching, HITL, circuit breaker, hard iteration cap.
- **DD-24.8 Prompt Caching: The 90% Discount** (4 min) — Prefix-based caching. 90% reduction. Cache-killers: timestamps, IDs, framework-injected dynamic content. Audit the prefix.
- **DD-24.9 The Prime Directive and the C4 Connection** (4 min) — Cheaper-and-broken is not optimized. Hold quality constant. Throttle must pair with quality check. C4 Module E03 builds the fleet version.

## Load-bearing claims

- **Agents cost 1,000x more than chat** because five mechanisms compound: re-sent context (62% of bills), tool-call fan-out, retry loops, quadratic attention, and context rot (which amplifies cost via retries).
- **LLM inference is only ~20% of TCO.** The majority is context management (62% of inference bills), retrieval/RAG, and orchestration/eval/governance (the hidden 80%). Optimizing only the model-choice lever addresses a fraction of spend.
- **The @token_meter interceptor** (throttle at 80%, rollback at 100%, circuit-break on storms) is the budget-enforcement layer Pi lacks. Budget is checked BEFORE the call — prevention, not detection.
- **Prompt caching is the highest-ROI optimization**: 90% discount on cached tokens, zero quality loss. The barrier is prefix stability. Audit the first tokens for dynamic content.
- **The prime directive**: cutting cost while dropping success rate produces a broken-cheaper agent. Cost optimization must hold quality constant. Throttle must pair with quality monitoring.

## Learning objectives

1. Explain why agents cost 1,000x more than chat via the five-mechanism multiplier stack.
2. Quantify the invisible cost layers and why Layer-1-only optimization fails.
3. Implement the @token_meter interceptor: throttle, rollback, circuit-break.
4. Design cost-aware tool selection and model routing (RouteLLM pattern).
5. Implement HITL at cost thresholds without alert fatigue.
6. Build a circuit breaker for runaway loops with manual reset.
7. Write a cost-aware execution loop in TypeScript and connect to Course 4 E03.

## Navigation

- Previous: [DD-23 — DeerFlow](../dd-23-deerflow/)
- Next: None (final deep-dive in Course 1)
- Up: [Course 1 — Master Course](../../)