# DD-24 — Diagrams: Cost-Aware Agents

Six Mermaid diagrams. Color coding per the design system:

- `#14141f` — panel fill (structural element)
- `#08080c` — nested node background (detail inside)
- `#5eead4` — teal accent (principle / the fix / the optimization)
- `#f0a868` — warn (cost layer / threshold / the invisible spend)
- `#f08080` — danger (impact / runaway loop / budget fire)

---

## Diagram 1 — The Multiplier Stack: Why Agents Cost 1,000x More Than Chat

**Type**: Flowchart (TB) showing the five compounding mechanisms

**Purpose**: The thesis visualized. Chat is one request, one response. Agents are a loop where five mechanisms compound: re-sent context, tool-call fan-out, retry loops, quadratic attention, context rot. The product is the 1,000x cost gap.

**Reading the diagram**: Top = chat (cheap). Bottom = the five multipliers stacking. Each multiplier feeds the next. The danger node at the bottom is the 1,000x product.

```mermaid
flowchart TB
    Chat(["Chat: 1 request, 1 response<br/>~500 tokens"]) --> M1

    subgraph Stack["THE MULTIPLIER STACK"]
        direction TB
        M1["1. RE-SENT CONTEXT<br/>every turn re-sends full history<br/>62% of total inference bills"]
        M2["2. TOOL-CALL FAN-OUT<br/>each tool result → another call<br/>5-deep tree = 243 leaf calls"]
        M3["3. RETRY LOOPS<br/>3 retries triple the cost<br/>unbounded retries = unbounded cost"]
        M4["4. QUADRATIC ATTENTION<br/>O(n²) in sequence length<br/>100K ctx is >10x the cost of 10K"]
        M5["5. CONTEXT ROT<br/>30%+ degradation at mid-window<br/>worse results → more retries → more cost"]
        M1 --> M2 --> M3 --> M4 --> M5
    end

    M5 --> Result(["AGENT TOTAL: up to 1,000x chat cost"])

    M1 -.->|"largest single cost"| Note1["Stanford Digital Economy Lab"]
    M5 -.->|"amplifier"| Note2["cost↑ quality↓ → retries↑ → cost↑↑"]

    classDef chat fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#9494a0
    classDef multiplier fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef danger fill:#08080c,stroke:#f08080,stroke-width:2px,color:#f08080
    classDef note fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#5a5a68
    classDef panel fill:#14141f,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8

    class Chat chat
    class M1,M2,M3,M4,M5 multiplier
    class Result danger
    class Note1,Note2 note
    class Stack panel
```

---

## Diagram 2 — The Four Cost Layers (The Iceberg)

**Type**: Flowchart (TB) showing the cost iceberg

**Purpose**: LLM inference is only ~20% of total cost of ownership. The majority lives in context management, retrieval, and orchestration — the "hidden 80%" most teams don't budget for.

**Reading the diagram**: Four layers stacked. The visible part (Layer 1, teal) is small. The invisible part (Layers 2-4, warn) is large. The annotation marks the hidden 80%.

```mermaid
flowchart TB
    subgraph Visible["VISIBLE — what most teams track (~20% TCO)"]
        L1["Layer 1: LLM INFERENCE<br/>the token bill<br/>~20% of total cost"]
    end

    subgraph Invisible["INVISIBLE — the hidden 80%"]
        direction TB
        L2["Layer 2: CONTEXT MANAGEMENT<br/>storage, retrieval, re-injection<br/>the 62% re-sent-context problem"]
        L3["Layer 3: RETRIEVAL / RAG<br/>embeddings, vector queries, reranking"]
        L4["Layer 4: ORCHESTRATION / EVAL / GOVERNANCE<br/>the infrastructure around the agent<br/>the hidden 80%"]
        L2 --> L3 --> L4
    end

    Visible --> Invisible
    L2 -.->|"largest invisible cost"| Big([62% of inference bills])
    L4 -.->|"most underbudgeted"| Hidden([the hidden 80%])

    classDef visible fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef invisible fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef annotation fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef panel fill:#14141f,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8

    class L1 visible
    class L2,L3,L4 invisible
    class Big,Hidden annotation
    class Visible,Invisible panel
```

---

## Diagram 3 — The `@token_meter` Interceptor: Throttle / Rollback / Circuit-Break

