@tokentop/ttop 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Nigel Bazzeghin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+ > [!CAUTION]
+> **tokentop is under active development and not yet ready for general use.** APIs and configuration may change without notice. If you're interested, star the repo and check back soon.
+
+<div align="center">
+
+# tokentop
+
+**htop for your AI costs**
+
+Real-time terminal monitoring of LLM token usage and spending across providers and coding agents.
+
+![Tokentop Dashboard](assets/Screenshot.png)
+
+<!-- TODO: uncomment CI badge when GitHub Actions workflow is set up -->
+<!-- [![CI](https://img.shields.io/github/actions/workflow/status/tokentopapp/tokentop/ci.yml?style=flat-square&label=CI)](https://github.com/tokentopapp/tokentop/actions) -->
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![GitHub release](https://img.shields.io/github/v/release/tokentopapp/tokentop?style=flat-square)](https://github.com/tokentopapp/tokentop/releases)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-runtime-f9f1e1?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
+
+[Features](#features) · [Install](#installation) · [Quick Start](#quick-start) · [Keyboard Shortcuts](#keyboard-shortcuts) · [Configuration](#configuration) · [Plugins](#plugin-system)
+
+</div>
+
+---
+
+## Why tokentop?
+
+You're coding with AI agents all day. Claude Code, OpenCode, Cursor — they're burning through tokens and you have no idea how fast.
+
+You check the Anthropic dashboard. It's hours behind. You check OpenAI. Different dashboard, different login. Want to see it all in one place? In real time? In your terminal, where you already live?
+
+That's tokentop.
+
+- See every session, every model, every dollar — **live**
+- Track costs across **10 providers** from a single dashboard
+- Set **budget alerts** so you don't wake up to a surprise bill
+- Runs **100% locally** — your usage data never leaves your machine
+
+<!-- TODO: Replace with VHS recording
+## Demo
+
+> _Coming soon: VHS terminal recording_
+-->
+
+## Features
+
+- **Real-time dashboard** — Live token counts, costs, burn rate, and activity sparklines
+- **10 providers** — Anthropic, OpenAI, Google Gemini, GitHub Copilot, Codex, Perplexity, Antigravity, MiniMax, Zai, OpenCode Zen
+- **Session tracking** — See every coding agent session with model, tokens, cost, and duration
+- **Budget guardrails** — Daily, weekly, and monthly limits with visual warnings at limit percentages you set
+- **Smart sidebar** — Adaptive panel that breaks down spending by model, project, or agent
+- **Efficiency insights** — Cache leverage, output verbosity, and cost-per-request analysis to help you spend less
+- **Historical trends** — ASCII step charts showing cost patterns over 7, 30, or 90 days
+- **Projects view** — See which codebase is costing you the most
+- **Provider limits** — Visual gauges showing how close you are to rate limits
+- **Live pricing** — Fetches current model pricing from [models.dev](https://models.dev) with local caching
+- **15 built-in themes** — Dark: Tokyo Night (default), Dracula, Nord, Catppuccin Mocha, Gruvbox Dark, One Dark, Rosé Pine, Kanagawa, OpenCode, Claude Code · Light: Catppuccin Latte, Gruvbox Light, GitHub Light, Solarized Light, Rosé Pine Dawn
+- **Plugin system** — Extend with custom providers, agents, themes, and notifications
+- **Responsive layout** — Adapts to any terminal size; sidebar, KPI strip, header, and tables all reflow automatically from ultrawide to laptop-width
+- **Demo mode** — Explore the UI with synthetic data, no API keys needed
+- **Zero config** — Auto-discovers credentials from Claude Code, environment variables, and CLI auth files
+
+## Installation
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew install tokentopapp/tap/tokentop
+```
+
+### Install script (macOS/Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tokentopapp/tokentop/main/scripts/install.sh | sh
+```
+
+### Scoop (Windows)
+
+```powershell
+scoop bucket add tokentop https://github.com/tokentopapp/scoop-tokentop
+scoop install tokentop
+```
+
+### Standalone binaries
+
+Download the latest binary for your platform from [GitHub Releases](https://github.com/tokentopapp/tokentop/releases). No dependencies required.
+
+| Platform | Binary |
+|----------|--------|
+| macOS (Apple Silicon) | `ttop-darwin-arm64` |
+| Linux (x64) | `ttop-linux-x64` |
+| Linux (ARM64) | `ttop-linux-arm64` |
+| Windows (x64) | `ttop-windows-x64.exe` |
+
+### npm
+
+Requires [Bun](https://bun.sh) runtime. If Bun is installed, this works out of the box. If not, it will tell you how to get it.
+
+```bash
+bunx @tokentop/ttop
+# or install globally
+bun install -g @tokentop/ttop
+```
+
+### From source
+
+```bash
+git clone https://github.com/tokentopapp/tokentop.git
+cd tokentop
+bun install
+bun start
+```
+
+## Quick Start
+
+```bash
+# Launch tokentop
+bun start
+# or, if installed globally:
+ttop
+
+# Try it without any API keys
+ttop demo
+
+# Pick a theme
+ttop -t dracula
+
+# Deterministic demo for screenshots/testing
+ttop demo --seed 42 --preset heavy
+```
+
+tokentop will automatically discover your credentials. If you use Claude Code, your OAuth tokens are picked up immediately — no configuration needed.
+
+## Views
+
+tokentop has 4 main views, switchable with `1`–`4`:
+
+| Key | View | What it shows |
+|-----|------|---------------|
+| `1` | **Dashboard** | KPI strip, activity sparkline, provider limits, sessions table, smart sidebar |
+| `2` | **Providers** | All configured providers with connection status and usage levels |
+| `3` | **Trends** | ASCII step charts of cost over 7/30/90 days |
+| `4` | **Projects** | Cost and token breakdown by local project/repo |
+
+<!-- TODO: Add VHS recordings of each view
+> _Screenshots coming soon_
+-->
+
+## Keyboard Shortcuts
+
+### Global
+
+| Key | Action |
+|-----|--------|
+| `1`–`4` | Switch views |
+| `,` | Settings |
+| `:` | Command palette |
+| `r` | Refresh all providers |
+| `?` | Help overlay |
+| `q` | Quit |
+
+### Dashboard
+
+| Key | Action |
+|-----|--------|
+| `t` | Cycle time window (5m → 15m → 1h → 24h → 7d → 30d → all) |
+| `/` | Filter sessions (by agent, model, project) |
+| `s` | Cycle sort (cost, tokens) |
+| `j`/`k` or `↑`/`↓` | Navigate sessions |
+| `Enter` | Open session details |
+| `Tab`/`Shift+Tab` | Cycle focus (sessions → limits → sidebar) |
+| `i` | Toggle sidebar |
+| `m`/`p`/`a` | Sidebar dimension (model / project / agent) |
+| `b` | Cycle budget lock (sync with window, daily, weekly, monthly) |
+| `l` | Jump to provider limits |
+| `gg`/`G` | Jump to top/bottom |
+
+## Configuration
+
+Config lives at `~/.config/tokentop/config.json`:
+
+```jsonc
+{
+  "theme": "tokyo-night",          // 15 themes — see ttop --help for full list
+  "colorScheme": "auto",           // auto, light, dark
+  "refreshInterval": 60000,        // polling interval (ms)
+  "budgets": {
+    "daily": 50.00,
+    "weekly": 200.00,
+    "monthly": 500.00
+  }
+}
+```
+
+Settings are also editable in-app — press `,` to open the settings panel.
+
+### Credential Discovery
+
+tokentop finds your API credentials automatically — no manual key entry needed.
+
+**Discovery order:**
+
+1. **OpenCode / Claude Code auth** — Reads OAuth tokens from `~/.local/share/opencode/auth.json` (supports Anthropic OAuth, OpenAI/Codex OAuth, GitHub tokens, and well-known API keys)
+2. **Antigravity accounts** — Picks up Google/Gemini OAuth from `~/.config/opencode/antigravity-accounts.json`
+3. **Environment variables** — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.
+4. **External CLI auth** — Claude Code, Gemini CLI, and other tool auth files
+
+OAuth tokens are preferred over API keys because provider usage-tracking APIs (like Anthropic's `/api/oauth/usage`) require OAuth, not API keys. If you use Claude Code or OpenCode, your tokens are picked up immediately.
+
+## Plugin System
+
+tokentop is built on a plugin architecture with four extension points:
+
+| Type | Purpose | Official | Community |
+|------|---------|----------|-----------|
+| **Provider** | Add a model provider | `@tokentop/provider-*` | `tokentop-provider-*` |
+| **Agent** | Support a coding agent | `@tokentop/agent-*` | `tokentop-agent-*` |
+| **Theme** | Custom color schemes | `@tokentop/theme-*` | `tokentop-theme-*` |
+| **Notification** | Alert delivery (Slack, Discord, etc.) | `@tokentop/notification-*` | `tokentop-notification-*` |
+
+All plugins run in a **permission sandbox** — they must declare network, filesystem, and environment access upfront. Anyone can publish community plugins to npm — no org membership needed.
+
+See the [Plugin Guide](docs/plugins.md) for installation, configuration, and development details.
+
+## How It Works
+
+tokentop combines two data sources for real-time visibility:
+
+1. **Provider API polling** — Fetches usage data directly from provider APIs (Anthropic, OpenAI, etc.) on a configurable interval
+2. **Local session parsing** — Watches your coding agent's session files on disk via `fs.watch`, computing token deltas in real time as you code
+
+Costs are calculated from token counts and live pricing data from [models.dev](https://models.dev) (cached 1 hour), with built-in fallback pricing for offline use.
+
+All data is stored in a **local SQLite database**. Nothing is sent anywhere. No telemetry, no analytics, no network calls except to the provider APIs you've already authenticated with.
+
+## Development
+
+```bash
+bun install          # Install dependencies
+bun run dev          # Dev mode with hot reload
+bun test             # Run tests
+bun run typecheck    # TypeScript check
+bun run lint         # ESLint
+```
+
+### Demo mode for development
+
+```bash
+ttop demo                          # Random synthetic data
+ttop demo --seed 42                # Deterministic (reproducible)
+ttop demo --preset heavy           # High activity simulation
+ttop demo --seed 42 --preset light # Combine both
+```
+
+### Built with
+
+- [Bun](https://bun.sh) — Runtime
+- [OpenTUI](https://github.com/anthropics/opentui) — Terminal UI framework (React reconciler)
+- [TypeScript](https://www.typescriptlang.org/) — Strict mode
+- [SQLite](https://www.sqlite.org/) — Local storage via `bun:sqlite`
+
+## Contributing
+
+Contributions welcome! Please open an issue first to discuss what you'd like to change.
+
+- **Conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`
+- **TypeScript strict mode** — no `any`, no `@ts-ignore`
+- **Tests required** for new features
+
+## License
+
+[MIT](LICENSE)

package/bin/ttop.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+// tokentop npm entry point
+// Detects runtime and either loads directly (Bun) or re-launches with Bun (Node).
+// Standalone binaries at: https://github.com/tokentopapp/tokentop/releases
+
+if (typeof globalThis.Bun !== 'undefined') {
+  await import('../src/cli.ts');
+} else {
+  const { execFileSync } = await import('node:child_process');
+  const { fileURLToPath } = await import('node:url');
+  const { dirname, join } = await import('node:path');
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const cli = join(__dirname, '..', 'src', 'cli.ts');
+
+  try {
+    execFileSync('bun', ['run', cli, ...process.argv.slice(2)], {
+      stdio: 'inherit',
+    });
+  } catch (err) {
+    // If bun ran but the command itself failed, propagate the exit code
+    if (err.status) process.exit(err.status);
+
+    // Bun not found — show install instructions
+    console.error(
+      [
+        '',
+        'tokentop requires the Bun runtime (https://bun.sh)',
+        '',
+        'Install Bun:',
+        '  curl -fsSL https://bun.sh/install | bash',
+        '',
+        'Or download a standalone binary (no Bun needed):',
+        '  https://github.com/tokentopapp/tokentop/releases',
+        '',
+        'Homebrew (macOS/Linux):',
+        '  brew install tokentopapp/tap/tokentop',
+        '',
+        'Scoop (Windows):',
+        '  scoop bucket add tokentop https://github.com/tokentopapp/scoop-tokentop',
+        '  scoop install tokentop',
+        '',
+      ].join('\n'),
+    );
+    process.exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@tokentop/ttop",
+  "version": "0.2.2",
+  "description": "Real-time AI token usage monitor - htop for your API costs",
+  "author": "Nigel Bazzeghin <nbazzeghin@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ttop": "./bin/ttop.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun --hot src/cli.ts",
+    "start": "bun src/cli.ts",
+    "build": "bun build ./src/cli.ts --outdir=dist --target=bun --minify",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "driver": "bun src/tui/driver/cli.ts",
+    "driver:help": "bun src/tui/driver/cli.ts --help",
+    "snapshot": "bun src/tui/debug/snapshot.tsx"
+  },
+  "dependencies": {
+    "@opentui/core": "0.1.79",
+    "@opentui/react": "0.1.79",
+    "@tokentop/agent-claude-code": "^1.1.0",
+    "@tokentop/agent-opencode": "^1.0.0",
+    "@tokentop/plugin-sdk": "^1.1.0",
+    "react": "^19.0.0",
+    "react-devtools-core": "^7.0.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "token",
+    "usage",
+    "monitor",
+    "tui",
+    "terminal",
+    "htop",
+    "anthropic",
+    "openai",
+    "claude",
+    "gpt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tokentopapp/tokentop"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/agents/aggregator.ts

@@ -0,0 +1,176 @@
+import type { SessionUsageData } from '@/plugins/types/agent.ts';
+import {
+  totalTokenCount,
+  type AgentId,
+  type AgentName,
+  type AgentSessionAggregate,
+  type AgentSessionStream,
+  type StreamWindowedTokens,
+  type TokenCounts,
+} from './types.ts';
+
+const ACTIVE_THRESHOLD_MS = 2 * 60 * 1000;
+
+interface AggregateOptions {
+  agentId: AgentId;
+  agentName: AgentName;
+  rows: SessionUsageData[];
+  now?: number;
+  activeThresholdMs?: number;
+}
+
+interface StreamKey {
+  providerId: string;
+  modelId: string;
+}
+
+function streamKeyToString(key: StreamKey): string {
+  return `${key.providerId}::${key.modelId}`;
+}
+
+function sumTokens(a: TokenCounts, b: TokenCounts): TokenCounts {
+  const result: TokenCounts = {
+    input: a.input + b.input,
+    output: a.output + b.output,
+  };
+  
+  const cacheRead = (a.cacheRead ?? 0) + (b.cacheRead ?? 0);
+  if (cacheRead > 0) result.cacheRead = cacheRead;
+  
+  const cacheWrite = (a.cacheWrite ?? 0) + (b.cacheWrite ?? 0);
+  if (cacheWrite > 0) result.cacheWrite = cacheWrite;
+  
+  return result;
+}
+
+function computeWindowBoundaries(now: number) {
+  const nowDate = new Date(now);
+  const startOfDay = new Date(nowDate.getFullYear(), nowDate.getMonth(), nowDate.getDate()).getTime();
+  const dayOfWeek = nowDate.getDay();
+  const startOfWeek = new Date(nowDate.getFullYear(), nowDate.getMonth(), nowDate.getDate() - dayOfWeek).getTime();
+  const startOfMonth = new Date(nowDate.getFullYear(), nowDate.getMonth(), 1).getTime();
+  return { startOfDay, startOfWeek, startOfMonth };
+}
+
+interface StreamAccumulator {
+  key: StreamKey;
+  tokens: TokenCounts;
+  requestCount: number;
+  windowed: StreamWindowedTokens;
+}
+
+export function aggregateSessionUsage(options: AggregateOptions): AgentSessionAggregate[] {
+  const { agentId, agentName, rows, now = Date.now(), activeThresholdMs = ACTIVE_THRESHOLD_MS } = options;
+  const { startOfDay, startOfWeek, startOfMonth } = computeWindowBoundaries(now);
+
+  const sessionMap = new Map<string, {
+    sessionName?: string;
+    projectPath?: string;
+    timestamps: number[];
+    sessionUpdatedAt?: number;
+    streamMap: Map<string, StreamAccumulator>;
+  }>();
+
+  for (const row of rows) {
+    const existing = sessionMap.get(row.sessionId);
+    if (!existing) {
+      const newSession: {
+        sessionName?: string;
+        projectPath?: string;
+        timestamps: number[];
+        sessionUpdatedAt?: number;
+        streamMap: Map<string, StreamAccumulator>;
+      } = {
+        timestamps: [],
+        streamMap: new Map(),
+      };
+      if (row.sessionName) newSession.sessionName = row.sessionName;
+      if (row.projectPath) newSession.projectPath = row.projectPath;
+      if (row.sessionUpdatedAt) newSession.sessionUpdatedAt = row.sessionUpdatedAt;
+      sessionMap.set(row.sessionId, newSession);
+    }
+    
+    const session = sessionMap.get(row.sessionId)!;
+
+    session.timestamps.push(row.timestamp);
+    if (row.sessionName && !session.sessionName) {
+      session.sessionName = row.sessionName;
+    }
+    if (row.projectPath && !session.projectPath) {
+      session.projectPath = row.projectPath;
+    }
+    if (row.sessionUpdatedAt && (!session.sessionUpdatedAt || row.sessionUpdatedAt > session.sessionUpdatedAt)) {
+      session.sessionUpdatedAt = row.sessionUpdatedAt;
+    }
+
+    const streamKey: StreamKey = { providerId: row.providerId, modelId: row.modelId };
+    const streamKeyStr = streamKeyToString(streamKey);
+
+    let stream = session.streamMap.get(streamKeyStr);
+    if (!stream) {
+      stream = {
+        key: streamKey,
+        tokens: { input: 0, output: 0 },
+        requestCount: 0,
+        windowed: { dayTokens: 0, weekTokens: 0, monthTokens: 0, totalTokens: 0 },
+      };
+      session.streamMap.set(streamKeyStr, stream);
+    }
+
+    stream.tokens = sumTokens(stream.tokens, row.tokens);
+    stream.requestCount += 1;
+
+    const msgTokens = totalTokenCount(row.tokens);
+    stream.windowed.totalTokens += msgTokens;
+    if (row.timestamp >= startOfDay) stream.windowed.dayTokens += msgTokens;
+    if (row.timestamp >= startOfWeek) stream.windowed.weekTokens += msgTokens;
+    if (row.timestamp >= startOfMonth) stream.windowed.monthTokens += msgTokens;
+  }
+
+  const results: AgentSessionAggregate[] = [];
+
+  for (const [sessionId, session] of sessionMap) {
+    const startedAt = Math.min(...session.timestamps);
+    const lastActivityAt = Math.max(...session.timestamps);
+    const lastSeenAt = session.sessionUpdatedAt ?? lastActivityAt;
+    const status = (now - lastSeenAt) <= activeThresholdMs ? 'active' : 'idle';
+
+    const streams: AgentSessionStream[] = [];
+    const streamWindowedTokens = new Map<string, StreamWindowedTokens>();
+    let totals: TokenCounts = { input: 0, output: 0 };
+    let totalRequestCount = 0;
+
+    for (const [streamKeyStr, stream] of session.streamMap) {
+      streams.push({
+        providerId: stream.key.providerId,
+        modelId: stream.key.modelId,
+        tokens: stream.tokens,
+        requestCount: stream.requestCount,
+      });
+      totals = sumTokens(totals, stream.tokens);
+      totalRequestCount += stream.requestCount;
+      streamWindowedTokens.set(streamKeyStr, stream.windowed);
+    }
+
+    const aggregate: AgentSessionAggregate = {
+      sessionId,
+      agentId,
+      agentName,
+      startedAt,
+      lastActivityAt,
+      status,
+      totals,
+      requestCount: totalRequestCount,
+      streams,
+      costInDay: 0,
+      costInWeek: 0,
+      costInMonth: 0,
+      _streamWindowedTokens: streamWindowedTokens,
+    };
+    if (session.sessionName) aggregate.sessionName = session.sessionName;
+    if (session.projectPath) aggregate.projectPath = session.projectPath;
+    results.push(aggregate);
+  }
+
+  return results.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+}

package/src/agents/costing.ts

@@ -0,0 +1,74 @@
+import { getPricing, estimateCost } from '@/pricing/index.ts';
+import type { AgentSessionAggregate, AgentSessionStream, StreamCostBreakdown } from './types.ts';
+
+export async function priceStream(stream: AgentSessionStream): Promise<AgentSessionStream> {
+  const pricing = await getPricing(stream.providerId, stream.modelId);
+  
+  if (!pricing) {
+    return { ...stream, pricingSource: 'unknown' };
+  }
+
+  const breakdown = estimateCost(stream.tokens, pricing);
+  const source = pricing.source === 'models.dev' ? 'models.dev' : 'fallback';
+  
+  const costBreakdown: StreamCostBreakdown = {
+    total: breakdown.total,
+    input: breakdown.input ?? 0,
+    output: breakdown.output ?? 0,
+  };
+  if (breakdown.cacheRead) costBreakdown.cacheRead = breakdown.cacheRead;
+  if (breakdown.cacheWrite) costBreakdown.cacheWrite = breakdown.cacheWrite;
+
+  return {
+    ...stream,
+    costUsd: breakdown.total,
+    costBreakdown,
+    pricingSource: source,
+  };
+}
+
+export async function priceSession(session: AgentSessionAggregate): Promise<AgentSessionAggregate> {
+  const pricedStreams = await Promise.all(session.streams.map(priceStream));
+  
+  const totalCostUsd = pricedStreams.reduce((sum, s) => {
+    return sum + (s.costUsd ?? 0);
+  }, 0);
+
+  const hasAnyCost = pricedStreams.some(s => s.costUsd !== undefined);
+
+  let costInDay = 0;
+  let costInWeek = 0;
+  let costInMonth = 0;
+
+  if (hasAnyCost && session._streamWindowedTokens) {
+    for (const stream of pricedStreams) {
+      const streamCost = stream.costUsd ?? 0;
+      if (streamCost === 0) continue;
+
+      const keyStr = `${stream.providerId}::${stream.modelId}`;
+      const windowed = session._streamWindowedTokens.get(keyStr);
+      if (!windowed || windowed.totalTokens === 0) continue;
+
+      const ratio = 1 / windowed.totalTokens;
+      costInDay += streamCost * windowed.dayTokens * ratio;
+      costInWeek += streamCost * windowed.weekTokens * ratio;
+      costInMonth += streamCost * windowed.monthTokens * ratio;
+    }
+  }
+
+  const result: AgentSessionAggregate = {
+    ...session,
+    streams: pricedStreams,
+    costInDay,
+    costInWeek,
+    costInMonth,
+  };
+  if (hasAnyCost) result.totalCostUsd = totalCostUsd;
+  delete result._streamWindowedTokens;
+
+  return result;
+}
+
+export async function priceSessions(sessions: AgentSessionAggregate[]): Promise<AgentSessionAggregate[]> {
+  return Promise.all(sessions.map(priceSession));
+}

package/src/agents/index.ts

@@ -0,0 +1,12 @@
+export type {
+  AgentName,
+  AgentId,
+  TokenCounts,
+  AgentSessionStream,
+  AgentSessionAggregate,
+  AgentInfo,
+} from './types.ts';
+
+export { aggregateSessionUsage } from './aggregator.ts';
+
+export { priceStream, priceSession, priceSessions } from './costing.ts';