# Agent Trajectory Cost Audit

Audit multi-turn agent execution loops for quadratic token accumulation, retry loops, tool call overhead, and cumulative trajectory dollar costs.

## Workflow

1. Ingest turn-by-turn trajectory metrics:
   - Turn index ($k = 1 \dots N$)
   - Prompt tokens per turn ($P_k$)
   - Completion tokens per turn ($C_k$)
   - Cache read hit tokens ($H_k$)
   - Tool execution indicator (was a tool invoked?)
2. Calculate trajectory cumulative metrics:
   - Total un-cached prompt tokens: $\sum (P_k - H_k)$
   - Total cached prompt tokens: $\sum H_k$
   - Total completion tokens: $\sum C_k$
   - Context growth factor: $\frac{P_N}{P_1}$
3. Apply provider pricing ladder to compute total dollar cost of the entire agent execution trajectory.
4. Verify trajectory cost remains within declared budget ceilings.

## Synthetic Input Format

JSON object with:
- `schemaVersion`: 1
- `agentName`: string
- `model`: string
- `rates`:
  - `promptPerMillion`: non-negative decimal string
  - `cacheReadPerMillion`: non-negative decimal string
  - `outputPerMillion`: non-negative decimal string
- `turns`: list of objects, each containing:
  - `turnIndex`: positive integer
  - `promptTokens`: positive integer
  - `cachedTokens`: non-negative integer
  - `completionTokens`: positive integer
- `assertions`:
  - `maxTrajectoryCostUSD`: optional decimal string (e.g. "0.5000")
  - `maxTurns`: optional integer

## Exit Codes

- `0`: Valid trajectory within budget limits.
- `1`: Budget or turn ceiling breached.
- `2`: Malformed input or safety violation.

## Verification

```sh
python3 scripts/check.py examples/synthetic.json
```