**Type**: Flowchart (TB) with the three enforcement actions

**Purpose**: The core pattern. The interceptor wraps every provider call. At 80% of budget: throttle. At 100%: rollback. On retry storms: circuit-break. This is the budget-enforcement layer Pi lacks.

**Reading the diagram**: The provider call enters at top. The meter checks budget BEFORE the call. Three enforcement branches: throttle (warn/switch model — session continues), rollback (abort/restore — session stops), circuit-break (retry storm detected — loop stops immediately).

```mermaid
flowchart TB
    Call(["provider call requested"]) --> Check{"beforeCall:<br/>projected budget ratio?"}

    Check -->|"ratio >= 1.0"| Rollback["ROLLBACK at 100%<br/>abort the operation<br/>restore prior state<br/>surface to operator"]
    Check -->|"ratio >= 0.8"| Throttle["THROTTLE at 80%<br/>switch to cheaper model<br/>reduce context window<br/>skip non-essential tools"]
    Check -->|"ratio < 0.8"| Proceed["proceed with the call"]

    Throttle --> Proceed
    Proceed --> Exec(["execute provider call"])
    Exec --> AfterCall{"afterCall:<br/>is this a retry?"}

    AfterCall -->|"consecutive retries<br/>>= threshold"| Break["CIRCUIT BREAK<br/>retry storm detected<br/>stop the loop immediately<br/>notify operator"]
    AfterCall -->|"normal"| Continue["record usage<br/>continue session"]
    AfterCall -->|"success after retry"| Reset["reset retry counter<br/>continue"]

    Rollback --> Stop([SESSION STOPPED])
    Break --> Stop
    Continue --> Next([next iteration])
    Reset --> Next

    classDef start fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#9494a0
    classDef decision fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#5eead4
    classDef throttle fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef rollback fill:#08080c,stroke:#f08080,stroke-width:2px,color:#f08080
    classDef breaker fill:#08080c,stroke:#f08080,stroke-width:2px,color:#f08080
    classDef ok fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#5eead4

    class Call,Exec start
    class Check,AfterCall decision
    class Throttle throttle
    class Rollback rollback
    class Break breaker
    class Proceed,Continue,Reset ok
    class Stop,Next start
```

---

## Diagram 4 — HITL at Cost Thresholds

**Type**: Flowchart (LR) with three threshold tiers

**Purpose**: Some spending decisions need a human. The three-tier pattern: log at 50%, warn+choice at 80%, hard stop at 100%. The human is in the loop at decision points, not at every turn.

**Reading the diagram**: Left-to-right, three thresholds. Each tier escalates intervention. The teal border marks the tier where the human decides; the danger border marks the hard stop.

```mermaid
flowchart LR
    Start([session spending]) --> T1{"50% of budget?"}
    T1 -->|"yes"| Log["TIER 1: LOG<br/>surface to operator dashboard<br/>no interruption<br/>session continues"]
    T1 -->|"no"| Continue1([continue])

    Log --> T2{"80% of budget?"}
    Continue1 --> T2
    T2 -->|"yes"| Warn["TIER 2: WARN + CHOICE<br/>notify: 'Task at 80% of budget'<br/>offer: continue? cheaper model? abort?<br/>HUMAN DECIDES"]
    T2 -->|"no"| Continue2([continue])

    Warn --> T3{"100% of budget?"}
    Continue2 --> T3
    T3 -->|"yes"| Stop["TIER 3: HARD STOP<br/>no more spending<br/>task paused, not killed<br/>human can authorize more budget"]
    T3 -->|"no"| Continue3([continue])

    classDef threshold fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#5eead4
    classDef log fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#9494a0
    classDef warn fill:#08080c,stroke:#f0a868,stroke-width:2px,color:#f0a868
    classDef stop fill:#08080c,stroke:#f08080,stroke-width:2px,color:#f08080
    classDef terminal fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#9494a0

    class T1,T2,T3 threshold
    class Log log
    class Warn warn
    class Stop stop
    class Start,Continue1,Continue2,Continue3 terminal
```

---

## Diagram 5 — The Runaway Loop and the Circuit Breaker

**Type**: Flowchart (TB) showing the storm pattern and the breaker

**Purpose**: The runaway loop is the highest-risk cost failure. A tool fails, the model retries, each retry re-sends context, cost compounds. The circuit breaker trips on consecutive retries and stops the loop. Without it, a single broken tool burns the entire budget.

