[LinuxDevil]

What

Every ExecutionResult carries usage: RunUsage (inputTokens, outputTokens, totalTokens, costUsd | undefined, modelCalls, estimated, byModel, optional delegated, optional cache/reasoning totals) and stepUsage: StepUsage[]. New public Usage, RunUsage, StepUsage, CallUsage, normalizeUsage, formatUsage (from src/models), ProviderUsage (from providers). Docs: "Usage and cost of a run" under "Models, tokens and cost" in docs/api-overview.md, plus a README feature bullet.

Why

The audit found no token/cost accounting on results; LOU-V6 (budgets) builds on these totals.

How

• src/models/usage.ts: types, normalizeUsage, formatUsage. src/execution/runUsage.ts: per-call measurement (reported, else estimateTokens flagged estimated), accumulation, delegation roll-up (AsyncLocalStorage sink, so no tool-result plumbing), checkpoint restore.
• GenerateResult.usage is now optional; aiSdkProvider returns undefined for the SDK's NaN counts and reads cache/reasoning tokens from providerMetadata when documented keys are present.
• costUsd is undefined if any contributing model is unpriced (no partial sum); per-model costs are recomputed from tokens so they stay consistent after merges.
• Resume: checkpoint stores the full running usage (old checkpoints: counts attributed to an unknown model, cost undefined). Approval pause/resume also carries usage (ExecutionSnapshot.usage, ExecuteOptions.initialUsage).
• finish/abort events carry the RunUsage; text-complete has stepUsage; onLLMResponse gets the call usage as a 3rd arg; the chat span reads the same numbers (loushy.usage.estimated when estimated).
• Edits in AgentExecutor.ts: the step loop moved verbatim into runSteps (so it can run inside the usage sink), plus a recordStep call where the step result is recorded.

How verified

• npx tsc --noEmit: clean. npm run lint: 0 errors (433 warnings, none new in touched code).
• npm run build and the create-loushy-agent build: success.
• Coverage run (merged with main 995f649): 117 files passed, 1648 tests passed, 4 skipped; npm run fallow exit 0. npm run test:types: no errors. docs:llms:check ok; docs:verify-snippets: all 59 snippets type-check, 6 run.
• Caveat: cloudflare.test.ts > wrangler dev serves the worker fails in my Windows environment (needs the wrangler CLI; unrelated), so the coverage run for fallow excluded that one file. guardrails.test.ts timeout test failed once under load and passed on rerun.

Notes for reviewer

• Behaviour change: mockModel with no usage now reports none (it reported zeros), so executor runs estimate; mockModel.test.ts expectation updated accordingly. Streaming types still require usage, so a usage-less mock turn streams zeros.
• RunUsage keeps promptTokens/completionTokens as deprecated aliases so existing consumers (evals budget, flows) work unchanged.
• The delegate tool still returns the legacy { promptTokens, completionTokens, totalTokens } to the model, not the breakdown.
• The streaming path (being added elsewhere) needs to call recordStep and run inside collectDelegatedUsage to get the same accounting.

🤖 Generated with Claude Code