cost-xray

Cost X-ray

Produce a ranked, evidence-backed report on where this agent's model spend goes and what to change. ACP sits in the request path, so it sees composition (cache blend, context breakdown, per-tool output bytes, loop share) — not just totals. Your job: pull the data, run the decompositions below, and deliver a report the user can act on before scaling to production.

Data sources (in order of preference)

1. ACP MCP tools if connected: acp_optimize (composition), acp_trace (one run's steps), acp_recommendations (policy findings), acp_cost (spend by model).
2. REST fallback with the key in ~/.acp/credentials (or ~/.acp/proxy-key):
   • GET https://api.agenticcontrolplane.com/api/v1/runs?window=7d — run rollups
   • GET https://api.agenticcontrolplane.com/api/v1/runs/{runKey} — one run with ordered steps
   • GET https://api.agenticcontrolplane.com/api/v1/introspect/cost-insights?window=7d — ranked recommendations Auth: Authorization: Bearer <key>.

Analysis steps

1. Headline: total cost, run count, window. If byoAuth, label costs "@ API rates" (subscription traffic priced at what it would cost).
2. Cache economics — decompose before concluding. A low headline hit rate has at least four distinct causes with different fixes. Compute from step data (model, tMs, promptTokens, cachedTokens):
   • per-model hit rate — Anthropic caches are per-model; if one model is cold, switching is the cause → route or batch by model;
   • hit rate by gap since the previous same-model call (<1min / 1–5min / 5–60min) — decay over gaps = TTL expiry → schedule work closer together or accept it;
   • full-price share immediately after a model switch — high = switching cost, low = rules it out;
   • uniform ~50% across models and gaps = structural: likely cache writes of new tool output being counted as misses (heavy tool-result appending), or genuine prefix instability. Say which is more consistent with the context composition, and say what you cannot distinguish from the data.
3. Context composition: system vs history vs tool-results share. If tool results dominate, name the top tools by re-read bytes (toolResultBytesByTool) and the worst offender's MB.
4. Loop share: report the number. Only recommend a subagent split for autonomous agents (background/api tier) — for interactive agents the growing loop IS the work.
5. Failure waste: only from runOutcome === "failed" runs. Runs without a terminal outcome NEVER get a waste claim.
6. Recommendations: merge /cost-insights items, ranked by impactUsd.