**Reading the diagram**: The retry loop (warn) compounds cost. Four trip conditions (danger) can stop it. The breaker (teal) is the fix.

```mermaid
flowchart TB
    subgraph Storm["THE RUNAWAY LOOP (without breaker)"]
        direction TB
        S1["tool call fails"]
        S2["model retries"]
        S3["retry re-sends full context<br/>cost compounds"]
        S4["retry fails again"]
        S5["model retries again..."]
        S1 --> S2 --> S3 --> S4 --> S5
        S5 -.->|"unbounded"| Fire([BUDGET FIRE])
    end

    subgraph Breaker["THE CIRCUIT BREAKER"]
        direction TB
        B1["TRIP CONDITION 1:<br/>consecutive retries >= 5"]
        B2["TRIP CONDITION 2:<br/>total session retries >= 20"]
        B3["TRIP CONDITION 3:<br/>fan-out depth >= 3"]
        B4["TRIP CONDITION 4:<br/>tokens/min exceeds threshold"]
    end

    S5 -.->|"any condition met"| Trip["BREAKER TRIPS<br/>session stops<br/>operator notified<br/>reset is MANUAL"]
    B1 --> Trip
    B2 --> Trip
    B3 --> Trip
    B4 --> Trip

    Trip --> Safe([BUDGET PROTECTED])

    classDef storm fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef fire fill:#08080c,stroke:#f08080,stroke-width:2px,color:#f08080
    classDef condition fill:#08080c,stroke:#f08080,stroke-width:1px,color:#f08080
    classDef breaker fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef safe fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef panel fill:#14141f,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8

    class S1,S2,S3,S4,S5 storm
    class Fire fire
    class B1,B2,B3,B4 condition
    class Trip breaker
    class Safe safe
    class Storm,Breaker panel
```

---

## Diagram 6 — Pi's Loop vs. the Cost-Aware Loop

**Type**: Side-by-side comparison (LR)

**Purpose**: The thesis in one picture. Pi's loop has no budget concept — it runs until done or the model stops. The cost-aware loop wraps every provider call with the meter, enforces throttle/rollback/break, and adds HITL. This is the difference between a personal harness and an enterprise harness.

**Reading the diagram**: Left = Pi (no budget, unbounded). Right = cost-aware (meter, thresholds, breaker). The teal arrow is the wrapper that transforms one into the other.

```mermaid
flowchart LR
    subgraph Pi["Pi (DD-01) — No Budget"]
        direction TB
        PL["loop: call model → tools → repeat"]
        PN["NO budget tracking"]
        PN2["NO throttle"]
        PN3["NO circuit breaker"]
        PN4["NO HITL"]
        PR["runs until done or model stops<br/>(or until budget burns)"]
        PL --> PR
    end

    subgraph CA["Cost-Aware Loop — Budget as First-Class"]
        direction TB
        CAL["loop: meter.check → call model → meter.record"]
        CA1["budget tracked per session"]
        CA2["throttle at 80% (switch to cheap model)"]
        CA3["rollback at 100% (abort + restore)"]
        CA4["circuit-break on retry storms"]
        CA5["HITL at cost thresholds"]
        CAR["runs until done, model stops,<br/>OR budget enforces a stop"]
        CAL --> CAR
    end

    Pi -.->|"wrap with @token_meter"| CA

    classDef panel fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#e4e4e8
    classDef gap fill:#08080c,stroke:#f08080,stroke-width:1px,color:#f08080
    classDef feature fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#5eead4
    classDef loop fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8

    class Pi,CA panel
    class PN,PN2,PN3,PN4 gap
    class CA1,CA2,CA3,CA4,CA5 feature
    class PL,PR,CAL,CAR loop
```

---

## Validation Notes

- All diagrams use `flowchart` with TB or LR direction.
- Subgraph syntax validated: every `subgraph` has a matching `end`.
- Color coding consistent: teal for fix/principle/safe, warn for cost/threshold/invisible, danger for fire/storm/impact.
- No diagram exceeds 14 nodes.
- Diagram 1 establishes the multiplier stack thesis; 2 shows the cost iceberg; 3-4 decompose the enforcement patterns; 5 visualizes the runaway loop; 6 contrasts Pi with the cost-aware loop.