Per-turn token and cost breakdown with child-agent aggregation

[themattvision]

Hi Paseo team,

I use Paseo every day as a hands-on vibecoder and product developer: https://www.instagram.com/themattvision/

Paseo is genuinely a game changer for orchestrating multiple coding agents.

I would love a compact usage indicator in the footer of each assistant response. On hover or tap it could show:

• input tokens
• cached input tokens
• output tokens
• cost
• total cost including child agents or subagents launched for that parent response, with an expandable breakdown per child agent.

The current plugin SDK is already close: it can render a timeline card after an assistant message, and agent streams emit turn usage. However, the public API does not provide stable historical binding from an assistant message to its turn, nor an explicit parent-turn to child-turn attribution. Exposing that would let plugins implement exact per-response, historical cost cards without guessing.

I built a local proof of concept designed to show direct agent usage live for newly observed turns. A native message-footer slot, or usage attached directly to assistant timeline items, would make this experience reliable and ideal.

Thanks for building Paseo. I use it every day and think this level of transparency would be hugely valuable for people orchestrating agents at scale.

[stv1024]

I have the same accounting need in TokenLedger, a community plugin with a per-turn ledger, agent panel, overview, and timeline summaries. The UI and pricing can stay in the plugin; the public usage and attribution contract is what prevents complete descendant accounting.

The plugin subscribes to the full paginated Paseo agent catalog. Provider-owned threads are a separate source, so increasing the catalog page limit does not recover their usage.

Concrete source evidence

The deployed workflow was checked on Paseo 0.8.0 on Windows. I also inspected current main at b2ce2bcb83dd40bd91c32098c59221f0b52d7ffd; these are source findings, not a claim that I ran that checkout:

• In Codex, dispatchSubAgentNotification has no token_usage_updated case. It returns through the default branch. The root dispatcher does handle that event.
• The provider-subagent descriptor contains identity, hierarchy, and presentation/status fields, but no structured usage, actual billing model, or cost scope.
• The plugin's public PaseoApi has no provider-subagent usage/history surface. A formatted subtitle is not a reliable accounting contract.

Simply forwarding child usage into the parent's lastUsage would lose ownership and could mix request counts with inclusive totals. The root timeline can remain free of child telemetry while a separate structured usage surface makes it available to plugins.

Minimum contract for reliable plugin aggregation

• A stable usage identity and an explicit request/turn/cumulative scope. Equal token counts cannot distinguish a replay from a second identical-sized request.
• Provider session/thread identity, parent/root ownership, and native-turn to Paseo-turn attribution, retained when child usage arrives after the parent finishes.
• The actual model for the usage being priced, including children that use a different model.
• Whether reported tokens/cost cover only this thread or already include descendants; missing coverage should be distinguishable from zero.
• A documented subscription/replay boundary. Paginated usage history or another cursor-based recovery contract would let a plugin reconnect without silently missing or adding usage twice.

Acceptance examples: two distinct requests with identical token counts both contribute; replaying one identity contributes nothing extra; late child usage stays attached to its original root turn; a parent cost that already includes children is not added to those child costs again. Native children also need one owner if they later appear as independent Paseo catalog agents.

Cache creation is a separate missing token dimension; I added the specific field-preservation evidence in #4623. Neither this extension nor the plugin needs a gateway-specific billing API. Would a provider-neutral usage surface with these ownership/scope guarantees fit the public SDK direction? The exact API shape can follow the maintainer's design; the existing plugin can serve as an integration case.

[stv1024]

Follow-up with OMP final-read ordering and branch-counter evidence beyond my September comment. This remains a request for the public data contract used by TokenLedger, not a proposal to move its ledger/UI into core.

What is current, versus installed-version evidence

The installed Paseo 0.11.2 investigation found OMP getSessionStats represents session/current-branch cumulative statistics, with already-exclusive input and some task-child usage included. That is evidence about the inspected runtime, not a guarantee that every provider or every kind of descendant has the same scope.

