mcp-cost-tracker-router 1.0.0

package/.env.example

@@ -0,0 +1,27 @@
+# ─── mcp-cost-tracker-router environment variables ───────────────────────────
+#
+# Copy this file to .env and fill in values for your environment.
+# None of these variables are required; the server runs without them.
+# They are only needed when running in HTTP mode (--http-port).
+
+# ─── Authentication (HTTP mode only) ─────────────────────────────────────────
+
+# Static API key for X-API-Key header authentication.
+# When set, every HTTP request must include the header:
+#   X-API-Key: <value>
+# Leave unset to disable API key authentication.
+MCP_API_KEY=your-api-key-here
+
+# HMAC-SHA256 secret used to verify HS256 JWT Bearer tokens.
+# When set, every HTTP request must include the header:
+#   Authorization: Bearer <jwt>
+# Leave unset to disable JWT authentication.
+MCP_JWT_SECRET=your-jwt-secret-here
+
+# ─── Alerting ─────────────────────────────────────────────────────────────────
+
+# Slack incoming webhook URL for budget alert notifications.
+# When set, a Slack message is posted whenever a session reaches 80% or 100%
+# of its configured budget threshold.
+# Leave unset to disable Slack notifications.
+MCP_SLACK_WEBHOOK=your-slack-webhook-url-here

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to MCP Cost Tracker & Router will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-03-23
+
+### Added
+
+- `gemini-2.0-flash` added to the built-in pricing table (`input: $0.0001`, `output: $0.0004` per 1K tokens).
+
+### Changed
+
+- Token counting migrated from `tiktoken-lite` to `js-tiktoken` (`cl100k_base` encoding) for offline, dependency-free token estimates. Falls back to `char/4` approximation on encoding failure.
+- `@modelcontextprotocol/sdk` upgraded from `^1.0.0` to `^1.12.0`.
+- `@types/node` upgraded from `^20.x` to `^24.12.0` (Node 24 LTS).
+- `eslint` upgraded from `^9.x` to `^10.0.3`; `eslint-config-prettier` from `^9.x` to `^10.1.8`.
+- `yargs` upgraded from `^17.x` to `^18.0.0`.
+- `@types/express` moved from `dependencies` to `devDependencies` — it is a type-only package with no runtime value.
+- Added `author`, `license`, `repository`, `homepage`, and `engines` (`>=20.19.0`) fields to `package.json`.
+- Added `prepublishOnly: npm run build` to ensure a fresh build before every `npm publish`.
+- Added `.env.example` documenting `MCP_API_KEY`, `MCP_JWT_SECRET`, and `MCP_SLACK_WEBHOOK`.
+- Notifications in `src/server.ts` wrapped in `tryNotify` helper to swallow unsupported-transport errors gracefully.
+
+### Fixed
+
+- Removed unused `base64urlDecode` function from `src/auth.ts`.
+- Converted `require()` import in `tests/alerting.test.ts` to ESM `import` to comply with `no-require-imports` lint rule.
+- Replaced untyped `Function` type with explicit call signatures in `tests/server-full.test.ts`.
+
+### Security
+
+- Resolved **GHSA-67mh-4wv8-2f99** (`esbuild` ≤ 0.24.2 dev-server cross-origin exposure) by upgrading `vitest` and `@vitest/coverage-v8` to `^4.1.0`. Affects local development only; not a production runtime concern.
+
+## [0.2.0] - 2026-03-12
+
+### Added
+
+- **Alerting** (`src/alerting.ts`): configurable budget alerts delivered to Slack webhooks.
+- **Audit log** (`src/audit-log.ts`): append-only JSONL audit trail of every cost-tracking tool call.
+- **JWT / API-key auth middleware** (`src/auth.ts`): HTTP transport protected via `MCP_API_KEY` or `MCP_JWT_SECRET`. stdio is unaffected.
+- **Per-client rate limiter** (`src/rate-limiter.ts`): sliding-window request throttle on the HTTP transport.
+- **Chargeback allocation** (`src/chargeback.ts`): distribute session cost across configured projects by token share.
+- **Project allocator** (`src/project-allocator.ts`): multi-project cost reporting and allocation tracking.
+- **Routing enforcer** (`src/routing-enforcer.ts`): YAML-based routing rules to block, warn on, or allow model selections.
+- **New tools**: `allocate_session_cost`, `get_project_report`, `enforce_routing`.
+- **`npm run inspect` script**: launches MCP Inspector for interactive pre-publish verification.
+- MCP Inspector verification instructions added to README.
+- `js-yaml` moved to `dependencies` (used at runtime by the routing enforcer).
+- Tests for alerting, audit log, auth, chargeback, project allocator, rate limiter, and routing enforcer.
+
+## [0.1.0] - 2026-03-12
+
+### Added
+
+- Initial public release of `mcp-cost-tracker-router`.
+- Per-tool-call and per-session token metering.
+- Persistent spend history stored locally in SQLite.
+- Model routing suggestions based on configurable cost thresholds.
+- Built-in pricing table covering major model providers.
+- Session budget alerts with configurable warning and hard-stop thresholds.
+- Streamable HTTP transport via `--http-port` flag (default: disabled, uses stdio).
+- GitHub Actions CI workflow running build, test, and lint on push/PR to `main`.
+- Vitest test suite with coverage via `@vitest/coverage-v8`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP Cost Tracker & Router contributors
+
+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,239 @@
+# MCP Cost Tracker & Router
+
+npm `mcp-cost-tracker-router` package
+
+Local-first cost awareness for MCP agent workflows. Token counts are calculated offline using js-tiktoken — no proxy, no API round-trip, no spend data leaving your machine. When costs climb, routing suggestions point you to cheaper models before the invoice arrives.
+
+[Tool reference](#tools) | [Configuration](#configuration) | [Contributing](#contributing) | [Troubleshooting](#troubleshooting)
+
+## Key features
+
+- **Per-tool cost breakdown**: See exactly which tool calls are consuming the most tokens and budget.
+- **Budget alerts**: Set a session spend threshold and get warned at 80% and 100% before you exceed it.
+- **Offline token counting**: Uses js-tiktoken for accurate counts — no API calls required.
+- **Model routing suggestions**: Recommends cheaper models for the current task type (advisory, never enforced without opt-in).
+- **Multi-provider pricing**: Tracks costs across Claude, OpenAI, and Gemini models from a single configurable pricing table.
+- **Spend history**: Query daily, weekly, and monthly totals by model or tool.
+- **Project cost allocation**: Tag sessions to named projects and generate chargeback reports.
+- **HTML spend reports**: Export a single-file, self-contained HTML report with charts and budget status.
+- **Audit log**: Append-only log of every budget enforcement decision.
+
+## Why this over proxy-based cost trackers?
+
+Most cost-tracking tools work by routing all your API traffic through their server and measuring tokens server-side. That means your prompts and responses transit a third-party service, and you're dependent on their uptime.
+
+|                   | mcp-cost-tracker-router                     | Proxy-based trackers (Helicone, LLMonitor, etc.) |
+| ----------------- | ------------------------------------------- | ------------------------------------------------ |
+| Token counting    | Offline via js-tiktoken — no network call   | Counted server-side after traffic is proxied     |
+| Data residency    | Local SQLite only                           | Prompts + responses pass through vendor servers  |
+| Model routing     | Built-in `suggest_model_routing` tool       | Rarely included; usually a separate paid tier    |
+| Multi-provider    | Claude, OpenAI, Gemini in one pricing table | Often single-provider or requires separate setup |
+| Uptime dependency | None — fully offline                        | Breaks if proxy is down                          |
+
+If your prompts contain sensitive information or you can't route traffic through a third party, this is the right tool. If you need a managed dashboard with team sharing, a proxy-based service may suit you better.
+
+## Disclaimers
+
+`mcp-cost-tracker-router` stores tool call metadata (token counts, model names, timestamps) locally in SQLite. It does not store prompt or response content. Cost calculations are estimates based on a local pricing table and may not exactly match your provider's invoice.
+
+## Requirements
+
+- Node.js v20.19 or newer.
+- npm.
+
+## Getting started
+
+Add the following config to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "cost-tracker": {
+      "command": "npx",
+      "args": ["-y", "mcp-cost-tracker-router@latest"]
+    }
+  }
+}
+```
+
+To set a session budget alert:
+
+```json
+{
+  "mcpServers": {
+    "cost-tracker": {
+      "command": "npx",
+      "args": ["-y", "mcp-cost-tracker-router@latest", "--budget-alert=5.00"]
+    }
+  }
+}
+```
+
+### MCP Client configuration
+
+Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed
+
+## Your first prompt
+
+Enter the following in your MCP client to verify everything is working:
+
+```
+How much has this session cost so far?
+```
+
+Your client should return a token and USD cost summary for the current session.
+
+## Tools
+
+### Session (4 tools)
+
+- `get_session_cost` — Returns token totals and USD cost estimates for the current session. Read-only.
+- `get_tool_costs` — Returns per-tool cost breakdown for the session, sorted by cost descending. Read-only.
+- `reset_session` — Start a new cost-tracking session. Previous session data is retained in history.
+- `record_usage` — Record token usage for a tool call. Takes `tool_name`, `model` (optional), `input_tokens`, and `output_tokens`. Emits a budget warning notification if 80% of threshold is reached.
+
+### Budgets & routing (3 tools)
+
+- `set_budget_alert` — Set a budget threshold in USD (`threshold_usd`). Warns at 80% and 100% of the threshold. Use with `--enforce-budget` to block calls beyond the limit.
+- `suggest_model_routing` — Heuristic model recommendation by task type. Takes `task_description` and optional `constraints.max_cost_usd`. Returns recommended model with reasoning and estimated cost.
+- `check_routing_policy` — Check whether a model is allowed for a given task type under the routing policy. Takes `task_type` and `model`.
+
+### History & reports (4 tools)
+
+- `get_spend_history` — Query historical spend aggregated by `period` (`day`/`week`/`month`). Returns breakdown by model and tool. Read-only.
+- `estimate_workflow_cost` — Pre-run cost estimation for a multi-step workflow. Takes a `steps` array with `tool_name`, `estimated_input_tokens`, `estimated_output_tokens`, and optional `model`. Read-only.
+- `export_spend_report` — Generate a single-file HTML spend report with session breakdown, historical spend, model cost comparison, and budget status. Read-only.
+- `export_budget_audit` — Export the audit log of budget enforcement decisions. Accepts optional `from_date`, `to_date`, and `format` (`json`/`csv`). Read-only.
+
+### Project allocation (4 tools)
+
+- `set_project` — Create or update a project with an optional `budget_usd`. Takes `project_name`.
+- `tag_session` — Tag the current session with a `project_name` for cost allocation.
+- `get_project_costs` — Get cost report for a project. Takes `project_name` and optional `since` (ISO date). Read-only.
+- `export_chargeback` — Generate a chargeback report for internal billing. Takes `from_date`, `to_date`, optional `group_by` (`project`/`session`), and optional `format` (`json`/`csv`). Read-only.
+
+## Configuration
+
+### `--budget-alert`
+
+Session spend threshold in USD. A warning is returned when session costs reach 80% and again at 100% of this threshold.
+
+Type: `number`
+
+### `--db` / `--db-path`
+
+Path to the SQLite database file used to store cost history.
+
+Type: `string`
+Default: `~/.mcp/costs.db`
+
+### `--pricing-table`
+
+Path to a JSON file containing custom model pricing ($/1K tokens). Merged with the built-in table; missing models fall back to defaults.
+
+Type: `string`
+
+### `--default-model`
+
+Model name to attribute costs to when no model can be inferred from context.
+
+Type: `string`
+Default: `claude-sonnet-4-6`
+
+### `--enforce-budget`
+
+Block tool calls that would cause the session to exceed the budget alert threshold. Requires `--budget-alert` to be set.
+
+Type: `boolean`
+Default: `false`
+
+### `--http-port`
+
+Start in HTTP mode using Streamable HTTP transport instead of stdio. Useful for sharing a single cost-tracking instance across a team.
+
+Type: `number`
+Default: disabled (uses stdio)
+
+Pass flags via the `args` property in your JSON config:
+
+```json
+{
+  "mcpServers": {
+    "cost-tracker": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-cost-tracker-router@latest",
+        "--budget-alert=2.00",
+        "--enforce-budget"
+      ]
+    }
+  }
+}
+```
+
+## Supported models and pricing
+
+Built-in pricing table (USD per 1K tokens):
+
+| Model             | Input     | Output    |
+| ----------------- | --------- | --------- |
+| claude-opus-4-6   | $0.0150   | $0.0750   |
+| claude-sonnet-4-6 | $0.0030   | $0.0150   |
+| claude-haiku-4-5  | $0.0008   | $0.0040   |
+| gpt-4o            | $0.0025   | $0.0100   |
+| gpt-4o-mini       | $0.000150 | $0.000600 |
+| gemini-1.5-pro    | $0.001250 | $0.005000 |
+| gemini-1.5-flash  | $0.000075 | $0.000300 |
+| gemini-2.0-flash  | $0.000100 | $0.000400 |
+
+Override individual model prices with `--pricing-table`. All costs are estimates.
+
+## Verification
+
+Before publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.
+
+**Interactive UI** (opens browser):
+
+```bash
+npm run build && npm run inspect
+```
+
+**CLI mode** (scripted / CI-friendly):
+
+```bash
+# List all tools
+npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
+
+# List resources and prompts
+npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
+npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list
+
+# Call a read-only tool
+npx @modelcontextprotocol/inspector --cli node dist/index.js \
+  --method tools/call --tool-name get_session_cost
+
+# Call record_usage with arguments
+npx @modelcontextprotocol/inspector --cli node dist/index.js \
+  --method tools/call --tool-name record_usage \
+  --tool-arg tool_name=my_tool --tool-arg input_tokens=500 --tool-arg output_tokens=200
+```
+
+Run before publishing to catch regressions in tool registration and runtime startup.
+
+## Contributing
+
+Update `src/pricing.ts` when new models are released. All cost calculation changes must include unit tests with known token counts and expected USD values. Routing suggestions live in `src/tools/routing.ts`.
+
+```bash
+npm install && npm test
+```
+
+## MCP Registry & Marketplace
+
+This plugin is available on:
+
+- [MCP Registry](https://registry.modelcontextprotocol.io)
+- [MCP Marketplace](https://marketplace.modelcontextprotocol.io)
+
+Search for `mcp-cost-tracker-router`.

package/dist/alerting.d.ts

@@ -0,0 +1,5 @@
+import Database from "better-sqlite3";
+export interface AlertChannels {
+    slackWebhook?: string;
+}
+export declare function checkBudgetAlerts(db: Database.Database, channels: AlertChannels): Promise<void>;

package/dist/alerting.js

@@ -0,0 +1,62 @@
+import { request as httpsRequest } from "https";
+function postSlackMessage(webhookUrl, text) {
+    return new Promise((resolve, reject) => {
+        const body = JSON.stringify({
+            blocks: [
+                {
+                    type: "section",
+                    text: { type: "mrkdwn", text },
+                },
+            ],
+        });
+        const url = new URL(webhookUrl);
+        const options = {
+            hostname: url.hostname,
+            path: url.pathname + url.search,
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(body),
+            },
+        };
+        const req = httpsRequest(options, (res) => {
+            res.resume();
+            res.on("end", () => resolve());
+        });
+        req.on("error", reject);
+        req.write(body);
+        req.end();
+    });
+}
+export async function checkBudgetAlerts(db, channels) {
+    if (!channels.slackWebhook)
+        return;
+    // Find sessions with budget thresholds set
+    const rows = db
+        .prepare(`
+    SELECT
+      s.id,
+      s.budget_threshold_usd,
+      COALESCE(SUM(tu.cost_usd), 0) AS total_cost_usd
+    FROM sessions s
+    LEFT JOIN tool_usage tu ON tu.session_id = s.id
+    WHERE s.budget_threshold_usd IS NOT NULL
+    GROUP BY s.id, s.budget_threshold_usd
+  `)
+        .all();
+    const alerts = [];
+    for (const row of rows) {
+        if (row.budget_threshold_usd === null)
+            continue;
+        const pct = (row.total_cost_usd / row.budget_threshold_usd) * 100;
+        if (pct >= 80 && pct < 100) {
+            alerts.push(`:warning: *Budget Alert* — Session \`${row.id}\` is at *${pct.toFixed(1)}%* of its $${row.budget_threshold_usd.toFixed(4)} budget ($${row.total_cost_usd.toFixed(6)} spent).`);
+        }
+        else if (pct >= 100) {
+            alerts.push(`:red_circle: *Budget Exceeded* — Session \`${row.id}\` has exceeded its $${row.budget_threshold_usd.toFixed(4)} budget ($${row.total_cost_usd.toFixed(6)} spent, ${pct.toFixed(1)}%).`);
+        }
+    }
+    for (const alertText of alerts) {
+        await postSlackMessage(channels.slackWebhook, alertText);
+    }
+}

