docs(agent-workflows): Plan usage and cost telemetry

[mmabrouk]

Context

Pi and Claude expose cache-aware token and cost information, but the agent runner reduces every
run to four ambiguous numbers. That loses cache buckets, currency, provenance, and model scope,
and it conflates ACP context-window occupancy with billed token usage. Tracing then repeats totals
on leaf and parent spans while the API recalculates producer-supplied cost, so the displayed cost
can be inaccurate or counted more than once.

This design starts at the pre-production harness, runner, and runner-to-service boundaries. It
keeps exported span attribution and service-to-API semantic-convention changes behind an explicit
CTO approval gate.

What this proposes

The runner normalizes each harness into inclusive input/output token totals with cache and
reasoning subcategories, monetary cost with currency and provenance, model-scoped observations,
and a separate context-utilization gauge. Pi and Claude adapters reconcile fields by authority and
temporality instead of replacing one whole usage object with another.

The plan also inventories the wider trace path: span hierarchy, model and response identity,
content policy, status/errors, timing, adapters, storage, rollups, query presets, and UI display.
It proposes one-owner incremental attribution and an Agenta cost semantic convention, but defers
all API-visible behavior changes until the CTO approves the convention, rollup, and cross-batch
strategy.

Before:

{"usage":{"input":10,"output":5,"total":15,"cost":0.001}}

Proposed direction:

{
  "usage": {
    "tokens": {"input":12000,"output":800,"total":12800,"details":{"cacheReadInput":10500}},
    "costs": {"total":{"amount":0.021,"currency":"USD"},"provenance":{"kind":"reported","source":"provider"}}
  },
  "context": {"usedTokens":12800,"windowTokens":200000}
}

How to review

1. Read context.md for scope and boundary constraints.
2. Read research.md and trace-inventory.md for the end-to-end findings and deferred gaps.
3. Review interface-design.md, especially inclusive token arithmetic, model-scoped cost
   provenance, final versus provisional events, and the service-to-API proposal.
4. Review plan.md for the runner-first sequence and the CTO gate before exported trace changes.
5. Check qa.md for cache-heavy, multi-model, partial/error, streaming, and no-double-counting
   coverage.

Decisions requested

• Approve or revise the canonical runner-to-service usage shape and normalization rules.
• Choose the cross-batch parent-summary direction to take into CTO review.
• Decide whether runner and service deployment can skew, requiring temporary old-wire parsing.
• Decide whether the first Vercel projection exposes cache details or only inclusive totals.
• Confirm the scope of the CTO approval packet for Agenta cost semantics, rollups, UI labels, and
  public documentation.

Tests / notes

This PR contains design documents only. The research used the live runner, installed Pi and Claude
ACP packages, Python service contracts, API adapters and tree rollups, observability UI paths,
existing tests, and public tracing documentation.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 12, 2026 4:20pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01c56fd7-3e5f-4cf8-bdc3-2461105ac081

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-usage-telemetry

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says: Please review the canonical runner-to-service usage shape, inclusive token and cache semantics, model-scoped cost provenance, and the phase boundary that requires CTO approval before any API-visible span attribution or semantic-convention change. The five open decisions are listed in status.md and the PR body.