I separately inspected public main at cafa04d3fbdbc7e4a3fe8f4d4bea80f15cd4a1d0 (October 14; no full app run):

• OMP schedules stats polling every three seconds and reads getSessionStats. Polls are changed cumulative snapshots, not an identified stream of billed requests.
• completeTurn starts the async final stats read, resets the active turn, and emits turn_completed without usage, before that read resolves. The poller can later publish with the old turn ID, but suppresses that final read if a new turn increments its generation first. The stale-read guard is useful; removing it would risk attributing old usage to new work.
• That internal optional turn ID is not a complete public correction path: the manager stores only event.usage in lastUsage, while the public wire stream union has no usage_updated variant. A counter-only snapshot cannot reliably identify the completed turn being corrected.
• Codex child routing still drops token_usage_updated through the default branch; the root handler publishes mapped counters without a request identity. Existing subagent hierarchy/presentation is not usage ownership: the descriptor still lacks structured usage/model/scope fields, and explicitly says not to parse its subtitle.

Small offline reproduction

I ran the public revision's actual exported OmpUsagePoller in isolation, with readStats returning a manually resolved promise, a no-timer injected scheduler, and synthetic input=10/read=60/write=30/output=5. No provider process or paid probe was used.

1. startTurn(); pending = completeTurn("synthetic-turn-A"); record a terminal event as the adapter does before resolving stats; then resolve and await pending. Observed order: terminal, usage, with A on the internal usage callback.
2. Repeat, but call startTurn() for B before resolving A's stats. Observed no A final publication because the completion generation is stale.

This isolates the poller and mirrors the adapter's terminal sequencing; it is not an end-to-end daemon reproduction. A fixed client-side waiting interval cannot make either path a reliable final-drain contract.

Contract refinements that would make accounting recoverable

Names/shapes are proposals, not existing API claims:

• Identity: stable request/usage identity across live events, snapshots and history, plus explicit correction revision. Bind it to provider session, thread, parent/root lineage, native turn and owning Paseo turn/session incarnation. Preserve the actual model of each request, including fallback or child models, rather than using the current selected model.
• Counter domain: declare request delta vs turn aggregate vs session/current-branch cumulative, input/cache convention, and a branch/reset epoch or equivalent baseline identity. Rewind, fork, compaction, new provider session and resume must have documented effects. A current-branch counter is not necessarily a monotonic lifetime billing total.
• Ownership: declare own-thread vs descendant-inclusive scope for tokens and costs separately, and coverage of included children. Do not add itemized children to an inclusive parent total. If an internal child is also a catalog agent, identify the same underlying work rather than counting it twice. Currency and reported-cost delta/cumulative scope should be explicit; no cost estimation belongs in this request.
• Finality: either drain final usage before terminal delivery, or publish an identifiable late correction tied to the original turn, with a documented finality/coverage state. Define failure/cancellation, stats-read failure, a new turn starting, and late child completion; never silently translate a missing final read to zero.
• Recovery: a typed paginated usage history and matching subscription, sharing IDs/revisions and a cursor/watermark boundary. Define retention, expired cursors and explicit unavailable/partial/gap coverage, so reconnect/reload can recover or truthfully mark missing data. If a provider supplies only cumulative stats, report that lower-resolution coverage instead of manufacturing per-request records.

Synthetic acceptance cases: two distinct request IDs with the same counts both contribute, while replaying either contributes nothing extra; a branch switch from counter 100 to 40 is not a negative charge or proof of a billing reset; replaying a fork's shared prefix is not new work; late A/child usage arriving after B begins still corrects A; an own-parent 10 plus child 20 totals 30, while a descendant-inclusive parent 30 plus that same child still totals 30. Unknown inclusion means partial coverage, not an invented exact total.

I checked the adjacent model-label discussion #6492 and timing discussion #6850; this comment does not request either UI labels or timing fields. Cache-creation preservation remains in #4623. The newer merged OMP context-refresh fix #6106 is present in the inspected source, but does not establish the request identity, epoch, finality or recovery guarantees above.