package/dist/audit-log.d.ts

@@ -0,0 +1,16 @@
+export interface AuditEntry {
+    timestamp: string;
+    session_id: string;
+    tool_name: string;
+    tokens: number;
+    cost_usd: number;
+    budget_usd: number | null;
+    decision: "allowed" | "blocked";
+    reason: string;
+}
+export declare class AuditLog {
+    private readonly filePath;
+    constructor(filePath?: string);
+    record(entry: AuditEntry): void;
+    export(from?: string, to?: string): AuditEntry[];
+}

package/dist/audit-log.js

@@ -0,0 +1,32 @@
+import { appendFileSync, readFileSync, mkdirSync, existsSync } from "fs";
+import { homedir } from "os";
+import { dirname } from "path";
+export class AuditLog {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath ?? `${homedir()}/.mcp/cost-tracker-audit.jsonl`;
+        const dir = dirname(this.filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    record(entry) {
+        const line = JSON.stringify(entry) + "\n";
+        appendFileSync(this.filePath, line, "utf-8");
+    }
+    export(from, to) {
+        if (!existsSync(this.filePath)) {
+            return [];
+        }
+        const raw = readFileSync(this.filePath, "utf-8");
+        const lines = raw.split("\n").filter((l) => l.trim() !== "");
+        const entries = lines.map((l) => JSON.parse(l));
+        return entries.filter((e) => {
+            if (from && e.timestamp < from)
+                return false;
+            if (to && e.timestamp > to)
+                return false;
+            return true;
+        });
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler } from "express";
+export declare function createAuthMiddleware(): RequestHandler;

package/dist/auth.js

@@ -0,0 +1,56 @@
+import { createHmac } from "crypto";
+function verifyJwt(token, secret) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    const [headerB64, payloadB64, signatureB64] = parts;
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const expectedSig = createHmac("sha256", secret)
+        .update(signingInput)
+        .digest("base64url");
+    // Constant-time comparison
+    const expectedBuf = Buffer.from(expectedSig);
+    const actualBuf = Buffer.from(signatureB64 ?? "");
+    if (expectedBuf.length !== actualBuf.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expectedBuf.length; i++) {
+        diff |= (expectedBuf[i] ?? 0) ^ (actualBuf[i] ?? 0);
+    }
+    return diff === 0;
+}
+export function createAuthMiddleware() {
+    return (req, res, next) => {
+        const apiKeyEnv = process.env["MCP_API_KEY"];
+        const jwtSecretEnv = process.env["MCP_JWT_SECRET"];
+        // If neither env var is set, pass through
+        if (!apiKeyEnv && !jwtSecretEnv) {
+            next();
+            return;
+        }
+        // Validate X-API-Key if env var is set
+        if (apiKeyEnv) {
+            const providedKey = req.headers["x-api-key"];
+            if (!providedKey || providedKey !== apiKeyEnv) {
+                res
+                    .status(401)
+                    .json({ error: "Unauthorized: invalid or missing API key" });
+                return;
+            }
+        }
+        // Validate Authorization: Bearer JWT if env var is set
+        if (jwtSecretEnv) {
+            const authHeader = req.headers["authorization"];
+            if (!authHeader || !authHeader.startsWith("Bearer ")) {
+                res.status(401).json({ error: "Unauthorized: missing Bearer token" });
+                return;
+            }
+            const token = authHeader.slice("Bearer ".length).trim();
+            if (!verifyJwt(token, jwtSecretEnv)) {
+                res.status(401).json({ error: "Unauthorized: invalid JWT signature" });
+                return;
+            }
+        }
+        next();
+    };
+}

package/dist/chargeback.d.ts

@@ -0,0 +1,17 @@
+import Database from "better-sqlite3";
+export interface ToolBreakdown {
+    tool: string;
+    cost: number;
+}
+export interface ChargebackGroup {
+    name: string;
+    cost_usd: number;
+    sessions: number;
+    tool_breakdown: ToolBreakdown[];
+}
+export interface ChargebackReport {
+    period: string;
+    groups: ChargebackGroup[];
+}
+export declare function generateChargebackReport(db: Database.Database, from: string, to: string, groupBy: "project" | "session"): ChargebackReport;
+export declare function chargebackToCSV(report: ChargebackReport): string;

package/dist/chargeback.js

@@ -0,0 +1,103 @@
+export function generateChargebackReport(db, from, to, groupBy) {
+    const fromTs = new Date(from).getTime();
+    const toTs = new Date(to).getTime();
+    const period = `${from} to ${to}`;
+    if (groupBy === "project") {
+        const projectNames = db
+            .prepare(`
+      SELECT DISTINCT sp.project_name
+      FROM session_projects sp
+      INNER JOIN tool_usage tu ON tu.session_id = sp.session_id
+      WHERE tu.recorded_at >= ? AND tu.recorded_at <= ?
+    `)
+            .all(fromTs, toTs);
+        const groups = projectNames.map(({ project_name }) => {
+            const totRow = db
+                .prepare(`
+        SELECT
+          COALESCE(SUM(tu.cost_usd), 0) AS cost_usd,
+          COUNT(DISTINCT tu.session_id) AS sessions
+        FROM tool_usage tu
+        INNER JOIN session_projects sp ON sp.session_id = tu.session_id
+        WHERE sp.project_name = ?
+          AND tu.recorded_at >= ? AND tu.recorded_at <= ?
+      `)
+                .get(project_name, fromTs, toTs);
+            const toolRows = db
+                .prepare(`
+        SELECT
+          tu.tool_name AS tool,
+          SUM(tu.cost_usd) AS cost
+        FROM tool_usage tu
+        INNER JOIN session_projects sp ON sp.session_id = tu.session_id
+        WHERE sp.project_name = ?
+          AND tu.recorded_at >= ? AND tu.recorded_at <= ?
+        GROUP BY tu.tool_name
+        ORDER BY cost DESC
+      `)
+                .all(project_name, fromTs, toTs);
+            return {
+                name: project_name,
+                cost_usd: totRow.cost_usd,
+                sessions: totRow.sessions,
+                tool_breakdown: toolRows,
+            };
+        });
+        return { period, groups };
+    }
+    else {
+        // groupBy === "session"
+        const sessionRows = db
+            .prepare(`
+      SELECT DISTINCT session_id
+      FROM tool_usage
+      WHERE recorded_at >= ? AND recorded_at <= ?
+    `)
+            .all(fromTs, toTs);
+        const groups = sessionRows.map(({ session_id }) => {
+            const totRow = db
+                .prepare(`
+        SELECT
+          COALESCE(SUM(cost_usd), 0) AS cost_usd,
+          COUNT(DISTINCT session_id) AS sessions
+        FROM tool_usage
+        WHERE session_id = ?
+          AND recorded_at >= ? AND recorded_at <= ?
+      `)
+                .get(session_id, fromTs, toTs);
+            const toolRows = db
+                .prepare(`
+        SELECT
+          tool_name AS tool,
+          SUM(cost_usd) AS cost
+        FROM tool_usage
+        WHERE session_id = ?
+          AND recorded_at >= ? AND recorded_at <= ?
+        GROUP BY tool_name
+        ORDER BY cost DESC
+      `)
+                .all(session_id, fromTs, toTs);
+            return {
+                name: session_id,
+                cost_usd: totRow.cost_usd,
+                sessions: totRow.sessions,
+                tool_breakdown: toolRows,
+            };
+        });
+        return { period, groups };
+    }
+}
+export function chargebackToCSV(report) {
+    const lines = ["group_name,cost_usd,sessions,tool,tool_cost"];
+    for (const group of report.groups) {
+        if (group.tool_breakdown.length === 0) {
+            lines.push(`"${group.name}",${group.cost_usd},${group.sessions},,`);
+        }
+        else {
+            for (const tb of group.tool_breakdown) {
+                lines.push(`"${group.name}",${group.cost_usd},${group.sessions},"${tb.tool}",${tb.cost}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}