Add token usage tracking and cost visibility for agent sessions #453

Problem

Squad has no visibility into token usage or costs across agent sessions. When the coordinator spawns agents, there's no tracking of how many tokens each agent consumes, no cumulative cost reporting, and no ability to set budget limits. Users have no way to answer basic questions like:

• How much did that last session cost?
• Which agent is the most expensive?
• How much am I spending per day/week on Squad?
• Is a particular task burning more tokens than expected?

Squad already has a cost-first model selection principle (prefer cheaper models unless writing code), but the actual spend is invisible. The orchestration log records what agents did, but not what they cost.

Proposed Solution

Phase 1: Token Usage Tracking (Visibility)

Surface token usage data that's already available from LLM API responses into Squad's existing logging infrastructure.

Where the data comes from:

• The Copilot SDK / LLM API responses include token counts (prompt tokens, completion tokens, total tokens)
• Each agent spawn produces usage data that currently gets discarded

Where to store it:

• Add a usage field to orchestration log entries (already written by Scribe after each batch)
• Format: { promptTokens, completionTokens, totalTokens, estimatedCostUsd }
• Scribe already writes per-agent orchestration logs -- just extend the entry format

How to surface it:

• squad status CLI command shows cumulative session cost
• Orchestration log entries include per-agent token usage
• Optional: squad cost CLI command for historical cost analysis across sessions

Phase 2: Budget Limits (Control)

Add optional per-agent and per-session budget caps to squad config.

Config (squad.config.ts / defineSquad):
ypescript defineSquad({ defaults: { budget: { perAgentSession: 50000, // max tokens per agent spawn perSession: 500000, // max tokens per coordinator session warnAt: 0.8, // warn at 80% of limit }, }, agents: [ defineAgent({ name: 'fenster', role: 'Core Dev', budget: { perSession: 100000 }, // override for expensive agents }), ], });

Enforcement:

• Coordinator checks budget before spawning (pre-flight)
• If an agent would exceed its budget, coordinator warns and asks user to approve or skip
• Session-level budget triggers a warning, not a hard stop (user can override)

Phase 3: Cost Dashboard (Analytics)

Extend the existing Aspire dashboard integration to show cost data:

• Token usage per agent over time
• Cost per session / per day
• Most expensive agents and tasks
• Budget utilization gauges

Scope

Phase 1 is the core deliverable -- make costs visible. Phases 2 and 3 are follow-ups that build on the data Phase 1 captures.

Technical Notes

• The SDK already has runtime/cost-tracker.ts -- investigate what it does today and whether it can be extended
• OTel metrics (runtime/otel-metrics.ts) may already have hooks for token counting
• The orchestration log format (templates/orchestration-log.md) needs a new ## Usage section
• Model pricing data could be maintained as a simple lookup table in the SDK