Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(savings): report the same numbers from the API, the overview and the CLI (#2413)

Raghav Chamadiyaebe9539a83d9
diff --git a/docs/agent/DISTILL.md b/docs/agent/DISTILL.md
index 4342bba6f..0c2b45b7f 100644
--- a/docs/agent/DISTILL.md
+++ b/docs/agent/DISTILL.md
@@ -253,23 +253,31 @@ inside a repowise repo.
## `repowise saved` — the savings report
```bash
-repowise saved # per-filter rollup + totals + est. dollars
+repowise saved # per-operation rollup + totals + est. dollars
+repowise saved --by surface # distill vs hooks vs MCP
+repowise saved --by agent # which agent the savings went to
repowise saved --by day # daily rollup
-repowise saved --by source # cli vs hook-* vs mcp:<tool>
repowise saved --since 2026-06-01
-repowise saved --model claude-opus-4-6 # price the estimate differently
repowise saved --missed # savings raw commands left on the table
repowise saved --missed --missed-days 30
```
-Dollar estimates price saved tokens at the chosen model's *input* rate (saved
-tokens are input the agent never had to read) using the same pricing table as
-`repowise costs`. Token counts are chars/4 estimates.
-
-The report covers both surfaces of the ledger: the **distill command/hook
-path** (`cli` / `hook-*` sources) and **MCP counterfactual savings** (`mcp:<tool>`
-sources — each tool answer priced against the raw exploration it replaced).
-`repowise saved --by source` separates them.
+Savings are priced at each event's own rate, captured when the event was
+recorded, so a later price change never rewrites what a past saving was worth.
+Events recorded without a rate are reported as unpriced rather than valued at
+today's model, and the command prints both figures. Saved tokens are input the
+agent never had to read, so the input rate applies; the pricing table is the
+one `repowise costs` uses. Token counts are chars/4 estimates.
+
+The report covers every capture surface in one ledger: the **distill
+command/hook path**, the **hooks that replace a tool result**, and **MCP
+calls**, where each answer is counted against the raw exploration it replaced.
+`repowise saved --by surface` separates them.
+
+The total keeps two kinds of evidence apart. **Measured** savings compare a
+known before and after — bytes that really moved. **Inferred** savings estimate
+the exploration an answer replaced. The command prints the split, and calls the
+total "estimated" whenever any of it is inferred.
### Missed savings — `repowise saved --missed`
diff --git a/docs/architecture/savings-accounting.md b/docs/architecture/savings-accounting.md
index 2391ab89d..091c6b502 100644
--- a/docs/architecture/savings-accounting.md
+++ b/docs/architecture/savings-accounting.md
@@ -153,6 +153,44 @@ stay nullable so explicit evidence can be recorded without inventing any.
Repowise's own `llm_costs` spend is a separate metered-spend section, never
merged into or subtracted from achieved agent savings.
+The rate is captured when the event is written, from a per-repository snapshot
+cached in the sidecar (`pricing-snapshot.json`, 24-hour TTL). Detecting the
+coding agent's model scans the local transcripts, which measures around six
+seconds on a repository with no Codex history, so it cannot run per event.
+
+**No agent-facing surface ever resolves it.** The MCP path, the rewrite hook
+and the augment hook all read the cache and write an unpriced event when it is
+cold. Each of them runs inside the agent's own tool call, where a six-second
+stall is unacceptable even once a day, and the hooks are fresh processes that
+could not amortize one anyway. The cache is filled by `repowise distill` run
+directly and by `repowise saved` — a human typed both, and the second is asking
+for the dollar figure.
+
+So a repository that has only ever served MCP calls reports its savings as
+unpriced until someone runs either command. That is a reported state, not a
+gap: the report counts priced and unpriced tokens separately, and the surfaces
+say which is which.
+
+## One report, three consumers
+
+`core/savings/service.load_report` is the only reader of the canonical ledger.
+The savings endpoint, the repository overview headline and `repowise saved` all
+map its `SavingsReport` into their own output and do no accounting arithmetic
+of their own.
+
+This is a correctness rule rather than tidiness. While the three aggregated the
+ledger independently they disagreed four ways about the same repository:
+`repowise saved` folded MCP counterfactual rows into its distill totals while
+both endpoints excluded them; the endpoint's per-day series was drawn from a
+different row set than its own summary, so the series did not sum to the total;
+the dollar figure was computed three different ways, only one of which used an
+output rate; and the overview ignored every time window. A parity test asserts
+the endpoint and the core report agree.
+
+A report of `None` means the repository has no sidecar, so nothing has been
+measured. That is a different claim from a report of zero, which means it was
+measured and was zero, and the surfaces render the two differently.
+
## Hosted and shared-presentation boundary
Hosted `total_cents` is the lifetime absolute value of negative
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index c60300910..39167e4be 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -1241,17 +1241,23 @@ repowise expand a1b2c3d4e5f6 -q "FAILED"
### `repowise saved [PATH]`
-Report tokens (and estimated dollars) saved for your coding agent. Combines
-`repowise distill` savings (direct invocations and hook rewrites) with MCP
-tool-response savings — each curated answer counted against the raw file
-exploration it replaced. Group `--by source` to split the `mcp:*` rows from the
-distill filters.
+Report the input tokens your coding agent never had to read, and what they were
+worth. Reads the canonical savings ledger through the same report service the
+savings endpoint and the dashboard overview use, so the three cannot disagree.
+Covers the `repowise distill` path, the hooks that replace a tool result, and
+MCP calls; group `--by surface` to split them.
+
+Two figures travel with the total rather than being folded into it. *Measured*
+savings compare a known before and after; *inferred* savings estimate the
+exploration an answer replaced. And because each event is priced at the rate
+recorded when it happened, savings recorded without a rate are counted but not
+valued — reported as unpriced rather than valued at today's model.
| Flag | Description |
|------|-------------|
-| `--by` | Grouping: `filter` (default), `day`, `source` |
-| `--since` | Only count savings since this ISO date |
-| `--model` | Pricing model for the dollar estimate (input-token rate). Defaults to the model detected from this repo's most recent agent session, falling back to `claude-sonnet-4-6` |
+| `--by` | Grouping: `operation` (default), `surface`, `agent`, `model`, `day` |
+| `--since` | Only count savings on or after this ISO date. Converted to a whole-day window, rounded up, so the named day is always fully included |
+| `--model` | Pricing model for the `--missed` opportunity estimates. Recorded savings are priced per event, so this does not affect them. Defaults to the model detected from this repo's most recent agent session, falling back to `claude-sonnet-4-6` |
| `--missed` | Report commands that looked distillable but weren't rewritten |
| `--missed-days` | Window in days for `--missed` (default 7.0) |
| `--format` | `table` (default) or `json` |
@@ -1259,8 +1265,9 @@ distill filters.
JSON folds the table, the net, and every trailing advisory line into one document.
```bash
-repowise saved # per-filter rollup + totals
-repowise saved --by day # daily rollup
+repowise saved # per-operation rollup + totals
+repowise saved --by surface # distill vs hooks vs MCP
+repowise saved --by agent # which agent the savings went to
repowise saved --since 2026-06-01
repowise saved --missed # what's slipping past the hook
```
diff --git a/packages/api-client/src/costs.ts b/packages/api-client/src/costs.ts
index 8b11eecf1..1455ac337 100644
--- a/packages/api-client/src/costs.ts
+++ b/packages/api-client/src/costs.ts
@@ -20,46 +20,77 @@ export interface CostSummary {
since: string | null;
}
-export interface DistillSavingsGroup {
- group: string;
+/** One bucket of a savings breakdown. `group` is null for the bucket with no
+ * name — savings whose events carry no pricing model, which is a real
+ * quantity rather than a row to drop. */
+export interface SavingsBreakdownRow {
+ group: string | null;
events: number;
- raw_tokens: number;
- distilled_tokens: number;
- saved_tokens: number;
+ saved_input_tokens: number;
}
-export interface McpDropGroup {
- tool: string;
+/** One agent's savings. The display name comes from the server's identity
+ * registry, so no client keeps a label map of its own. */
+export interface SavingsAgentRow {
+ agent: string;
+ agent_display_name: string | null;
events: number;
- tokens: number;
- /** "counterfactual" (answer replaced raw exploration) or "truncation" (budget drop). */
- kind?: string;
+ saved_input_tokens: number;
+}
+
+/** One kind of observed opportunity. Never part of achieved savings. */
+export interface SavingsOpportunityRow {
+ kind: string;
+ observations: number;
+ estimated_potential_input_tokens: number;
}
-export interface DistillSavings {
+/**
+ * What agents avoided in one repository, from the canonical savings ledger.
+ *
+ * Three distinctions the UI preserves rather than flattens: measured vs
+ * inferred evidence, priced vs unpriced tokens, and achieved savings vs
+ * observed opportunities. `available: false` means nothing has been measured
+ * in this repository, which is not the same as a measured zero.
+ */
+export interface Savings {
available: boolean;
- events: number;
- raw_tokens: number;
- distilled_tokens: number;
- saved_tokens: number;
- estimated_usd_saved: number;
- pricing_model: string;
- /** How the pricing model was resolved (Phase 1 model-aware pricing). */
- pricing_agent: string;
- pricing_source: string;
- per_filter: DistillSavingsGroup[];
- per_day: DistillSavingsGroup[];
- /** Unified MCP savings — counterfactual ledger + truncation drops. */
- mcp_events: number;
- mcp_tokens: number;
- /** Count of counterfactual MCP queries answered ("N MCP queries answered"). */
- mcp_queries: number;
- mcp_per_tool: McpDropGroup[];
- /** Raw (non-distilled) agent commands a filter would have caught. */
+ /** Window the figures cover; null means all time. */
+ window_days: number | null;
+ as_of: string;
+ first_event_at: string | null;
+ last_event_at: string | null;
+
+ unique_events: number;
+ successful_or_usable_partial_events: number;
+ saving_interactions: number;
+ mcp_queries_answered: number;
+ dead_ends: number;
+
+ saved_input_tokens: number;
+ measured_saved_input_tokens: number;
+ inferred_saved_input_tokens: number;
+ priced_saved_input_tokens: number;
+ unpriced_saved_input_tokens: number;
+ priced_input_savings_usd: number;
+ saved_output_tokens: number | null;
+ priced_saved_output_tokens: number;
+ unpriced_saved_output_tokens: number;
+ priced_output_savings_usd: number;
+
+ per_operation: SavingsBreakdownRow[];
+ per_surface: SavingsBreakdownRow[];
+ per_agent: SavingsAgentRow[];
+ per_model: SavingsBreakdownRow[];
+ per_day: SavingsBreakdownRow[];
+
+ opportunity_count: number;
+ opportunity_tokens_excluded: number;
+ per_opportunity_kind: SavingsOpportunityRow[];
+ /** Transcript-mined opportunities: what was *not* saved. */
missed_events: number;
missed_tokens_est: number;
missed_window_days: number;
- /** Full re-reads of unchanged files a targeted get_symbol would have replaced. */
reread_events: number;
reread_tokens_est: number;
}
@@ -87,11 +118,11 @@ export async function getCostSummary(
});
}
-export async function getDistillSavings(
+export async function getSavings(
repoId: string,
- since?: string,
-): Promise<DistillSavings> {
- return apiGet<DistillSavings>(`/api/repos/${repoId}/distill-savings`, {
- since,
+ opts: { days?: number } = {},
+): Promise<Savings> {
+ return apiGet<Savings>(`/api/repos/${repoId}/savings`, {
+ days: opts.days,
});
}
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py b/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py
index 1d13e4443..143e5c9b8 100644
--- a/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py
+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py
@@ -280,6 +280,13 @@ def _record_event(
Attribution is real here rather than ``unknown``. The hook was handed the
serving agent's own adapter, so which agent saved these tokens is evidence,
not a guess.
+
+ Pricing is read from cache only, never resolved. Detecting the agent's
+ model means scanning local transcripts -- around six seconds when the
+ repository has no Codex history -- and this is a fresh process per tool
+ call, so it could not amortize that even once. An unpriced event is the
+ correct outcome here; the report counts priced and unpriced tokens
+ separately, and the next distill or MCP call refills the cache for us.
"""
try:
from datetime import UTC, datetime
@@ -287,9 +294,11 @@ def _record_event(
from repowise.core.agents.identity import slug_for_hook_adapter
from repowise.core.savings import recorder
from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key
+ from repowise.core.savings.pricing import resolve_pricing_snapshot
agent = slug_for_hook_adapter(hook_adapter)
event_id = new_event_id()
+ pricing = resolve_pricing_snapshot(repo_path, allow_scan=False)
recorder.record_event_on(
connection,
repo_path,
@@ -309,6 +318,7 @@ def _record_event(
"baseline_input_tokens": raw_tokens,
"pre_budget_input_tokens": raw_tokens,
"delivered_input_tokens": distilled_tokens,
+ **(pricing.as_payload() if pricing else {}),
},
)
except Exception:
diff --git a/packages/cli/src/repowise/cli/commands/saved_cmd.py b/packages/cli/src/repowise/cli/commands/saved_cmd.py
index a90fdab7e..370946fa2 100644
--- a/packages/cli/src/repowise/cli/commands/saved_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/saved_cmd.py
@@ -1,11 +1,15 @@
-"""``repowise saved`` — report tokens saved by output distillation.
+"""``repowise saved`` — report the input tokens agents did not have to read.
-Reads the savings ledger in the omissions sidecar
-(``.repowise/omissions/omissions.db``). The ledger covers the
-``repowise distill`` path (direct invocations and hook rewrites) plus MCP
-counterfactual savings — each tool answer priced against the raw file
-exploration it replaced, recorded under ``source='mcp:<tool>'``. Group by
-source to split the two surfaces.
+Reads the canonical savings ledger in the omissions sidecar
+(``.repowise/omissions/omissions.db``) through the one core report service, so
+this command, the savings endpoint and the repository overview headline report
+the same figures by construction. They previously did not: each aggregated and
+priced the ledger for itself, and the three disagreed about which rows counted
+as distillation, whether MCP tokens entered the dollar figure, whether a fixed
+output credit was added, and what window applied.
+
+The ledger covers the ``repowise distill`` path, the hooks that replace a tool
+result, and MCP calls. ``--by surface`` splits them.
Named ``saved`` rather than ``distill --stats`` because ``repowise distill``
captures everything after it as the command to run (``ignore_unknown_options``)
@@ -17,10 +21,14 @@ from __future__ import annotations
from datetime import datetime
from pathlib import Path
+from typing import TYPE_CHECKING
import click
from rich.table import Table
+if TYPE_CHECKING:
+ from repowise.core.savings.contracts import SavingsReport
+
from repowise.cli.helpers import console
from repowise.cli.output import emit_json, format_option, notice_console
@@ -35,10 +43,10 @@ DEFAULT_PRICING_MODEL = "claude-sonnet-4-6"
@click.option(
"--by",
"group_by",
- type=click.Choice(["filter", "day", "source"]),
- default="filter",
+ type=click.Choice(["operation", "surface", "agent", "model", "day"]),
+ default="operation",
show_default=True,
- help="Group savings by filter, day, or source surface.",
+ help="Group savings by operation, surface, agent, pricing model, or day.",
)
@click.option(
"--since",
@@ -52,9 +60,10 @@ DEFAULT_PRICING_MODEL = "claude-sonnet-4-6"
default=None,
metavar="MODEL",
help=(
- "Pricing model for the dollar estimate (input-token rate). Defaults to "
- "the model detected from this repo's most recent agent session, and "
- f"falls back to {DEFAULT_PRICING_MODEL} when there is none."
+ "Pricing model for the opportunity estimates under --missed. Recorded "
+ "savings are priced at the rate captured on each event, so this does "
+ "not affect them. Defaults to the model detected from this repo's most "
+ f"recent agent session, falling back to {DEFAULT_PRICING_MODEL}."
),
)
@click.option(
@@ -81,22 +90,29 @@ def saved_command(
missed_days: float,
fmt: str,
) -> None:
- """Show tokens (and estimated dollars) saved by ``repowise distill``.
+ """Show the input tokens agents did not have to read, and what they were worth.
- PATH defaults to the current directory; the report covers that repo's
- omission store (or the user-level fallback store when the repo has no
- ``.repowise/``). Covers the distill command/hook path plus MCP
- counterfactual savings (``source='mcp:<tool>'``); ``--by source`` splits them.
+ PATH defaults to the current directory. The report covers that repository's
+ savings ledger; a directory with no ``.repowise/`` has none, which is
+ reported as "nothing recorded" rather than as zero. Covers the distill
+ path, the replacement hooks and MCP calls; ``--by surface`` splits them.
"""
- from repowise.core.distill.store import OmissionStore, default_store_path
+ from repowise.core.distill.store import default_store_path
+ from repowise.core.savings.service import load_report
notices = notice_console(fmt)
since_ts = _parse_since(since)
+ window_days = _window_days(since_ts)
start = Path(path).resolve() if path else Path.cwd()
- pricing_model, pricing_note = _resolve_pricing(start, pricing_model)
if show_missed:
+ # Resolved only on this branch. Detection scans the local agent
+ # transcripts -- seconds, on a repository with no Codex history -- and
+ # only the opportunity estimates need it. Recorded savings carry the
+ # rate they were written with, so the default report must never pay for
+ # a detection it does not use.
+ pricing_model, _ = _resolve_pricing(start, pricing_model)
if fmt == "json":
emit_json(
{
@@ -111,7 +127,8 @@ def saved_command(
return
db_path = default_store_path(start)
- if not db_path.exists():
+ report = load_report(start, days=window_days)
+ if report is None:
notices.print(
"[yellow]No savings recorded yet.[/yellow] Run commands through "
"'repowise distill <cmd>' (or install the rewrite hook with "
@@ -121,98 +138,165 @@ def saved_command(
emit_json({"ledger": str(db_path), "events": 0, "rows": []})
return
- store = OmissionStore(db_path)
- try:
- summary = store.savings_summary(since=since_ts)
- rows = store.savings_rollup(by=group_by, since=since_ts)
- finally:
- store.close()
+ rows = _breakdown_rows(report, group_by)
+ saved = report.saved_input_tokens
if fmt == "json":
- saved_tokens = summary["saved_tokens"]
- usd, rate = _estimate_usd(saved_tokens, pricing_model)
emit_json(
{
"ledger": str(db_path),
"group_by": group_by,
"since": since,
- "pricing_model": pricing_model,
- "pricing_source": pricing_note,
- "input_rate_usd_per_mtok": rate,
- "summary": {**summary, "estimated_usd": usd},
+ "window_days": window_days,
+ "summary": {
+ "events": report.unique_events,
+ "saved_input_tokens": saved,
+ "measured_saved_input_tokens": report.measured_saved_input_tokens,
+ "inferred_saved_input_tokens": report.inferred_saved_input_tokens,
+ "priced_saved_input_tokens": report.priced_saved_input_tokens,
+ "unpriced_saved_input_tokens": report.unpriced_saved_input_tokens,
+ "estimated_usd": report.priced_input_savings_usd,
+ "mcp_queries_answered": report.mcp_queries_answered,
+ "dead_ends": report.dead_ends,
+ "first_event_at": report.first_event_at,
+ "last_event_at": report.last_event_at,
+ },
"rows": rows,
- "mcp_truncation": _mcp_truncation_rows(db_path, since_ts),
- "net": _net_data(start, saved_tokens, since_ts),
+ "opportunities": {
+ "count": report.opportunity_count,
+ "estimated_potential_input_tokens": report.opportunity_tokens_excluded,
+ "per_kind": [dict(row) for row in report.per_opportunity_kind],
+ },
+ "net": _net_data(start, saved, since_ts),
"missed_distill": _missed_report(start, missed_days),
"missed_mcp_rereads": _reread_report(start, missed_days),
"forgone": _forgone_rows(start, db_path, since_ts),
}
)
+ _warm_pricing_cache(start, report)
return
- if summary["events"] == 0:
- msg = "No distillation events recorded"
+ if report.unique_events == 0:
+ msg = "No savings events recorded"
if since_ts is not None:
msg += f" since {since}"
console.print(f"[yellow]{msg}.[/yellow]")
# Before returning, not after. Declining the init prompt turns off
# distill rewrites *and* skeleton-served Reads in the same write, so
# the cohort the counterfactual exists to inform is exactly the cohort
- # with zero distillation events — and returning here first would make
+ # with zero distillation events -- and returning here first would make
# its rows unreadable by the only command that reports them.
_print_forgone_read_skeleton_line(start, db_path, since_ts)
return
- saved = summary["saved_tokens"]
- pct = 100.0 * saved / summary["raw_tokens"] if summary["raw_tokens"] else 0.0
- usd, rate = _estimate_usd(saved, pricing_model)
-
table = Table(
- title=f"Distill savings - grouped by {group_by}",
+ title=f"Savings - grouped by {group_by}",
border_style="dim",
show_footer=True,
caption=(
- "Covers the 'repowise distill' command/hook path, MCP "
- "counterfactual savings (mcp:<tool>), and the hooks that replace a "
- "tool result: a Read served as a skeleton (read_skeleton), an "
- "unchanged re-read served as a pointer (read_reread), and a search "
- "flood served as a digest (search_digest). Group by filter or "
- "source to split them."
+ "Input tokens agents did not have to read, from the canonical "
+ "savings ledger: the 'repowise distill' command path, the hooks "
+ "that replace a tool result, and MCP calls. Group by surface, "
+ "agent, model or day to split them."
),
)
table.add_column(group_by.capitalize(), style="cyan", footer="[bold]TOTAL[/bold]")
- table.add_column("Events", justify="right", footer=str(summary["events"]))
- table.add_column("Raw Tokens", justify="right", footer=f"{summary['raw_tokens']:,}")
- table.add_column("Distilled Tokens", justify="right", footer=f"{summary['distilled_tokens']:,}")
+ table.add_column("Events", justify="right", footer=str(report.unique_events))
table.add_column(
- "Saved Tokens",
- justify="right",
- footer=f"[bold green]{saved:,} ({pct:.0f}%)[/bold green]",
+ "Saved Tokens", justify="right", footer=f"[bold green]{saved:,}[/bold green]"
)
for row in rows:
- row_pct = 100.0 * row["saved_tokens"] / row["raw_tokens"] if row["raw_tokens"] else 0.0
table.add_row(
str(row["group"] or "-"),
str(row["events"]),
- f"{row['raw_tokens']:,}",
- f"{row['distilled_tokens']:,}",
- f"[green]{row['saved_tokens']:,} ({row_pct:.0f}%)[/green]",
+ f"[green]{row['saved_input_tokens']:,}[/green]",
)
console.print()
console.print(table)
- console.print(
- f" Estimated saved: [bold green]${usd:.4f}[/bold green] "
- f"[dim](at ${rate:.2f}/M input tokens, {pricing_note}; "
- f"tokens are chars/4 estimates)[/dim]"
- )
+ _print_evidence_and_pricing(report)
console.print(f" [dim]Ledger: {db_path}[/dim]")
- _print_mcp_truncation_line(db_path, since_ts)
_print_net(start, saved, since_ts)
_print_missed_summary_line(start, missed_days)
_print_reread_summary_line(start, missed_days)
_print_forgone_read_skeleton_line(start, db_path, since_ts)
console.print()
+ _warm_pricing_cache(start, report)
+
+
+def _warm_pricing_cache(start: Path, report: SavingsReport) -> None:
+ """Resolve the pricing snapshot so future events can be priced.
+
+ The surfaces that write events all run inside an agent's tool call and read
+ this cache without ever filling it, so something has to. This command is
+ the right place: a human typed it and is reading a dollar figure.
+
+ Run only when the report actually shows unpriced savings, and only after
+ the output is on screen. Resolving costs seconds on a cold cache, and it is
+ self-limiting: once the cache is warm the events it prices stop being
+ unpriced, so this stops firing.
+ """
+ if not report.unpriced_saved_input_tokens:
+ return
+ from repowise.core.savings.pricing import resolve_pricing_snapshot
+
+ resolve_pricing_snapshot(start)
+
+
+#: Which report breakdown each ``--by`` value reads, and the key its rows use
+#: for the group. One mapping, so adding a breakdown is one line here rather
+#: than a new branch in the table renderer and another in the JSON writer.
+_BREAKDOWNS = {
+ "operation": ("per_operation", "operation"),
+ "surface": ("per_surface", "surface"),
+ "agent": ("per_agent", "agent"),
+ "model": ("per_model", "model"),
+ "day": ("per_day", "day"),
+}
+
+
+def _breakdown_rows(report: SavingsReport, group_by: str) -> list[dict]:
+ """One breakdown as uniform ``group``/``events``/``saved`` rows.
+
+ Agents are labelled from the identity registry, which the report already
+ carried through, so this never spells an agent name itself.
+ """
+ attribute, key = _BREAKDOWNS[group_by]
+ rows = getattr(report, attribute)
+ return [
+ {
+ "group": row.get("agent_display_name") or row[key] if key == "agent" else row[key],
+ "events": row["events"],
+ "saved_input_tokens": row["saved_input_tokens"],
+ }
+ for row in rows
+ ]
+
+
+def _print_evidence_and_pricing(report: SavingsReport) -> None:
+ """The two splits that stop the total reading as one confident number.
+
+ Measured against inferred says how the saving was established; priced
+ against unpriced says how much of it carries a rate at all. Both are
+ reported rather than folded in, because an event is priced at the rate
+ captured when it happened and some events carry none -- pricing those at
+ today's rate would be inventing evidence.
+ """
+ console.print(
+ f" Measured: [bold]{report.measured_saved_input_tokens:,}[/bold] "
+ f"Inferred: [bold]{report.inferred_saved_input_tokens:,}[/bold]"
+ )
+ if report.priced_saved_input_tokens:
+ console.print(
+ f" Estimated saved: [bold green]${report.priced_input_savings_usd:.4f}[/bold green] "
+ f"[dim](on {report.priced_saved_input_tokens:,} priced tokens; "
+ f"tokens are chars/4 estimates)[/dim]"
+ )
+ if report.unpriced_saved_input_tokens:
+ console.print(
+ f" [dim]{report.unpriced_saved_input_tokens:,} tokens carry no recorded "
+ f"rate and are not priced.[/dim]"
+ )
def _net_data(start: Path, saved_tokens: int, since_ts: float | None) -> dict | None:
@@ -371,53 +455,6 @@ _FORGONE_SURFACES = (
)
-def _mcp_truncation_rows(db_path: Path, since_ts: float | None) -> list[dict]:
- """Per-tool truncation drops, or ``[]`` when this repo has never served MCP."""
- import sqlite3
-
- from repowise.core.distill import tracking
-
- try:
- con = sqlite3.connect(f"file:{db_path.as_posix()}?mode=ro", uri=True, timeout=2)
- try:
- summary = tracking.mcp_savings_summary(con, since=since_ts)
- finally:
- con.close()
- except sqlite3.Error:
- return [] # no such table: this repo has never served MCP, not an error
- return [r for r in summary["per_tool"] if r["kind"] == "truncation"]
-
-
-def _print_mcp_truncation_line(db_path: Path, since_ts: float | None) -> None:
- """MCP savings the table above structurally cannot show.
-
- Two MCP signals exist. Counterfactual rows (``source='mcp:<tool>'`` in
- ``savings``) are already in the table, because they went through
- ``record_saving`` like everything else. Truncation drops are not: a tool
- with no counterfactual estimator writes only to ``omissions``, never
- calls ``record_saving``, and so is invisible to ``savings_summary`` --
- real savings that happened, sitting one table over.
-
- They are printed rather than folded into the footer because the table's
- columns are raw/distilled pairs and a drop has no raw counterpart to
- put in them. ``mcp_savings_summary`` merges with counterfactual
- precedence, so taking only the ``truncation`` rows adds each tool once.
- """
- rows = _mcp_truncation_rows(db_path, since_ts)
- if not rows:
- return
- tokens = sum(r["tokens"] for r in rows)
- events = sum(r["events"] for r in rows)
- tools = ", ".join(r["tool"] for r in rows[:3])
- if len(rows) > 3:
- tools += f", +{len(rows) - 3} more"
- console.print(
- f" [dim]Not counted above:[/dim] [green]{tokens:,}[/green] tokens dropped past "
- f"the response budget by {events:,} MCP call(s) ([dim]{tools}[/dim]) - tools with "
- "no counterfactual estimator yet, so only the truncation is measurable."
- )
-
-
def _forgone_rows(start: Path, db_path: Path, since_ts: float | None) -> list[dict]:
"""One row per replacing surface that has measured rows, else ``[]``.
@@ -771,13 +808,38 @@ def _parse_since(value: str | None) -> float | None:
return None
try:
return datetime.fromisoformat(value).timestamp()
- except ValueError as exc:
+ # OSError, not just ValueError: on Windows a pre-epoch date parses fine and
+ # then raises errno 22 from timestamp(), which would be a traceback rather
+ # than a usage error.
+ except (ValueError, OSError, OverflowError) as exc:
raise click.BadParameter(f"Cannot parse date '{value}': {exc}") from exc
def _estimate_usd(saved_tokens: int, model: str) -> tuple[float, float]:
- """Dollar estimate for *saved_tokens* at *model*'s input rate."""
+ """Dollar estimate for *saved_tokens* at *model*'s input rate.
+
+ Used only for the ``--missed`` opportunity estimates, which are hypothetical
+ tokens with no event and therefore no captured rate. Recorded savings are
+ never priced this way: each event carries the rate it was worth when it
+ happened, so repricing history at today's model would move past figures.
+ """
from repowise.core.generation.cost_tracker import get_model_pricing
rate = get_model_pricing(model)["input"]
return saved_tokens * rate / 1_000_000, rate
+
+
+def _window_days(since_ts: float | None) -> int | None:
+ """``--since`` as a whole-day window, or ``None`` for all time.
+
+ The report windows by days back from now, so a date becomes the number of
+ days that covers it. Rounded up, because a window that excluded the day the
+ user named would report less than they asked for.
+ """
+ if since_ts is None:
+ return None
+ import math
+ import time
+
+ elapsed = time.time() - since_ts
+ return max(0, math.ceil(elapsed / 86_400))
diff --git a/packages/core/src/repowise/core/agents/identity.py b/packages/core/src/repowise/core/agents/identity.py
index a2366377a..ae3b51ce7 100644
--- a/packages/core/src/repowise/core/agents/identity.py
+++ b/packages/core/src/repowise/core/agents/identity.py
@@ -246,7 +246,13 @@ def display_name_for(slug: str) -> str:
An unregistered slug — a retired agent whose events are still in the ledger
— is returned verbatim. Guessing a prettier label for an agent we no longer
describe would be inventing evidence.
+
+ :data:`UNKNOWN_AGENT` is the exception, because it is not an agent at all
+ but this registry's own word for "nothing was announced". Labelling it here
+ keeps that string out of every surface that has to display it.
"""
+ if slug == UNKNOWN_AGENT:
+ return "Unknown"
identity = _REGISTERED.get(slug)
return identity.display_name if identity else slug
diff --git a/packages/core/src/repowise/core/distill/engine.py b/packages/core/src/repowise/core/distill/engine.py
index dcb0d007b..29cf16b3c 100644
--- a/packages/core/src/repowise/core/distill/engine.py
+++ b/packages/core/src/repowise/core/distill/engine.py
@@ -103,12 +103,21 @@ def _record_event(
"""
from repowise.core.savings import recorder
from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key
+ from repowise.core.savings.pricing import resolve_pricing_snapshot
try:
repo_root = store.db_path.parents[2]
if store.db_path != recorder.sidecar_path(repo_root) or repo_root == Path.home():
return
event_id = new_event_id()
+ surface = "hook" if source.startswith("hook") else "distill"
+ # A hook-sourced run is not a CLI command a human typed: the rewrite
+ # hook turns the agent's own Bash call into `repowise distill`, so this
+ # runs synchronously inside that tool call. Detecting the model scans
+ # the local transcripts -- seconds, on a repository with no Codex
+ # history -- so the hook reads the cache and never fills it, exactly as
+ # the PostToolUse hook does. A direct `repowise distill` may scan.
+ pricing = resolve_pricing_snapshot(repo_root, allow_scan=surface != "hook")
recorder.record_event_in(
store,
repo_root,
@@ -117,7 +126,7 @@ def _record_event(
"idempotency_key": scoped_idempotency_key(str(repo_root), "distill", event_id),
"occurred_at": datetime.now(UTC),
# The rewrite hook tags its shell; everything else is the CLI.
- "surface": "hook" if source.startswith("hook") else "distill",
+ "surface": surface,
"integration": "unknown",
"agent": "unknown",
"operation": filter_name,
@@ -132,6 +141,7 @@ def _record_event(
"pre_budget_input_tokens": raw_tokens,
"delivered_input_tokens": distilled_tokens,
"omission_refs": (ref,),
+ **(pricing.as_payload() if pricing else {}),
},
)
except Exception:
diff --git a/packages/core/src/repowise/core/generation/cost_tracker.py b/packages/core/src/repowise/core/generation/cost_tracker.py
index 64c21caad..1dcf8dec9 100644
--- a/packages/core/src/repowise/core/generation/cost_tracker.py
+++ b/packages/core/src/repowise/core/generation/cost_tracker.py
@@ -7,6 +7,7 @@ the ``llm_costs`` table for historical reporting via ``repowise costs``.
from __future__ import annotations
import contextlib
+import hashlib
from collections.abc import Iterator
from datetime import datetime
from typing import Any
@@ -184,6 +185,25 @@ def get_model_pricing(model: str) -> dict[str, float]:
return _get_pricing(model)
+def pricing_table_version() -> str:
+ """Stable identifier for the rate tables this module resolves against.
+
+ Savings events snapshot the rate they were priced at so history is never
+ repriced, and that snapshot is only auditable if it also records *which*
+ table produced it. Derived from the table contents rather than declared as
+ a constant: a hand-maintained version is one more thing to keep in sync,
+ and it would go stale silently on exactly the edit that matters.
+ """
+ payload = repr(
+ (
+ sorted(_PRICING.items()),
+ _CLAUDE_FAMILY_PRICING,
+ sorted(_FALLBACK_PRICING.items()),
+ )
+ )
+ return "pricing:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()[:12]
+
+
# ---------------------------------------------------------------------------
# CostTracker
# ---------------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/savings/contracts.py b/packages/core/src/repowise/core/savings/contracts.py
index 08f8ece3b..f9844a396 100644
--- a/packages/core/src/repowise/core/savings/contracts.py
+++ b/packages/core/src/repowise/core/savings/contracts.py
@@ -311,6 +311,18 @@ class OpportunityObservation:
@dataclass(frozen=True, slots=True)
class SavingsReport:
+ """One repository's savings over one window, from one set of queries.
+
+ Every first-party surface -- the costs endpoint, the repository overview
+ headline and ``repowise saved`` -- reports from this object and does no
+ accounting arithmetic of its own. They used to each aggregate and price the
+ ledger independently, and produced three different dollar figures for the
+ same repository; that is what this type exists to prevent.
+
+ The breakdowns are bounded tuples, not generators, so a caller cannot turn
+ a report into an unbounded payload by iterating harder.
+ """
+
unique_events: int
successful_or_usable_partial_events: int
saving_interactions: int
@@ -329,3 +341,17 @@ class SavingsReport:
opportunity_count: int
opportunity_tokens_excluded: int
per_operation: tuple[Mapping[str, Any], ...] = ()
+ per_surface: tuple[Mapping[str, Any], ...] = ()
+ #: Rows carry ``agent_display_name`` beside the slug, resolved from the
+ #: identity registry here so no consumer needs a label map of its own --
+ #: there were three of those before this, one of them in TypeScript.
+ per_agent: tuple[Mapping[str, Any], ...] = ()
+ #: ``model`` is null on an unpriced event, which is a real bucket rather
+ #: than a gap to hide: it is how much saving carries no rate evidence.
+ per_model: tuple[Mapping[str, Any], ...] = ()
+ per_day: tuple[Mapping[str, Any], ...] = ()
+ per_opportunity_kind: tuple[Mapping[str, Any], ...] = ()
+ #: Freshness, for saying how current the figures are rather than implying
+ #: they are live. Null when the window holds no events at all.
+ first_event_at: str | None = None
+ last_event_at: str | None = None
diff --git a/packages/core/src/repowise/core/savings/pricing.py b/packages/core/src/repowise/core/savings/pricing.py
index ca4091218..cd8a64ebe 100644
--- a/packages/core/src/repowise/core/savings/pricing.py
+++ b/packages/core/src/repowise/core/savings/pricing.py
@@ -1,8 +1,53 @@
-"""Per-event pricing projections; history is never repriced."""
+"""Per-event pricing projections; history is never repriced.
+
+Two halves. :func:`price_tokens` projects a token count at a rate already
+captured on an event. :func:`resolve_pricing_snapshot` produces the rate to
+capture, at write time, so a later price change cannot rewrite what a past
+saving was worth.
+
+Why the snapshot is cached on disk rather than resolved per event:
+:func:`repowise.core.distill.session_model.resolve_session_model` scans the
+local agent transcripts, and its Codex branch reads every session file end to
+end whenever the repository has no Codex history -- the common case, and
+measured at around six seconds on a developer machine with 700 sessions.
+
+So *no agent-facing surface resolves it*. The MCP path and both hooks pass
+``allow_scan=False``: each runs inside the agent's own tool call, where a
+six-second stall is unacceptable even once a day, and the hooks are fresh
+processes that could not amortize one anyway. They write an unpriced event when
+the cache is cold, and the report counts priced and unpriced tokens separately
+for exactly that reason.
+
+The cache is filled by ``repowise distill`` run directly and by
+``repowise saved`` -- commands a human typed, where once a day is affordable.
+"""
from __future__ import annotations
+import contextlib
+import json
import math
+import os
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+#: Cache lifetime. A developer changes coding model far less often than they
+#: run a tool call, and a rate that is a day stale is a much smaller error than
+#: either alternative: a six-second stall per event, or no price at all.
+_TTL_SECONDS = 24 * 60 * 60
+
+#: Cache file format. Bump when the payload shape changes; an unreadable or
+#: unrecognised file is treated as absent, never as an error.
+_CACHE_VERSION = 1
+
+_CACHE_NAME = "pricing-snapshot.json"
+
+#: Mirrors the ``model`` bound in the event contract. A snapshot that would be
+#: rejected there has to be discarded here, while discarding it is still free.
+_MAX_MODEL_LENGTH = 128
def price_tokens(tokens: int, usd_per_million: float | None) -> float | None:
@@ -12,3 +57,174 @@ def price_tokens(tokens: int, usd_per_million: float | None) -> float | None:
if not math.isfinite(usd_per_million) or usd_per_million < 0:
raise ValueError("pricing rate must be finite and nonnegative")
return max(tokens, 0) * usd_per_million / 1_000_000
+
+
+@dataclass(frozen=True, slots=True)
+class PricingSnapshot:
+ """The rates an event was priced at, and where they came from."""
+
+ model: str
+ pricing_source: str
+ pricing_version: str
+ input_rate_usd_per_million: float
+ output_rate_usd_per_million: float
+ currency: str = "USD"
+
+ def as_payload(self) -> dict[str, Any]:
+ """The event fields this snapshot supplies, ready to merge."""
+ return {
+ "model": self.model,
+ "currency": self.currency,
+ "pricing_source": self.pricing_source,
+ "pricing_version": self.pricing_version,
+ "input_rate_usd_per_million": self.input_rate_usd_per_million,
+ "output_rate_usd_per_million": self.output_rate_usd_per_million,
+ }
+
+
+#: repository root -> (snapshot, monotonic deadline). Bounds the disk read as
+#: well as the scan for a long-lived process such as the MCP server.
+_memo: dict[str, tuple[PricingSnapshot | None, float]] = {}
+
+
+def resolve_pricing_snapshot(
+ repo_root: str | Path | None, *, allow_scan: bool = True
+) -> PricingSnapshot | None:
+ """The pricing snapshot to stamp on an event, or ``None`` when unpriced.
+
+ *allow_scan* is the hot-path switch. With it false the cache is read but
+ never refreshed, so the hook pays one small file read and writes an
+ unpriced event rather than triggering a transcript scan. Whichever surface
+ next runs with scanning allowed refills the cache for it.
+
+ Never raises: an unpriced event is a correct event, and the report reports
+ priced and unpriced tokens separately for exactly this reason.
+ """
+ if repo_root is None:
+ return None
+ try:
+ return _resolve(Path(repo_root), allow_scan=allow_scan)
+ except Exception:
+ return None
+
+
+def clear_pricing_cache() -> None:
+ """Drop the in-process memo. For tests and long-lived process teardown."""
+ _memo.clear()
+
+
+def _resolve(repo_root: Path, *, allow_scan: bool) -> PricingSnapshot | None:
+ key = str(repo_root)
+ now = time.monotonic()
+ memoized = _memo.get(key)
+ if memoized is not None and memoized[1] > now:
+ return memoized[0]
+ cached = _read_cache(_cache_path(repo_root))
+ if cached is not None:
+ snapshot, age = cached
+ # The memo expires when the *file* does, not a full TTL from now.
+ # Refreshing the deadline on every read would let a long-lived process
+ # serve a snapshot for nearly twice the TTL it is supposed to have.
+ _memo[key] = (snapshot, now + max(0.0, _TTL_SECONDS - age))
+ return snapshot
+ if not allow_scan:
+ # Deliberately no memo entry: the next scanning surface should refill
+ # the cache promptly rather than wait out a TTL this process set.
+ return None
+ scanned = _scan(repo_root)
+ if scanned is None:
+ return None
+ snapshot = scanned
+ # Memoized before the write, and the write cannot unmake it: a snapshot
+ # that cost six seconds to compute must not be discarded because the disk
+ # refused it. The process keeps it either way; only other processes lose.
+ _memo[key] = (snapshot, now + _TTL_SECONDS)
+ with contextlib.suppress(Exception):
+ _write_cache(_cache_path(repo_root), snapshot)
+ return snapshot
+
+
+def _cache_path(repo_root: Path) -> Path:
+ return repo_root / ".repowise" / "omissions" / _CACHE_NAME
+
+
+def _scan(repo_root: Path) -> PricingSnapshot | None:
+ """Detect the coding agent's model and freeze its rates.
+
+ Returns ``None`` rather than an over-long model id. The id is read out of a
+ transcript the user's agent wrote, and the event contract bounds ``model``
+ at 128 characters -- by *raising*, which would drop the whole event before
+ it was written. A pricing snapshot we cannot use must cost the event its
+ price, never its existence.
+ """
+ from repowise.core.distill.session_model import resolve_session_model
+ from repowise.core.generation.cost_tracker import get_model_pricing, pricing_table_version
+
+ resolved = resolve_session_model(repo_root)
+ if not resolved.model or len(resolved.model) > _MAX_MODEL_LENGTH:
+ return None
+ rates = get_model_pricing(resolved.model)
+ return PricingSnapshot(
+ model=resolved.model,
+ # Machine-readable provenance rather than the detector's human label,
+ # so a consumer can tell a detected rate from the default without
+ # parsing prose. ``unknown`` is the detector's own word for "nothing
+ # found", and stays distinguishable from a real agent.
+ pricing_source=f"session_model:{resolved.agent}",
+ pricing_version=pricing_table_version(),
+ input_rate_usd_per_million=float(rates["input"]),
+ output_rate_usd_per_million=float(rates["output"]),
+ )
+
+
+def _read_cache(path: Path) -> tuple[PricingSnapshot, float] | None:
+ """The cached snapshot and its age in seconds, or ``None`` if unusable."""
+ try:
+ raw = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return None
+ if not isinstance(raw, dict) or raw.get("version") != _CACHE_VERSION:
+ return None
+ resolved_at = raw.get("resolved_at")
+ # ``bool`` is an ``int``, and True would read as one second past the epoch.
+ if not isinstance(resolved_at, int | float) or isinstance(resolved_at, bool):
+ return None
+ age = time.time() - float(resolved_at)
+ if age > _TTL_SECONDS:
+ return None
+ try:
+ snapshot = PricingSnapshot(
+ model=str(raw["model"]),
+ pricing_source=str(raw["pricing_source"]),
+ pricing_version=str(raw["pricing_version"]),
+ input_rate_usd_per_million=float(raw["input_rate_usd_per_million"]),
+ output_rate_usd_per_million=float(raw["output_rate_usd_per_million"]),
+ currency=str(raw.get("currency", "USD")),
+ )
+ except (KeyError, TypeError, ValueError):
+ return None
+ # Re-checked on read, not just on write: the file is editable, and an
+ # over-long model would make the event contract reject the whole event.
+ if not snapshot.model or len(snapshot.model) > _MAX_MODEL_LENGTH:
+ return None
+ return snapshot, max(0.0, age)
+
+
+def _write_cache(path: Path, snapshot: PricingSnapshot) -> None:
+ """Write the cache atomically, or not at all.
+
+ A torn file reads back as absent, which costs another six-second scan, so
+ the temporary-then-replace is about latency here as much as correctness.
+ """
+ payload = {"version": _CACHE_VERSION, "resolved_at": time.time(), **snapshot.as_payload()}
+ # Unique per thread as well as per process: two threads in the MCP server
+ # resolving at once would otherwise interleave writes into one temp file,
+ # and os.replace would atomically publish the mixture.
+ temporary = path.with_name(f"{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+ try:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ temporary.write_text(json.dumps(payload), encoding="utf-8")
+ os.replace(temporary, path)
+ except OSError:
+ with contextlib.suppress(OSError):
+ temporary.unlink()
diff --git a/packages/core/src/repowise/core/savings/recorder.py b/packages/core/src/repowise/core/savings/recorder.py
index 7ab977bac..d586b2df9 100644
--- a/packages/core/src/repowise/core/savings/recorder.py
+++ b/packages/core/src/repowise/core/savings/recorder.py
@@ -154,7 +154,13 @@ def _build(payload: Mapping[str, Any], repo_root: str | Path) -> Any:
from repowise.core.savings.contracts import SavingsEvent
return SavingsEvent.from_mapping(
- {**payload, "repository_id": str(repo_root)}, accept_event_id=True
+ # Normalized through Path so the id a surface writes is the id the
+ # reader asks with. Surfaces hand this a Path or a raw string, and
+ # a string can carry a trailing separator or forward slashes on
+ # Windows; the report service normalizes the same way. A mismatch
+ # would not error -- it would report a confident zero.
+ {**payload, "repository_id": str(Path(repo_root))},
+ accept_event_id=True,
)
except Exception:
logger.debug("savings event rejected before write", exc_info=True)
diff --git a/packages/core/src/repowise/core/savings/reporting.py b/packages/core/src/repowise/core/savings/reporting.py
index 8f1282a8d..798399163 100644
--- a/packages/core/src/repowise/core/savings/reporting.py
+++ b/packages/core/src/repowise/core/savings/reporting.py
@@ -3,12 +3,53 @@
from __future__ import annotations
from collections import defaultdict
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping
from datetime import datetime, timedelta
+from typing import Any
from repowise.core.savings.contracts import OpportunityObservation, SavingsEvent, SavingsReport
from repowise.core.savings.pricing import price_tokens
+#: Day-series cap, shared by both report builders. A year of daily rows is
+#: already more than any surface plots; the point is that an all-time window
+#: cannot return an unbounded payload just because the repository is old.
+DAY_LIMIT = 366
+
+
+def breakdown_rows(key: str, rows: Iterable[tuple[Any, ...]]) -> tuple[Mapping[str, Any], ...]:
+ """Shape ``(group, events, saved_input_tokens)`` triples into report rows.
+
+ Shared with :mod:`repowise.core.savings.repository` so the SQL path and the
+ pure path cannot drift into two different row shapes. They are meant to be
+ field-for-field identical, and the only way to keep that true is for one of
+ them to own the shaping.
+ """
+ return tuple(
+ {key: row[0], "events": int(row[1]), "saved_input_tokens": int(row[2])} for row in rows
+ )
+
+
+def agent_breakdown_rows(rows: Iterable[tuple[Any, ...]]) -> tuple[Mapping[str, Any], ...]:
+ """Agent rows, carrying the display name beside the stored slug.
+
+ Resolved here rather than in each consumer: the identity registry is the
+ one place an agent's label is written, and there were three separate label
+ maps before this, one of which spelled Codex CLI differently from the
+ registry. An unregistered slug comes back verbatim, which is how a retired
+ agent still in the ledger stays readable.
+ """
+ from repowise.core.agents.identity import display_name_for
+
+ return tuple(
+ {
+ "agent": row[0],
+ "agent_display_name": display_name_for(row[0]) if row[0] else None,
+ "events": int(row[1]),
+ "saved_input_tokens": int(row[2]),
+ }
+ for row in rows
+ )
+
def _included(occurred_at: str, cutoff: datetime | None, as_of: datetime) -> bool:
timestamp = datetime.fromisoformat(occurred_at.replace("Z", "+00:00"))
@@ -33,15 +74,26 @@ def build_report(
scoped_opportunities = [
item for item in opportunities if _included(item.occurred_at, cutoff, as_of)
]
- per_operation: dict[str, list[int]] = defaultdict(lambda: [0, 0])
+ groups: dict[str, dict[Any, list[int]]] = {
+ name: defaultdict(lambda: [0, 0])
+ for name in ("operation", "surface", "agent", "model", "day")
+ }
input_usd = 0.0
output_usd = 0.0
priced_input = 0
priced_output = 0
output_evidence_events = 0
for event in scoped:
- per_operation[event.operation][0] += 1
- per_operation[event.operation][1] += event.saved_input_tokens
+ for name, value in (
+ ("operation", event.operation),
+ ("surface", event.surface),
+ ("agent", event.agent),
+ ("model", event.model),
+ ("day", event.occurred_at[:10]),
+ ):
+ bucket = groups[name][value]
+ bucket[0] += 1
+ bucket[1] += event.saved_input_tokens
input_price = price_tokens(event.saved_input_tokens, event.input_rate_usd_per_million)
if input_price is not None:
priced_input += event.saved_input_tokens
@@ -56,12 +108,34 @@ def build_report(
output_usd += output_price
saved_input = sum(event.saved_input_tokens for event in scoped)
saved_output = sum(event.saved_output_tokens or 0 for event in scoped)
- breakdown = tuple(
- {"operation": operation, "events": values[0], "saved_input_tokens": values[1]}
- for operation, values in sorted(
- per_operation.items(), key=lambda item: (-item[1][1], item[0])
- )[: max(0, min(max_breakdowns, 100))]
- )
+ limit = max(0, min(max_breakdowns, 100))
+
+ def ranked(name: str) -> list[tuple[Any, ...]]:
+ """Sorted ``(group, events, saved)`` triples, matching the SQL order.
+
+ ``-saved`` then group ascending, with a null group first among ties --
+ SQLite sorts NULL first on an ascending key, and an unpriced event has
+ a null model, so this is the tie the two builders actually hit.
+ """
+ return [
+ (group, values[0], values[1])
+ for group, values in sorted(
+ groups[name].items(),
+ key=lambda item: (-item[1][1], item[0] is not None, item[0] or ""),
+ )[:limit]
+ ]
+
+ # Ordered by day ascending, capped to the most recent days, matching the
+ # SQL path's newest-first-then-reversed slice.
+ day_rows = [
+ (group, values[0], values[1])
+ for group, values in sorted(groups["day"].items(), reverse=True)[:DAY_LIMIT]
+ ][::-1]
+ opportunity_kinds: dict[str, list[int]] = defaultdict(lambda: [0, 0])
+ for item in scoped_opportunities:
+ opportunity_kinds[item.kind][0] += 1
+ opportunity_kinds[item.kind][1] += item.estimated_potential_input_tokens
+ occurrences = sorted(event.occurred_at for event in scoped)
def answered(event: SavingsEvent) -> bool:
return event.result_state == "success" or (
@@ -92,5 +166,21 @@ def build_report(
opportunity_tokens_excluded=sum(
item.estimated_potential_input_tokens for item in scoped_opportunities
),
- per_operation=breakdown,
+ per_operation=breakdown_rows("operation", ranked("operation")),
+ per_surface=breakdown_rows("surface", ranked("surface")),
+ per_agent=agent_breakdown_rows(ranked("agent")),
+ per_model=breakdown_rows("model", ranked("model")),
+ per_day=breakdown_rows("day", day_rows),
+ per_opportunity_kind=tuple(
+ {
+ "kind": kind,
+ "observations": values[0],
+ "estimated_potential_input_tokens": values[1],
+ }
+ for kind, values in sorted(
+ opportunity_kinds.items(), key=lambda item: (-item[1][1], item[0])
+ )[:limit]
+ ),
+ first_event_at=occurrences[0] if occurrences else None,
+ last_event_at=occurrences[-1] if occurrences else None,
)
diff --git a/packages/core/src/repowise/core/savings/repository.py b/packages/core/src/repowise/core/savings/repository.py
index d925c5295..8c8833e96 100644
--- a/packages/core/src/repowise/core/savings/repository.py
+++ b/packages/core/src/repowise/core/savings/repository.py
@@ -12,6 +12,11 @@ from repowise.core.savings.contracts import (
SavingsReport,
utc_text,
)
+from repowise.core.savings.reporting import (
+ DAY_LIMIT,
+ agent_breakdown_rows,
+ breakdown_rows,
+)
_EVENT_COLUMNS = (
"event_id",
@@ -57,6 +62,29 @@ class SavingsRepository:
def __init__(self, connection: sqlite3.Connection) -> None:
self._conn = connection
+ def _grouped(
+ self,
+ expression: str,
+ where: str,
+ params: list[Any],
+ limit: int,
+ *,
+ order: str = "3 DESC, 1 ASC",
+ ) -> list[tuple[Any, ...]]:
+ """One bounded ``GROUP BY`` over the scoped events.
+
+ *expression* and *order* are SQL fragments and are only ever called
+ with literals written in this module -- never with a caller's value.
+ The window filter rides ``idx_savings_events_repo_time``; the grouping
+ sorts the matched slice, which is why every one of these is capped.
+ """
+ return self._conn.execute(
+ f"SELECT {expression}, COUNT(*), COALESCE(SUM(saved_input_tokens), 0) "
+ f"FROM savings_events WHERE {where} "
+ f"GROUP BY 1 ORDER BY {order} LIMIT ?",
+ [*params, limit],
+ ).fetchall()
+
def record_event(self, event: SavingsEvent) -> bool:
"""Atomically insert an event and its links; return false for a retry."""
values = [getattr(event, column) for column in _EVENT_COLUMNS[:-1]]
@@ -132,7 +160,12 @@ class SavingsRepository:
days: int | None = None,
max_breakdowns: int = 100,
) -> SavingsReport:
- """Read totals with three bounded aggregate queries and no writes."""
+ """Read totals and breakdowns with bounded aggregate queries, no writes.
+
+ Every query is filtered on ``(repository_id, occurred_at)``, which is
+ indexed, and every breakdown is capped, so the payload is bounded by
+ the caps rather than by how much the repository has accumulated.
+ """
if as_of.tzinfo is None:
raise ValueError("as_of must include a timezone")
if days is not None and days < 0:
@@ -169,25 +202,38 @@ class SavingsRepository:
THEN COALESCE(saved_output_tokens, 0) ELSE 0 END), 0),
COALESCE(SUM(CASE WHEN output_rate_usd_per_million IS NOT NULL
THEN COALESCE(saved_output_tokens, 0) * output_rate_usd_per_million
- / 1000000.0 ELSE 0 END), 0.0)
+ / 1000000.0 ELSE 0 END), 0.0),
+ MIN(occurred_at),
+ MAX(occurred_at)
FROM savings_events WHERE {where}
""",
params,
).fetchone()
limit = max(0, min(int(max_breakdowns), 100))
- operations = self._conn.execute(
- f"""
- SELECT operation, COUNT(*), COALESCE(SUM(saved_input_tokens), 0)
- FROM savings_events WHERE {where}
- GROUP BY operation ORDER BY 3 DESC, 1 ASC LIMIT ?
- """,
- [*params, limit],
- ).fetchall()
+ operations = self._grouped("operation", where, params, limit)
+ surfaces = self._grouped("surface", where, params, limit)
+ agents = self._grouped("agent", where, params, limit)
+ models = self._grouped("model", where, params, limit)
+ # Newest-first then reversed, so a window longer than the cap keeps the
+ # recent days a reader is actually looking at rather than the oldest.
+ days_rows = list(
+ reversed(
+ self._grouped(
+ "substr(occurred_at, 1, 10)", where, params, DAY_LIMIT, order="1 DESC"
+ )
+ )
+ )
opportunity_count, opportunity_tokens = self._conn.execute(
"SELECT COUNT(*), COALESCE(SUM(estimated_potential_input_tokens), 0) "
f"FROM savings_opportunities WHERE {where}",
params,
).fetchone()
+ opportunity_kinds = self._conn.execute(
+ "SELECT kind, COUNT(*), COALESCE(SUM(estimated_potential_input_tokens), 0) "
+ f"FROM savings_opportunities WHERE {where} "
+ "GROUP BY 1 ORDER BY 3 DESC, 1 ASC LIMIT ?",
+ [*params, limit],
+ ).fetchall()
saved_input = int(row[5])
priced_input = int(row[8])
saved_output = int(row[11])
@@ -210,8 +256,19 @@ class SavingsRepository:
priced_output_savings_usd=float(row[13]),
opportunity_count=int(opportunity_count),
opportunity_tokens_excluded=int(opportunity_tokens),
- per_operation=tuple(
- {"operation": item[0], "events": item[1], "saved_input_tokens": item[2]}
- for item in operations
+ per_operation=breakdown_rows("operation", operations),
+ per_surface=breakdown_rows("surface", surfaces),
+ per_agent=agent_breakdown_rows(agents),
+ per_model=breakdown_rows("model", models),
+ per_day=breakdown_rows("day", days_rows),
+ per_opportunity_kind=tuple(
+ {
+ "kind": item[0],
+ "observations": int(item[1]),
+ "estimated_potential_input_tokens": int(item[2]),
+ }
+ for item in opportunity_kinds
),
+ first_event_at=row[14],
+ last_event_at=row[15],
)
diff --git a/packages/core/src/repowise/core/savings/service.py b/packages/core/src/repowise/core/savings/service.py
new file mode 100644
index 000000000..3bc3a40e2
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/service.py
@@ -0,0 +1,79 @@
+"""The one savings report every first-party surface reads.
+
+Before this, three consumers each aggregated and priced the ledger themselves:
+the costs endpoint, the repository overview headline and ``repowise saved``.
+They disagreed in at least four ways that mattered -- which ledger rows counted
+as distillation, whether MCP tokens entered the dollar figure, whether an
+output credit was added, and what time window applied -- so the same repository
+reported three different savings and three different dollar values depending on
+where you looked.
+
+So this module is deliberately the only reader. It opens the sidecar read-only,
+runs the bounded aggregates, and hands back a :class:`SavingsReport`. It does
+no formatting and no presentation: a caller maps the report to its own output
+shape, but never recomputes a number from its parts.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from repowise.core.savings.contracts import SavingsReport
+from repowise.core.savings.recorder import sidecar_path
+from repowise.core.savings.repository import SavingsRepository
+
+
+def load_report(
+ repo_root: str | Path | None,
+ *,
+ as_of: datetime | None = None,
+ days: int | None = None,
+ max_breakdowns: int = 100,
+) -> SavingsReport | None:
+ """The savings report for *repo_root*, or ``None`` when unavailable.
+
+ ``None`` means "no sidecar to read", which is the ordinary state of a
+ repository that has never run a distill, hook or MCP call -- not an error
+ and not zero. Callers distinguish the two: an absent report is "we have not
+ measured anything here", a report of zero is "we measured, and it is zero".
+
+ Read-only and never raises. Reporting runs inside a dashboard endpoint and
+ a CLI command, neither of which should fail because a sidecar is locked,
+ truncated or written by a newer build.
+ """
+ if repo_root is None:
+ return None
+ database = sidecar_path(repo_root)
+ if not database.is_file():
+ return None
+ moment = as_of or datetime.now(UTC)
+ try:
+ # A read-only URI handle never contends with the hook and MCP writers,
+ # and never runs the schema upgrade a read path has no business doing.
+ connection = sqlite3.connect(
+ f"file:{database.as_posix()}?mode=ro", uri=True, timeout=1
+ )
+ except sqlite3.Error:
+ return None
+ try:
+ return SavingsRepository(connection).report(
+ # The recorder files events under the path it wrote to, so the
+ # reader has to ask with the same string or it reads an empty
+ # repository and reports a confident zero. Both sides normalize
+ # through Path for exactly that reason: a caller-supplied path can
+ # carry a trailing separator or forward slashes on Windows, and the
+ # server stores whatever a client registered, verbatim.
+ str(Path(repo_root)),
+ as_of=moment,
+ days=days,
+ max_breakdowns=max_breakdowns,
+ )
+ # OverflowError is not a ValueError: a large enough ``days`` overflows the
+ # timedelta rather than failing validation, and this function promises not
+ # to raise into a dashboard endpoint.
+ except (sqlite3.Error, ValueError, OverflowError):
+ return None
+ finally:
+ connection.close()
diff --git a/packages/server/src/repowise/server/mcp_server/_savings/event.py b/packages/server/src/repowise/server/mcp_server/_savings/event.py
index e89479a09..f7c1c252f 100644
--- a/packages/server/src/repowise/server/mcp_server/_savings/event.py
+++ b/packages/server/src/repowise/server/mcp_server/_savings/event.py
@@ -120,6 +120,7 @@ def record(interaction: Interaction, result: Any) -> bool:
def _record(interaction: Interaction, result: Any) -> bool:
from repowise.core.savings import recorder
+ from repowise.core.savings.pricing import resolve_pricing_snapshot
from .wrapper import response_tokens
@@ -130,6 +131,16 @@ def _record(interaction: Interaction, result: Any) -> bool:
result_state, is_usable = _outcome(result)
baseline = interaction.baseline_input_tokens
inferred = baseline is not None
+ # The rate this saving is worth, frozen now so a later price change cannot
+ # rewrite it -- but read from cache only, never resolved here. Detecting the
+ # agent's model scans the local transcripts, which measures around six
+ # seconds on a repository with no Codex history, and this runs inside the
+ # agent's own tool call. Once a day is still far too often to stall one.
+ #
+ # So the tool call takes an unpriced event and `repowise distill` or
+ # `repowise saved` fills the cache; the report counts priced and unpriced
+ # tokens separately for exactly this reason.
+ pricing = resolve_pricing_snapshot(interaction.repo_root, allow_scan=False)
payload: dict[str, Any] = {
"event_id": interaction.event_id,
@@ -155,6 +166,7 @@ def _record(interaction: Interaction, result: Any) -> bool:
"delivered_input_tokens": delivered,
"omission_refs": _omission_refs(result),
"metadata": interaction.identity_metadata or None,
+ **(pricing.as_payload() if pricing else {}),
}
return recorder.record_event(interaction.repo_root, payload)
diff --git a/packages/server/src/repowise/server/routers/costs.py b/packages/server/src/repowise/server/routers/costs.py
index b1e11a27b..419adab06 100644
--- a/packages/server/src/repowise/server/routers/costs.py
+++ b/packages/server/src/repowise/server/routers/costs.py
@@ -2,9 +2,10 @@
from __future__ import annotations
-import sqlite3
-from datetime import date, datetime
+from collections.abc import Iterable, Mapping
+from datetime import UTC, date, datetime
from pathlib import Path
+from typing import Any
import sqlalchemy as sa
from fastapi import APIRouter, Depends, HTTPException, Query
@@ -16,9 +17,10 @@ from repowise.server.deps import get_db_session, verify_api_key
from repowise.server.schemas import (
CostGroupResponse,
CostSummaryResponse,
- DistillSavingsGroup,
- DistillSavingsResponse,
- McpDropGroup,
+ SavingsAgentRow,
+ SavingsBreakdownRow,
+ SavingsOpportunityRow,
+ SavingsResponse,
)
router = APIRouter(
@@ -28,15 +30,6 @@ router = APIRouter(
)
-#: Output tokens credited per answered counterfactual MCP query. Each curated
-#: answer stands in for at least one raw exploration tool call the agent never
-#: had to emit (README markets "-70% tool calls"), and that invocation is output
-#: tokens we otherwise ignore. Deliberately one avoided call's worth (~a tool_use
-#: block), not the several reads a single answer often replaces, so the credit
-#: stays an undersell; priced at the agent's output rate below.
-_AVOIDED_CALL_OUTPUT_TOKENS = 60
-
-
def _parse_since(since: str | None) -> datetime | None:
"""Parse an ISO date string (YYYY-MM-DD) into a datetime, or return None."""
if since is None:
@@ -128,105 +121,79 @@ async def list_costs(
]
[email protected]("/{repo_id}/distill-savings", response_model=DistillSavingsResponse)
-async def get_distill_savings(
[email protected]("/{repo_id}/savings", response_model=SavingsResponse)
+async def get_savings(
repo_id: str,
- since: str | None = Query(None, description="ISO date filter, e.g. 2025-01-01"),
+ # Bounded, not just non-negative: a large enough value overflows the
+ # timedelta the report subtracts, and a decade already means "all time"
+ # for a ledger this young.
+ days: int | None = Query(
+ None, ge=0, le=3_650, description="Window in days; omit for all time"
+ ),
session: AsyncSession = Depends(get_db_session),
-) -> DistillSavingsResponse:
- """Savings rollup from the repo's omission store sidecar.
+) -> SavingsResponse:
+ """What agents avoided in this repository, from the canonical ledger.
- Combines the ``repowise distill`` ledger with the MCP truncation drops
- already on disk (``source='mcp:*'``), priced at the coding agent's detected
- model. Returns ``available=False`` when the repo has no omission store.
+ Reads through the one core report service, so this endpoint, the
+ repository overview headline and ``repowise saved`` report the same
+ numbers by construction rather than by three implementations agreeing.
+
+ The transcript miners below are *observed opportunities* -- things that
+ could have been saved and were not. They are reported beside the achieved
+ savings and never added to them.
"""
repo = await crud.get_repository(session, repo_id)
if repo is None:
raise HTTPException(status_code=404, detail="Repository not found")
if not repo.local_path:
- return DistillSavingsResponse(available=False)
+ return SavingsResponse(available=False)
- db_path = Path(repo.local_path) / ".repowise" / "omissions" / "omissions.db"
- if not db_path.is_file():
- return DistillSavingsResponse(available=False)
+ from repowise.core.savings.service import load_report
- since_dt = _parse_since(since)
- since_ts = since_dt.timestamp() if since_dt is not None else None
+ as_of = datetime.now(UTC)
+ report = load_report(repo.local_path, as_of=as_of, days=days)
+ if report is None:
+ return SavingsResponse(available=False)
- from repowise.core.distill import tracking
- from repowise.core.distill.session_model import resolve_session_model
- from repowise.core.generation.cost_tracker import get_model_pricing
-
- # Read-only stdlib sqlite3 on the sidecar: tiny aggregate queries, and a
- # ro handle never contends with hook/CLI writers.
- try:
- conn = sqlite3.connect(f"file:{db_path.as_posix()}?mode=ro", uri=True, timeout=1)
- except sqlite3.Error:
- return DistillSavingsResponse(available=False)
- try:
- # Distill figures exclude the ``mcp:*`` counterfactual rows Phase 2 now
- # writes into the same ledger; the MCP block reports those separately.
- summary = tracking.distill_summary(conn, since=since_ts)
- per_day = tracking.savings_rollup(conn, by="day", since=since_ts)
- # Unified MCP view: counterfactual ledger merged with truncation drops,
- # counterfactual taking precedence per tool (no double counting).
- mcp = tracking.mcp_savings_summary(conn, since=since_ts)
- except sqlite3.Error:
- return DistillSavingsResponse(available=False)
- finally:
- conn.close()
-
- per_filter = [{"group": name, **stats} for name, stats in summary["per_filter"].items()]
-
- # Missed savings: best-effort scan of local agent transcripts; the module
- # degrades to an empty report on any failure, never raises.
+ # Best-effort transcript scans; both degrade to an empty report and never
+ # raise. Kept out of the ledger entirely -- they are estimates of what was
+ # not saved, and the contract says those never enter the headline.
from repowise.core.distill.missed import scan_missed_savings
from repowise.core.distill.missed_mcp import scan_missed_mcp_savings
missed = scan_missed_savings(Path(repo.local_path))
reread = scan_missed_mcp_savings(Path(repo.local_path))
- # Price at the coding agent's actual model — saved tokens are input tokens
- # that agent never had to read. Detection is best-effort (sonnet default).
- resolved = resolve_session_model(Path(repo.local_path))
- pricing = get_model_pricing(resolved.model)
- total_saved = summary["saved_tokens"] + mcp["tokens"]
- input_usd = total_saved * pricing["input"] / 1_000_000
- # Add a small credit for the tool-call output the agent never had to emit:
- # every answered counterfactual MCP query replaced at least one raw
- # exploration call. Priced at the output rate; see _AVOIDED_CALL_OUTPUT_TOKENS.
- # Counted over net-positive counterfactual rows only — a dead-end (error)
- # call is recorded as a debit and saved the agent nothing, so crediting its
- # output would flip that debit into a credit.
- avoided_calls = sum(
- row["events"]
- for row in mcp["per_tool"]
- if row.get("kind") == "counterfactual" and row.get("tokens", 0) > 0
- )
- output_usd = avoided_calls * _AVOIDED_CALL_OUTPUT_TOKENS * pricing["output"] / 1_000_000
- return DistillSavingsResponse(
+ return SavingsResponse(
available=True,
- events=summary["events"],
- raw_tokens=summary["raw_tokens"],
- distilled_tokens=summary["distilled_tokens"],
- saved_tokens=summary["saved_tokens"],
- estimated_usd_saved=input_usd + output_usd,
- pricing_model=resolved.model,
- pricing_agent=resolved.agent,
- pricing_source=resolved.source,
- per_filter=[DistillSavingsGroup(**row) for row in per_filter],
- per_day=[DistillSavingsGroup(**row) for row in per_day],
- mcp_events=mcp["events"],
- mcp_tokens=mcp["tokens"],
- mcp_queries=mcp["queries"],
- mcp_per_tool=[
- McpDropGroup(
- tool=row["tool"],
- events=row["events"],
- tokens=row["tokens"],
- kind=row["kind"],
- )
- for row in mcp["per_tool"]
+ window_days=days,
+ as_of=as_of.isoformat(),
+ first_event_at=report.first_event_at,
+ last_event_at=report.last_event_at,
+ unique_events=report.unique_events,
+ successful_or_usable_partial_events=report.successful_or_usable_partial_events,
+ saving_interactions=report.saving_interactions,
+ mcp_queries_answered=report.mcp_queries_answered,
+ dead_ends=report.dead_ends,
+ saved_input_tokens=report.saved_input_tokens,
+ measured_saved_input_tokens=report.measured_saved_input_tokens,
+ inferred_saved_input_tokens=report.inferred_saved_input_tokens,
+ priced_saved_input_tokens=report.priced_saved_input_tokens,
+ unpriced_saved_input_tokens=report.unpriced_saved_input_tokens,
+ priced_input_savings_usd=report.priced_input_savings_usd,
+ saved_output_tokens=report.saved_output_tokens,
+ priced_saved_output_tokens=report.priced_saved_output_tokens,
+ unpriced_saved_output_tokens=report.unpriced_saved_output_tokens,
+ priced_output_savings_usd=report.priced_output_savings_usd,
+ per_operation=_breakdown(report.per_operation, "operation"),
+ per_surface=_breakdown(report.per_surface, "surface"),
+ per_agent=[SavingsAgentRow(**row) for row in report.per_agent],
+ per_model=_breakdown(report.per_model, "model"),
+ per_day=_breakdown(report.per_day, "day"),
+ opportunity_count=report.opportunity_count,
+ opportunity_tokens_excluded=report.opportunity_tokens_excluded,
+ per_opportunity_kind=[
+ SavingsOpportunityRow(**row) for row in report.per_opportunity_kind
],
missed_events=missed["events"],
missed_tokens_est=missed["est_saved_tokens"],
@@ -234,3 +201,19 @@ async def get_distill_savings(
reread_events=reread["events"],
reread_tokens_est=reread["est_saved_tokens"],
)
+
+
+def _breakdown(rows: Iterable[Mapping[str, Any]], key: str) -> list[SavingsBreakdownRow]:
+ """Map one core breakdown onto the wire row, renaming its group column.
+
+ The core report names each bucket after what it groups by; the wire uses
+ one row shape so a client needs one renderer rather than five.
+ """
+ return [
+ SavingsBreakdownRow(
+ group=None if row[key] is None else str(row[key]),
+ events=row["events"],
+ saved_input_tokens=row["saved_input_tokens"],
+ )
+ for row in rows
+ ]
diff --git a/packages/server/src/repowise/server/routers/overview.py b/packages/server/src/repowise/server/routers/overview.py
index fe3847145..fe2714cdf 100644
--- a/packages/server/src/repowise/server/routers/overview.py
+++ b/packages/server/src/repowise/server/routers/overview.py
@@ -12,7 +12,6 @@ from __future__ import annotations
import configparser
import contextlib
import json
-import sqlite3
from pathlib import Path
from typing import Any
@@ -134,44 +133,36 @@ def _decision_slim(d: Any) -> dict:
async def _savings_headline(repo_local_path: str | None) -> dict:
- """Distill + MCP savings totals from the omission-store sidecar.
+ """Savings headline for the overview, from the one core report service.
- Headline numbers only — no per-day rollups, no transcript scan (the
- missed-savings scan reads agent transcripts and is too slow for an
- overview payload). Mirrors /distill-savings semantics otherwise.
+ Headline figures only -- no breakdowns and no transcript scan, which reads
+ agent transcripts and is far too slow for an overview payload. Every field
+ here comes from the same report the savings endpoint and ``repowise saved``
+ read, so the three cannot drift. They previously did, in four separate
+ ways, because each aggregated and priced the ledger for itself.
+
+ The measured/inferred and priced/unpriced splits travel beside the total on
+ purpose. A lone headline reads as one confident number, and the evidence
+ behind it is not uniform.
"""
if not repo_local_path:
return {"available": False}
- db_path = Path(repo_local_path) / ".repowise" / "omissions" / "omissions.db"
- if not db_path.is_file():
- return {"available": False}
- from repowise.core.distill import tracking
- from repowise.core.distill.session_model import resolve_session_model
- from repowise.core.generation.cost_tracker import get_model_pricing
+ from repowise.core.savings.service import load_report
- try:
- conn = sqlite3.connect(f"file:{db_path.as_posix()}?mode=ro", uri=True, timeout=1)
- except sqlite3.Error:
+ report = load_report(repo_local_path)
+ if report is None:
return {"available": False}
- try:
- summary = tracking.distill_summary(conn, since=None)
- mcp = tracking.mcp_savings_summary(conn, since=None)
- except sqlite3.Error:
- return {"available": False}
- finally:
- conn.close()
-
- resolved = resolve_session_model(Path(repo_local_path))
- rate = get_model_pricing(resolved.model)["input"]
- total_saved = summary["saved_tokens"] + mcp["tokens"]
return {
"available": True,
- "saved_tokens": summary["saved_tokens"],
- "mcp_tokens": mcp["tokens"],
- "total_saved_tokens": total_saved,
- "estimated_usd_saved": total_saved * rate / 1_000_000,
- "pricing_model": resolved.model,
+ "saved_input_tokens": report.saved_input_tokens,
+ "measured_saved_input_tokens": report.measured_saved_input_tokens,
+ "inferred_saved_input_tokens": report.inferred_saved_input_tokens,
+ "priced_saved_input_tokens": report.priced_saved_input_tokens,
+ "unpriced_saved_input_tokens": report.unpriced_saved_input_tokens,
+ "estimated_usd_saved": report.priced_input_savings_usd,
+ "mcp_queries_answered": report.mcp_queries_answered,
+ "last_event_at": report.last_event_at,
}
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
index f33e5f8c6..7df9b874e 100644
--- a/packages/server/src/repowise/server/schemas/__init__.py
+++ b/packages/server/src/repowise/server/schemas/__init__.py
@@ -238,13 +238,14 @@ from .ui_helpers import (
ActiveProviderSelection,
CostGroupResponse,
CostSummaryResponse,
- DistillSavingsGroup,
- DistillSavingsResponse,
- McpDropGroup,
OkResponse,
ProviderEntry,
ProviderStatusResponse,
ProviderValidationResponse,
+ SavingsAgentRow,
+ SavingsBreakdownRow,
+ SavingsOpportunityRow,
+ SavingsResponse,
SetActiveProviderRequest,
SetApiKeyRequest,
WebhookResponse,
@@ -383,8 +384,6 @@ __all__ = [
"DecisionStatusUpdate",
"DependencyPathResponse",
"DirectRiskEntry",
- "DistillSavingsGroup",
- "DistillSavingsResponse",
"DocDriftDocumentDriftResponse",
"DocDriftFindingResponse",
"DocDriftReferenceResponse",
@@ -431,7 +430,6 @@ __all__ = [
"KnowledgeMapResponse",
"KnowledgeMapSilo",
"KnowledgeMapTarget",
- "McpDropGroup",
"McpToolInfo",
"McpToolSurfaceResponse",
"ModuleEdgeResponse",
@@ -476,6 +474,10 @@ __all__ = [
"RiskDriverResponse",
"RiskHistogramBucket",
"RiskRangeResponse",
+ "SavingsAgentRow",
+ "SavingsBreakdownRow",
+ "SavingsOpportunityRow",
+ "SavingsResponse",
"SearchRequest",
"SearchResultResponse",
"SecurityFindingResponse",
diff --git a/packages/server/src/repowise/server/schemas/ui_helpers.py b/packages/server/src/repowise/server/schemas/ui_helpers.py
index 69b0500de..675c7f29d 100644
--- a/packages/server/src/repowise/server/schemas/ui_helpers.py
+++ b/packages/server/src/repowise/server/schemas/ui_helpers.py
@@ -85,67 +85,96 @@ class CostSummaryResponse(BaseModel):
since: str | None
-class DistillSavingsGroup(BaseModel):
- group: str
- events: int
- raw_tokens: int
- distilled_tokens: int
- saved_tokens: int
+class SavingsBreakdownRow(BaseModel):
+ """One bucket of a savings breakdown.
+
+ ``group`` is nullable because one bucket genuinely has no name: an event
+ written before its rate could be resolved has no model, and that is a real
+ quantity -- how much saving carries no pricing evidence -- rather than a
+ gap to drop from the list.
+ """
+ group: str | None = None
+ events: int = 0
+ saved_input_tokens: int = 0
-class McpDropGroup(BaseModel):
- """Per-tool MCP savings (``tool`` with the ``mcp:`` prefix stripped).
- ``kind`` distinguishes a ``"counterfactual"`` saving (the answer replaced raw
- file exploration — recorded in the savings ledger) from a ``"truncation"``
- drop (content trimmed past the response budget — the only signal for tools
- without a counterfactual estimator yet).
- """
+class SavingsAgentRow(BaseModel):
+ """One agent's savings, labelled from the identity registry."""
+
+ agent: str
+ agent_display_name: str | None = None
+ events: int = 0
+ saved_input_tokens: int = 0
+
+
+class SavingsOpportunityRow(BaseModel):
+ """One kind of observed opportunity. Never part of achieved savings."""
- tool: str
- events: int
- tokens: int
- kind: str = "truncation"
+ kind: str
+ observations: int = 0
+ estimated_potential_input_tokens: int = 0
-class DistillSavingsResponse(BaseModel):
- """Savings rollup for the Costs page hero card.
+class SavingsResponse(BaseModel):
+ """What agents avoided in one repository over one window.
- The ``distill`` block (``saved_tokens`` etc.) covers the ``repowise
- distill`` command/hook path. The ``mcp`` block surfaces tokens already
- dropped past MCP response budgets (the ``omissions`` store), which the
- distill ledger never recorded. Savings are priced at the *coding agent's*
- detected model (``pricing_model`` / ``pricing_agent`` / ``pricing_source``)
- — they are input tokens that agent never had to read. ``available`` is
- False when the repo has no omission store on disk (feature unused).
+ Every figure comes from the canonical savings ledger through the one core
+ report service, so this response, the repository overview headline and
+ ``repowise saved`` cannot disagree -- which the three of them did, in four
+ separate ways, when each aggregated and priced the ledger for itself.
+
+ Three things it deliberately keeps apart. *Measured* reductions are known
+ before/after sizes from an operation that really ran; *inferred* avoidance
+ is a documented counterfactual. *Priced* and *unpriced* tokens are split
+ because an event records the rate it was worth at the time and some events
+ carry none, and reporting a total as though it were all priced would be a
+ guess. *Observed opportunities* are things that could have been saved and
+ were not: they never enter the headline.
+
+ ``available`` is False when the repository has no savings sidecar at all,
+ which means "nothing has been measured here" and is different from a
+ measured zero.
"""
available: bool
- events: int = 0
- raw_tokens: int = 0
- distilled_tokens: int = 0
- saved_tokens: int = 0
- estimated_usd_saved: float = 0.0
- pricing_model: str = ""
- # How the pricing model was resolved (Phase 1 model-aware pricing).
- pricing_agent: str = "unknown"
- pricing_source: str = "default"
- per_filter: list[DistillSavingsGroup] = []
- per_day: list[DistillSavingsGroup] = []
- # Unified MCP savings: counterfactual ledger rows (each answer replaced raw
- # file exploration) merged with truncation drops for tools that have no
- # counterfactual estimator. ``mcp_queries`` counts counterfactual tool calls
- # ("N MCP queries answered"); ``mcp_tokens`` is total saved.
- mcp_events: int = 0
- mcp_tokens: int = 0
- mcp_queries: int = 0
- mcp_per_tool: list[McpDropGroup] = []
- # Missed savings — raw (non-distilled) agent commands a filter would have
- # caught, scanned best-effort from local Claude Code transcripts.
+ #: Window the figures cover; null means all time.
+ window_days: int | None = None
+ as_of: str = ""
+ first_event_at: str | None = None
+ last_event_at: str | None = None
+
+ unique_events: int = 0
+ successful_or_usable_partial_events: int = 0
+ saving_interactions: int = 0
+ mcp_queries_answered: int = 0
+ dead_ends: int = 0
+
+ saved_input_tokens: int = 0
+ measured_saved_input_tokens: int = 0
+ inferred_saved_input_tokens: int = 0
+ priced_saved_input_tokens: int = 0
+ unpriced_saved_input_tokens: int = 0
+ priced_input_savings_usd: float = 0.0
+ saved_output_tokens: int | None = None
+ priced_saved_output_tokens: int = 0
+ unpriced_saved_output_tokens: int = 0
+ priced_output_savings_usd: float = 0.0
+
+ per_operation: list[SavingsBreakdownRow] = []
+ per_surface: list[SavingsBreakdownRow] = []
+ per_agent: list[SavingsAgentRow] = []
+ per_model: list[SavingsBreakdownRow] = []
+ per_day: list[SavingsBreakdownRow] = []
+
+ #: Recorded opportunities (a hook replacement that was declined, say).
+ opportunity_count: int = 0
+ opportunity_tokens_excluded: int = 0
+ per_opportunity_kind: list[SavingsOpportunityRow] = []
+ #: Transcript-mined opportunities: raw commands a filter would have caught,
+ #: and full re-reads of unchanged files. Estimates of what was *not* saved.
missed_events: int = 0
missed_tokens_est: int = 0
missed_window_days: float = 0.0
- # Missed MCP savings — full re-reads of unchanged files a targeted
- # get_symbol / range read would have replaced, same transcript scan.
reread_events: int = 0
reread_tokens_est: int = 0
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 6f77eb166..548f0e2e8 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -985,48 +985,6 @@ export interface DirectRiskEntry {
centrality: number;
}
-export interface DistillSavingsGroup {
- group: string;
- events: number;
- raw_tokens: number;
- distilled_tokens: number;
- saved_tokens: number;
-}
-
-/**
- * Savings rollup for the Costs page hero card.
- *
- * The ``distill`` block (``saved_tokens`` etc.) covers the ``repowise
- * distill`` command/hook path. The ``mcp`` block surfaces tokens already
- * dropped past MCP response budgets (the ``omissions`` store), which the
- * distill ledger never recorded. Savings are priced at the *coding agent's*
- * detected model (``pricing_model`` / ``pricing_agent`` / ``pricing_source``)
- * — they are input tokens that agent never had to read. ``available`` is
- * False when the repo has no omission store on disk (feature unused).
- */
-export interface DistillSavingsResponse {
- available: boolean;
- events?: number;
- raw_tokens?: number;
- distilled_tokens?: number;
- saved_tokens?: number;
- estimated_usd_saved?: number;
- pricing_model?: string;
- pricing_agent?: string;
- pricing_source?: string;
- per_filter?: DistillSavingsGroup[];
- per_day?: DistillSavingsGroup[];
- mcp_events?: number;
- mcp_tokens?: number;
- mcp_queries?: number;
- mcp_per_tool?: McpDropGroup[];
- missed_events?: number;
- missed_tokens_est?: number;
- missed_window_days?: number;
- reread_events?: number;
- reread_tokens_est?: number;
-}
-
/**
* A naming document that carries drift somewhere in it.
*
@@ -1825,21 +1783,6 @@ export interface KnowledgeMapTarget {
doc_words: number;
}
-/**
- * Per-tool MCP savings (``tool`` with the ``mcp:`` prefix stripped).
- *
- * ``kind`` distinguishes a ``"counterfactual"`` saving (the answer replaced raw
- * file exploration — recorded in the savings ledger) from a ``"truncation"``
- * drop (content trimmed past the response budget — the only signal for tools
- * without a counterfactual estimator yet).
- */
-export interface McpDropGroup {
- tool: string;
- events: number;
- tokens: number;
- kind?: string;
-}
-
/** One tool in the configurable surface, with the flags a UI needs. */
export interface McpToolInfo {
name: string;
@@ -2517,6 +2460,91 @@ export interface RiskScaleRange {
maximum: number | null;
}
+/** One agent's savings, labelled from the identity registry. */
+export interface SavingsAgentRow {
+ agent: string;
+ agent_display_name?: string | null;
+ events?: number;
+ saved_input_tokens?: number;
+}
+
+/**
+ * One bucket of a savings breakdown.
+ *
+ * ``group`` is nullable because one bucket genuinely has no name: an event
+ * written before its rate could be resolved has no model, and that is a real
+ * quantity -- how much saving carries no pricing evidence -- rather than a
+ * gap to drop from the list.
+ */
+export interface SavingsBreakdownRow {
+ group?: string | null;
+ events?: number;
+ saved_input_tokens?: number;
+}
+
+/** One kind of observed opportunity. Never part of achieved savings. */
+export interface SavingsOpportunityRow {
+ kind: string;
+ observations?: number;
+ estimated_potential_input_tokens?: number;
+}
+
+/**
+ * What agents avoided in one repository over one window.
+ *
+ * Every figure comes from the canonical savings ledger through the one core
+ * report service, so this response, the repository overview headline and
+ * ``repowise saved`` cannot disagree -- which the three of them did, in four
+ * separate ways, when each aggregated and priced the ledger for itself.
+ *
+ * Three things it deliberately keeps apart. *Measured* reductions are known
+ * before/after sizes from an operation that really ran; *inferred* avoidance
+ * is a documented counterfactual. *Priced* and *unpriced* tokens are split
+ * because an event records the rate it was worth at the time and some events
+ * carry none, and reporting a total as though it were all priced would be a
+ * guess. *Observed opportunities* are things that could have been saved and
+ * were not: they never enter the headline.
+ *
+ * ``available`` is False when the repository has no savings sidecar at all,
+ * which means "nothing has been measured here" and is different from a
+ * measured zero.
+ */
+export interface SavingsResponse {
+ available: boolean;
+ window_days?: number | null;
+ as_of?: string;
+ first_event_at?: string | null;
+ last_event_at?: string | null;
+ unique_events?: number;
+ successful_or_usable_partial_events?: number;
+ saving_interactions?: number;
+ mcp_queries_answered?: number;
+ dead_ends?: number;
+ saved_input_tokens?: number;
+ measured_saved_input_tokens?: number;
+ inferred_saved_input_tokens?: number;
+ priced_saved_input_tokens?: number;
+ unpriced_saved_input_tokens?: number;
+ priced_input_savings_usd?: number;
+ saved_output_tokens?: number | null;
+ priced_saved_output_tokens?: number;
+ unpriced_saved_output_tokens?: number;
+ priced_output_savings_usd?: number;
+ per_operation?: SavingsBreakdownRow[];
+ per_surface?: SavingsBreakdownRow[];
+ per_agent?: SavingsAgentRow[];
+ per_model?: SavingsBreakdownRow[];
+ per_day?: SavingsBreakdownRow[];
+ opportunity_count?: number;
+ opportunity_tokens_excluded?: number;
+ per_opportunity_kind?: SavingsOpportunityRow[];
+ missed_events?: number;
+ missed_tokens_est?: number;
+ missed_window_days?: number;
+ reread_events?: number;
+ reread_tokens_est?: number;
+}
+
export interface SearchResultResponse {
page_id: string;
title: string;
diff --git a/packages/types/src/overview.ts b/packages/types/src/overview.ts
index 79ae0188a..9f5407ef5 100644
--- a/packages/types/src/overview.ts
+++ b/packages/types/src/overview.ts
@@ -132,13 +132,27 @@ export interface OverviewDecisionSlim {
staleness_score: number;
}
+/**
+ * The savings headline on the overview payload.
+ *
+ * A strict subset of the full savings report, from the same core report
+ * service, so the overview and the Costs page cannot disagree. The
+ * measured/inferred and priced/unpriced splits travel with the total because a
+ * lone headline reads as one confident number and the evidence is not uniform.
+ *
+ * `available: false` means nothing has been measured in this repository, which
+ * is not the same as a measured zero.
+ */
export interface OverviewSavings {
available: boolean;
- saved_tokens?: number;
- mcp_tokens?: number;
- total_saved_tokens?: number;
+ saved_input_tokens?: number;
+ measured_saved_input_tokens?: number;
+ inferred_saved_input_tokens?: number;
+ priced_saved_input_tokens?: number;
+ unpriced_saved_input_tokens?: number;
estimated_usd_saved?: number;
- pricing_model?: string;
+ mcp_queries_answered?: number;
+ last_event_at?: string | null;
}
export interface OverviewSyncStatus {
diff --git a/packages/ui/__tests__/costs/distill-savings-card.test.tsx b/packages/ui/__tests__/costs/distill-savings-card.test.tsx
deleted file mode 100644
index 9eb990a2a..000000000
--- a/packages/ui/__tests__/costs/distill-savings-card.test.tsx
+++ /dev/null
@@ -1,97 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { render, screen } from "@testing-library/react";
-import {
- DistillSavingsCard,
- type DistillSavingsData,
-} from "../../src/costs/distill-savings-card";
-
-function makeData(overrides: Partial<DistillSavingsData> = {}): DistillSavingsData {
- return {
- available: true,
- events: 12,
- raw_tokens: 70_000,
- distilled_tokens: 5_000,
- saved_tokens: 65_000,
- estimated_usd_saved: 1.5,
- pricing_model: "claude-opus-4-8",
- pricing_agent: "claude_code",
- pricing_source: "detected from Claude Code session",
- per_filter: [
- { group: "git_log", events: 1, raw_tokens: 31_000, distilled_tokens: 500, saved_tokens: 30_500 },
- ],
- per_day: [],
- mcp_events: 5,
- mcp_tokens: 39_000,
- mcp_per_tool: [
- { tool: "get_risk", events: 3, tokens: 29_000 },
- { tool: "get_dead_code", events: 1, tokens: 7_000 },
- ],
- missed_events: 0,
- missed_tokens_est: 0,
- missed_window_days: 7,
- ...overrides,
- };
-}
-
-describe("DistillSavingsCard", () => {
- it("shows the hero total as distill + mcp saved tokens", () => {
- render(<DistillSavingsCard data={makeData()} />);
- // 65K + 39K = 104K → formatTokens → "104K"
- expect(screen.getByText("104K")).toBeInTheDocument();
- expect(screen.getByText(/priced at Claude Code/)).toBeInTheDocument();
- });
-
- it("breaks savings down by surface", () => {
- render(<DistillSavingsCard data={makeData()} />);
- expect(screen.getByText("Distill — by filter")).toBeInTheDocument();
- expect(screen.getByText("MCP — by tool")).toBeInTheDocument();
- expect(screen.getByText("get_risk")).toBeInTheDocument();
- });
-
- it("renders the missed-as-opportunity CTA with a docs link", () => {
- render(
- <DistillSavingsCard
- data={makeData({ missed_events: 193, missed_tokens_est: 74_000 })}
- />,
- );
- expect(screen.getByText(/Unlock ~74K more/)).toBeInTheDocument();
- const link = screen.getByRole("link");
- expect(link).toHaveAttribute("href", expect.stringContaining("DISTILL.md"));
- });
-
- it("frames MCP savings as queries answered when counterfactuals exist", () => {
- render(
- <DistillSavingsCard
- data={makeData({
- mcp_queries: 8,
- mcp_per_tool: [
- { tool: "get_context", events: 6, tokens: 30_000, kind: "counterfactual" },
- { tool: "get_risk", events: 2, tokens: 9_000, kind: "truncation" },
- ],
- })}
- />,
- );
- expect(screen.getByText(/8 queries answered/)).toBeInTheDocument();
- });
-
- it("falls back to the drop count when no counterfactual queries exist", () => {
- render(<DistillSavingsCard data={makeData({ mcp_queries: 0 })} />);
- expect(screen.getByText(/5 drops/)).toBeInTheDocument();
- });
-
- it("shows the empty state when nothing is saved", () => {
- render(<DistillSavingsCard data={makeData({ available: false, saved_tokens: 0, mcp_tokens: 0 })} />);
- expect(screen.getByText(/No agent token savings recorded yet/)).toBeInTheDocument();
- });
-
- it("renders MCP-only savings even with no distill events", () => {
- render(
- <DistillSavingsCard
- data={makeData({ events: 0, saved_tokens: 0, per_filter: [] })}
- />,
- );
- // 0 + 39K = 39K total (hero) — also appears as the MCP sub-stat, so match
- // at least one occurrence rather than asserting uniqueness.
- expect(screen.getAllByText("39K").length).toBeGreaterThanOrEqual(1);
- });
-});
diff --git a/packages/ui/__tests__/costs/savings-card.test.tsx b/packages/ui/__tests__/costs/savings-card.test.tsx
new file mode 100644
index 000000000..10dd8897a
--- /dev/null
+++ b/packages/ui/__tests__/costs/savings-card.test.tsx
@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { SavingsCard, type SavingsData } from "../../src/costs/savings-card";
+
+function makeData(overrides: Partial<SavingsData> = {}): SavingsData {
+ return {
+ available: true,
+ unique_events: 12,
+ mcp_queries_answered: 8,
+ saved_input_tokens: 104_000,
+ measured_saved_input_tokens: 65_000,
+ inferred_saved_input_tokens: 39_000,
+ priced_saved_input_tokens: 104_000,
+ unpriced_saved_input_tokens: 0,
+ priced_input_savings_usd: 1.5,
+ per_operation: [
+ { group: "git_log", events: 1, saved_input_tokens: 30_500 },
+ { group: "get_risk", events: 3, saved_input_tokens: 29_000 },
+ ],
+ per_surface: [
+ { group: "distill", events: 7, saved_input_tokens: 65_000 },
+ { group: "mcp", events: 5, saved_input_tokens: 39_000 },
+ ],
+ per_agent: [
+ { agent: "claude_code", agent_display_name: "Claude Code", events: 12, saved_input_tokens: 104_000 },
+ ],
+ missed_events: 0,
+ missed_tokens_est: 0,
+ missed_window_days: 7,
+ ...overrides,
+ };
+}
+
+describe("SavingsCard", () => {
+ it("shows the canonical total as the hero figure", () => {
+ render(<SavingsCard data={makeData()} />);
+ expect(screen.getByText("104K")).toBeInTheDocument();
+ });
+
+ it("calls the total estimated while any of it is inferred", () => {
+ render(<SavingsCard data={makeData()} />);
+ expect(screen.getByText(/Estimated agent savings/)).toBeInTheDocument();
+ });
+
+ it("drops the estimated framing when every token is measured", () => {
+ render(
+ <SavingsCard
+ data={makeData({
+ measured_saved_input_tokens: 104_000,
+ inferred_saved_input_tokens: 0,
+ })}
+ />,
+ );
+ expect(screen.getByText(/Tokens saved for your agent/)).toBeInTheDocument();
+ expect(screen.queryByText(/Estimated agent savings/)).not.toBeInTheDocument();
+ });
+
+ it("keeps the measured and inferred split legible", () => {
+ render(<SavingsCard data={makeData()} />);
+ // Both words also appear in the methodology note, so this asserts they are
+ // present at all rather than that they appear exactly once.
+ expect(screen.getAllByText(/Measured/).length).toBeGreaterThanOrEqual(1);
+ expect(screen.getAllByText(/Inferred/).length).toBeGreaterThanOrEqual(1);
+ // The legend carries the actual split, not just the labels.
+ expect(screen.getByText("65K")).toBeInTheDocument();
+ expect(screen.getByText("39K")).toBeInTheDocument();
+ });
+
+ it("says how much of the total the dollar figure covers when some is unpriced", () => {
+ render(
+ <SavingsCard
+ data={makeData({
+ priced_saved_input_tokens: 64_000,
+ unpriced_saved_input_tokens: 40_000,
+ })}
+ />,
+ );
+ expect(screen.getByText(/priced on 64K of 104K tokens/)).toBeInTheDocument();
+ });
+
+ it("breaks savings down by surface and operation", () => {
+ render(<SavingsCard data={makeData()} />);
+ expect(screen.getByText("By surface")).toBeInTheDocument();
+ expect(screen.getByText("By operation")).toBeInTheDocument();
+ // Surface slugs are rendered as words, not as identifiers.
+ expect(screen.getByText("Distill")).toBeInTheDocument();
+ expect(screen.getByText("MCP")).toBeInTheDocument();
+ expect(screen.getByText("get_risk")).toBeInTheDocument();
+ });
+
+ it("labels a null breakdown group rather than rendering an empty row", () => {
+ render(
+ <SavingsCard
+ data={makeData({
+ per_surface: [{ group: null, events: 1, saved_input_tokens: 104_000 }],
+ })}
+ />,
+ );
+ expect(screen.getAllByText("Unknown").length).toBeGreaterThanOrEqual(1);
+ });
+
+ it("presents a missed scan as an observed opportunity, not as a saving", () => {
+ render(<SavingsCard data={makeData({ missed_events: 193, missed_tokens_est: 74_000 })} />);
+ expect(screen.getByText(/Observed opportunity: ~74K/)).toBeInTheDocument();
+ // The headline is untouched by what was not saved.
+ expect(screen.getByText("104K")).toBeInTheDocument();
+ });
+
+ it("gives the opportunity a plain guidance link rather than a fake action", () => {
+ render(<SavingsCard data={makeData({ missed_events: 193, missed_tokens_est: 74_000 })} />);
+ const link = screen.getByRole("link", { name: /distillation setup guide/i });
+ expect(link).toHaveAttribute("href", expect.stringContaining("DISTILL.md"));
+ });
+
+ it("reports a re-read as observed rather than as certainly replaceable", () => {
+ render(<SavingsCard data={makeData({ reread_events: 5, reread_tokens_est: 635 })} />);
+ // Hedged both ways: "potentially avoid", and "were observed" rather than a
+ // claim that get_symbol would have replaced them.
+ expect(screen.getByText(/Potentially avoid ~635/)).toBeInTheDocument();
+ expect(screen.getByText(/were observed/)).toBeInTheDocument();
+ });
+
+ it("shows the empty state when nothing is saved", () => {
+ render(<SavingsCard data={makeData({ available: false, saved_input_tokens: 0 })} />);
+ expect(screen.getByText(/No agent token savings recorded yet/)).toBeInTheDocument();
+ });
+
+ it("renders a skeleton rather than a zero while loading", () => {
+ render(<SavingsCard />);
+ expect(screen.queryByText("104K")).not.toBeInTheDocument();
+ expect(screen.queryByText(/No agent token savings recorded yet/)).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/ui/src/costs/index.ts b/packages/ui/src/costs/index.ts
index 2ea766559..97ae3df4e 100644
--- a/packages/ui/src/costs/index.ts
+++ b/packages/ui/src/costs/index.ts
@@ -6,13 +6,13 @@ export { CostHeatmap } from "./cost-heatmap";
export type { CostHeatmapProps } from "./cost-heatmap";
export { DailySpendChart } from "./daily-spend-chart";
export type { DailySpendChartProps } from "./daily-spend-chart";
-export { DistillSavingsCard } from "./distill-savings-card";
+export { SavingsCard } from "./savings-card";
export type {
- DistillSavingsCardProps,
- DistillSavingsData,
- DistillSavingsGroup,
- McpDropGroup,
-} from "./distill-savings-card";
+ SavingsAgentRow,
+ SavingsBreakdownRow,
+ SavingsCardProps,
+ SavingsData,
+} from "./savings-card";
export { RoiCard } from "./roi-card";
export type { RoiCardProps } from "./roi-card";
export { SavingsTrendChart } from "./savings-trend-chart";
diff --git a/packages/ui/src/costs/distill-savings-card.tsx b/packages/ui/src/costs/savings-card.tsx
similarity index 57%
rename from packages/ui/src/costs/distill-savings-card.tsx
rename to packages/ui/src/costs/savings-card.tsx
index ab496c135..e7e01c018 100644
--- a/packages/ui/src/costs/distill-savings-card.tsx
+++ b/packages/ui/src/costs/savings-card.tsx
@@ -5,80 +5,84 @@ import { Card, CardContent } from "../ui/card";
import { Skeleton, SkeletonRegion } from "../ui/skeleton";
import { formatCost, formatTokens } from "../lib/format";
-export interface DistillSavingsGroup {
- group: string;
+export interface SavingsBreakdownRow {
+ group: string | null;
events: number;
- raw_tokens: number;
- distilled_tokens: number;
- saved_tokens: number;
+ saved_input_tokens: number;
}
-export interface McpDropGroup {
- tool: string;
+export interface SavingsAgentRow {
+ agent: string;
+ agent_display_name: string | null;
events: number;
- tokens: number;
- /** "counterfactual" (answer replaced raw exploration) or "truncation" (budget drop). */
- kind?: string;
+ saved_input_tokens: number;
}
-export interface DistillSavingsData {
+/** The canonical savings report. Field names match the wire exactly, so this
+ * component never has to know how a number was derived — only how to show it. */
+export interface SavingsData {
available: boolean;
- events: number;
- raw_tokens: number;
- distilled_tokens: number;
- saved_tokens: number;
- estimated_usd_saved: number;
- pricing_model: string;
- pricing_agent?: string;
- pricing_source?: string;
- per_filter: DistillSavingsGroup[];
- per_day: DistillSavingsGroup[];
- mcp_events?: number;
- mcp_tokens?: number;
- /** Count of counterfactual MCP queries answered ("N MCP queries answered"). */
- mcp_queries?: number;
- mcp_per_tool?: McpDropGroup[];
- /** Raw (non-distilled) agent commands a filter would have caught. */
+ unique_events: number;
+ mcp_queries_answered: number;
+ saved_input_tokens: number;
+ measured_saved_input_tokens: number;
+ inferred_saved_input_tokens: number;
+ priced_saved_input_tokens: number;
+ unpriced_saved_input_tokens: number;
+ priced_input_savings_usd: number;
+ per_operation: SavingsBreakdownRow[];
+ per_surface: SavingsBreakdownRow[];
+ /** Carried for callers and for the Phase 4 surface; this card does not
+ * render it, so it is optional rather than a required field nothing reads. */
+ per_agent?: SavingsAgentRow[];
+ per_day?: SavingsBreakdownRow[];
missed_events?: number;
missed_tokens_est?: number;
missed_window_days?: number;
- /** Full re-reads of unchanged files a targeted get_symbol would have replaced. */
reread_events?: number;
reread_tokens_est?: number;
}
-export interface DistillSavingsCardProps {
- /** Savings rollup from /distill-savings; undefined while loading. */
- data?: DistillSavingsData;
+export interface SavingsCardProps {
+ /** The savings report; undefined while loading. */
+ data?: SavingsData;
}
const DISTILL_DOCS = "https://github.com/repowise-dev/repowise/blob/main/docs/agent/DISTILL.md";
-/** Humanize the resolved pricing agent for the "priced at" caption. */
-function agentLabel(agent: string | undefined): string {
- if (agent === "claude_code") return "Claude Code";
- if (agent === "codex") return "Codex";
- return "";
+/** Surface slugs read as identifiers; these are the words for them. Kept here
+ * rather than server-side because a surface is a fixed part of the accounting
+ * contract, unlike an agent, whose label comes from the registry on the wire. */
+const SURFACE_LABELS: Record<string, string> = {
+ distill: "Distill",
+ hook: "Hooks",
+ mcp: "MCP",
+ vscode_lm: "VS Code",
+};
+
+function surfaceLabel(slug: string | null): string {
+ if (!slug) return "Unknown";
+ return SURFACE_LABELS[slug] ?? slug;
}
/**
- * Hero results card for the Costs page: every token & dollar repowise saved the
- * coding agent, across the `repowise distill` ledger (CLI + hook) and the MCP
- * tools — each curated answer replacing raw file exploration. Priced at the
- * agent's *real* model — saved tokens are input the agent never had to read.
+ * Hero results card for the Costs page: the input tokens repowise kept out of
+ * the agent's context, and what they were worth.
+ *
+ * The headline is deliberately not one confident number. Measured reductions
+ * (a known before and after) and inferred avoidance (a documented
+ * counterfactual) are different evidence and are shown as such, and the dollar
+ * figure covers only the tokens whose events carried a rate.
*/
-export function DistillSavingsCard({ data }: DistillSavingsCardProps) {
- const distillSaved = data?.saved_tokens ?? 0;
- const mcpSaved = data?.mcp_tokens ?? 0;
- const total = distillSaved + mcpSaved;
+export function SavingsCard({ data }: SavingsCardProps) {
+ const total = data?.saved_input_tokens ?? 0;
const hasData = !!data?.available && total > 0;
if (!data) {
- // Mirrors the populated card below rather than reserving a flat block:
- // headline, the two right-aligned totals, the breakdown bar with its
- // legend, and the two detail columns. The flat version stood 176px tall
- // against a card that measures 350-450px, so the whole page jumped on
- // first paint.
+ // Mirrors the populated card rather than reserving a flat block: headline,
+ // the right-aligned totals, the evidence bar with its legend, and the two
+ // detail columns. A flat version stood 176px against a card measuring
+ // 350-450px, so the whole page jumped on first paint.
return (
<Card>
<CardContent className="py-6">
@@ -96,9 +100,11 @@ export function DistillSavingsCard({ data }: DistillSavingsCardProps) {
<Skeleton className="block h-[1lh] w-24" />
</span>
</div>
- <p className="mt-1 text-xs">
+ {/* A div, not a p: Skeleton renders a div, and a p may not
+ contain one. */}
+ <div className="mt-1 text-xs">
<Skeleton className="block h-[1lh] w-56" />
- </p>
+ </div>
</div>
<div className="flex gap-6">
{[0, 1].map((i) => (
@@ -160,25 +166,18 @@ export function DistillSavingsCard({ data }: DistillSavingsCardProps) {
);
}
- const distillPct = total > 0 ? Math.round((distillSaved / total) * 100) : 0;
- const mcpPct = 100 - distillPct;
- const topFilters = [...data.per_filter]
- .sort((a, b) => b.saved_tokens - a.saved_tokens)
- .slice(0, 5);
- const topTools = (data.mcp_per_tool ?? []).slice(0, 5);
- const priced = agentLabel(data.pricing_agent) || data.pricing_model;
- const detected = data.pricing_source && data.pricing_source !== "default";
+ const measured = data.measured_saved_input_tokens;
+ const inferred = data.inferred_saved_input_tokens;
+ const measuredPct = total > 0 ? Math.round((measured / total) * 100) : 0;
+ const inferredPct = 100 - measuredPct;
+ const topOperations = data.per_operation.slice(0, 5);
+ const topSurfaces = data.per_surface.slice(0, 5);
const missed = (data.missed_tokens_est ?? 0) > 0;
const reread = (data.reread_tokens_est ?? 0) > 0;
-
- // Prefer the counterfactual framing ("N queries answered") when any MCP call
- // recorded a real saving; fall back to the truncation-drop count otherwise.
- const mcpQueries = data.mcp_queries ?? 0;
- const mcpEvents = data.mcp_events ?? 0;
- const mcpCaption =
- mcpQueries > 0
- ? `MCP · ${mcpQueries.toLocaleString()} quer${mcpQueries === 1 ? "y" : "ies"} answered`
- : `MCP · ${mcpEvents.toLocaleString()} drop${mcpEvents === 1 ? "" : "s"}`;
+ const unpriced = data.unpriced_saved_input_tokens;
+ // "Estimated" while any of the total rests on a counterfactual rather than a
+ // measured before and after.
+ const headline = inferred > 0 ? "Estimated agent savings" : "Tokens saved for your agent";
return (
<Card>
@@ -188,139 +187,147 @@ export function DistillSavingsCard({ data }: DistillSavingsCardProps) {
<div>
<div className="flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-[var(--color-text-tertiary)]">
<Sparkles className="h-3.5 w-3.5 text-[var(--color-savings-distill)]" />
- Tokens saved for your agent
+ {headline}
</div>
<div className="mt-1 flex items-baseline gap-3">
<span className="text-4xl font-semibold tabular-nums text-[var(--color-text-primary)]">
{formatTokens(total)}
</span>
<span className="text-2xl font-semibold tabular-nums text-[var(--color-success)]">
- {formatCost(data.estimated_usd_saved)}
+ {formatCost(data.priced_input_savings_usd)}
</span>
</div>
<p className="mt-1 text-xs text-[var(--color-text-secondary)]">
- priced at {priced}
- {detected ? (
- <span className="text-[var(--color-text-tertiary)]"> · {data.pricing_source}</span>
- ) : (
+ {unpriced > 0 ? (
<span
- className="text-[var(--color-text-tertiary)]"
- title="No agent session was detected, so savings are valued at the standard published rate for this model."
+ title="Each event is priced at the rate recorded when it happened. Events recorded without a rate are counted but not valued."
>
- {" "}
- · estimated at the standard model rate
+ priced on {formatTokens(data.priced_saved_input_tokens)} of{" "}
+ {formatTokens(total)} tokens
</span>
+ ) : (
+ <span>priced at the rate recorded on each event</span>
)}
</p>
</div>
<div className="flex gap-6 text-right">
<div>
<div className="text-lg font-semibold tabular-nums text-[var(--color-text-primary)]">
- {formatTokens(distillSaved)}
+ {data.unique_events.toLocaleString()}
</div>
<div className="text-xs text-[var(--color-text-tertiary)]">
- distill · {data.events.toLocaleString()} event{data.events === 1 ? "" : "s"}
+ interaction{data.unique_events === 1 ? "" : "s"}
</div>
</div>
<div>
<div className="text-lg font-semibold tabular-nums text-[var(--color-text-primary)]">
- {formatTokens(mcpSaved)}
+ {data.mcp_queries_answered.toLocaleString()}
+ </div>
+ <div className="text-xs text-[var(--color-text-tertiary)]">
+ MCP quer{data.mcp_queries_answered === 1 ? "y" : "ies"} answered
</div>
- <div className="text-xs text-[var(--color-text-tertiary)]">{mcpCaption}</div>
</div>
</div>
</div>
- {/* Two-segment breakdown bar */}
+ {/* Evidence mix — the distinction the headline must not flatten. */}
<div className="mt-4 flex h-2.5 w-full overflow-hidden rounded-full bg-[var(--color-bg-inset)]">
- {distillSaved > 0 && (
+ {measured > 0 && (
<div
className="h-full bg-[var(--color-savings-distill)]"
- style={{ width: `${distillPct}%` }}
- title={`Distill — ${formatTokens(distillSaved)} (${distillPct}%)`}
+ style={{ width: `${measuredPct}%` }}
+ title={`Measured — ${formatTokens(measured)} (${measuredPct}%)`}
/>
)}
- {mcpSaved > 0 && (
+ {inferred > 0 && (
<div
className="h-full bg-[var(--color-savings-mcp)]"
- style={{ width: `${mcpPct}%` }}
- title={`MCP tools — ${formatTokens(mcpSaved)} (${mcpPct}%)`}
+ style={{ width: `${inferredPct}%` }}
+ title={`Inferred — ${formatTokens(inferred)} (${inferredPct}%)`}
/>
)}
</div>
<div className="mt-1.5 flex items-center gap-4 text-xs text-[var(--color-text-secondary)]">
<span className="flex items-center gap-1.5">
- <span className="h-2 w-2 rounded-full bg-[var(--color-savings-distill)]" /> Distill {distillPct}%
+ <span className="h-2 w-2 rounded-full bg-[var(--color-savings-distill)]" /> Measured{" "}
+ {formatTokens(measured)}
</span>
<span className="flex items-center gap-1.5">
- <span className="h-2 w-2 rounded-full bg-[var(--color-savings-mcp)]" /> MCP tools {mcpPct}%
+ <span className="h-2 w-2 rounded-full bg-[var(--color-savings-mcp)]" /> Inferred{" "}
+ {formatTokens(inferred)}
</span>
</div>
- {/* Per-surface detail */}
+ {/* Where the savings came from */}
<div className="mt-4 grid grid-cols-1 gap-x-8 gap-y-4 sm:grid-cols-2">
- {topFilters.length > 0 && (
+ {topSurfaces.length > 0 && (
<SurfaceDetail
- title="Distill — by filter"
- rows={topFilters.map((f) => ({
- label: f.group,
- tokens: f.saved_tokens,
+ title="By surface"
+ rows={topSurfaces.map((row) => ({
+ label: surfaceLabel(row.group),
+ tokens: row.saved_input_tokens,
}))}
- max={distillSaved}
+ max={total}
barClass="bg-[var(--color-savings-distill)]"
/>
)}
- {topTools.length > 0 && (
+ {topOperations.length > 0 && (
<SurfaceDetail
- title="MCP — by tool"
- rows={topTools.map((t) => ({ label: t.tool, tokens: t.tokens }))}
- max={mcpSaved}
+ title="By operation"
+ rows={topOperations.map((row) => ({
+ label: row.group ?? "Unknown",
+ tokens: row.saved_input_tokens,
+ }))}
+ max={total}
barClass="bg-[var(--color-savings-mcp)]"
/>
)}
</div>
- {/* Missed → opportunity CTA */}
+ {/* Observed opportunities — never part of the total above. */}
{missed && (
- <a
- href={DISTILL_DOCS}
- target="_blank"
- rel="noreferrer"
- className="mt-5 flex items-center gap-3 rounded-lg border border-[var(--color-warning)]/30 bg-[var(--color-warning)]/5 px-3 py-2.5 transition-colors hover:bg-[var(--color-warning)]/10"
- >
+ <div className="mt-5 flex items-center gap-3 rounded-lg border border-[var(--color-warning)]/30 bg-[var(--color-warning)]/5 px-3 py-2.5">
<Zap className="h-4 w-4 shrink-0 text-[var(--color-warning)]" />
<div className="text-xs text-[var(--color-text-secondary)]">
<span className="font-medium text-[var(--color-warning)]">
- Unlock ~{formatTokens(data.missed_tokens_est ?? 0)} more
+ Observed opportunity: ~{formatTokens(data.missed_tokens_est ?? 0)}
</span>{" "}
— {(data.missed_events ?? 0).toLocaleString()} raw command
- {(data.missed_events ?? 0) === 1 ? "" : "s"} bypassed distill in the last{" "}
- {data.missed_window_days ?? 7} days. Enable auto-capture →
+ {(data.missed_events ?? 0) === 1 ? "" : "s"} bypassed distillation in the last{" "}
+ {data.missed_window_days ?? 7} days.{" "}
+ <a
+ href={DISTILL_DOCS}
+ target="_blank"
+ rel="noreferrer"
+ className="underline underline-offset-2 hover:text-[var(--color-text-primary)]"
+ >
+ See the distillation setup guide
+ </a>
</div>
- </a>
+ </div>
)}
- {/* Re-read waste → MCP opportunity CTA */}
{reread && (
<div className="mt-3 flex items-center gap-3 rounded-lg border border-[var(--color-warning)]/30 bg-[var(--color-warning)]/5 px-3 py-2.5">
<Zap className="h-4 w-4 shrink-0 text-[var(--color-warning)]" />
<div className="text-xs text-[var(--color-text-secondary)]">
<span className="font-medium text-[var(--color-warning)]">
- Save ~{formatTokens(data.reread_tokens_est ?? 0)} more
+ Potentially avoid ~{formatTokens(data.reread_tokens_est ?? 0)}
</span>{" "}
— {(data.reread_events ?? 0).toLocaleString()} full re-read
- {(data.reread_events ?? 0) === 1 ? "" : "s"} of unchanged files a targeted{" "}
- <code>get_symbol</code> would have replaced.
+ {(data.reread_events ?? 0) === 1 ? "" : "s"} of unchanged files{" "}
+ {(data.reread_events ?? 0) === 1 ? "was" : "were"} observed.
</div>
</div>
)}
<p className="mt-3 text-xs leading-snug text-[var(--color-text-tertiary)]">
- Distill counts <code>repowise distill</code> command/hook savings; MCP counts the raw
- file exploration each tool answer replaced (plus any over-budget content trimmed). Saved
- tokens are agent input priced at the agent&apos;s input rate, plus a small credit for the
- tool calls repowise let the agent skip; counts are estimates (~chars/4) and deliberately
- undersell. Everything stays on this machine.
+ Savings are input tokens your agent never had to read, recorded one event per
+ interaction across the <code>repowise distill</code> path, the replacement hooks and
+ MCP calls. Measured figures compare a known before and after; inferred figures estimate
+ the exploration an answer replaced. Each event is valued at the rate recorded when it
+ happened, so the dollar figure covers only priced events. Counts are estimates
+ (~chars/4) and deliberately undersell. Everything stays on this machine.
</p>
</CardContent>
</Card>
diff --git a/packages/ui/src/costs/savings-trend-chart.tsx b/packages/ui/src/costs/savings-trend-chart.tsx
index ea61e4d25..2d4d307c9 100644
--- a/packages/ui/src/costs/savings-trend-chart.tsx
+++ b/packages/ui/src/costs/savings-trend-chart.tsx
@@ -5,10 +5,10 @@ import { CHART_HEIGHT } from "./chart-height";
import { formatTokens } from "../lib/format";
export interface SavingsTrendChartProps {
- /** Day-grouped savings rows ({ group: "YYYY-MM-DD", saved_tokens }). The
- * `per_day` series from /distill-savings — total agent tokens saved per day
- * (distill + MCP counterfactual). Caller fetches. */
- groups: Array<{ group: string; saved_tokens: number }>;
+ /** Day-grouped savings rows ({ group: "YYYY-MM-DD", saved_input_tokens }).
+ * The `per_day` series from the savings report — input tokens agents did
+ * not have to read, per UTC day. Caller fetches. */
+ groups: Array<{ group: string | null; saved_input_tokens: number }>;
height?: number;
}
@@ -19,7 +19,9 @@ export interface SavingsTrendChartProps {
*/
export function SavingsTrendChart({ groups, height = CHART_HEIGHT }: SavingsTrendChartProps) {
const data = [...groups]
- .filter((g) => g.saved_tokens > 0)
+ .filter((g): g is { group: string; saved_input_tokens: number } =>
+ g.group !== null && g.saved_input_tokens > 0,
+ )
.sort((a, b) => a.group.localeCompare(b.group));
if (data.length === 0) {
@@ -72,7 +74,7 @@ export function SavingsTrendChart({ groups, height = CHART_HEIGHT }: SavingsTren
labelFormatter={(label) => `Date: ${String(label)}`}
/>
<Bar
- dataKey="saved_tokens"
+ dataKey="saved_input_tokens"
fill="var(--color-savings-distill)"
radius={[4, 4, 0, 0]}
/>
diff --git a/packages/ui/src/dashboard/savings-mini.tsx b/packages/ui/src/dashboard/savings-mini.tsx
index 91ebe02b6..df5346a02 100644
--- a/packages/ui/src/dashboard/savings-mini.tsx
+++ b/packages/ui/src/dashboard/savings-mini.tsx
@@ -2,18 +2,19 @@ import { Sparkles } from "lucide-react";
import { Card, CardContent, CardHeader, CardTitle } from "../ui/card";
import { formatCost, formatTokens } from "../lib/format";
-/** Structural slice of the savings rollup this tile renders — the full
- * /distill-savings payload and the overview-summary headline both fit. */
+/** Structural slice of the savings report this tile renders — the full
+ * savings payload and the overview-summary headline both fit. */
export interface SavingsMiniData {
available: boolean;
- saved_tokens?: number;
- mcp_tokens?: number;
+ saved_input_tokens?: number;
+ measured_saved_input_tokens?: number;
+ inferred_saved_input_tokens?: number;
+ unpriced_saved_input_tokens?: number;
estimated_usd_saved?: number;
- pricing_model?: string;
}
interface SavingsMiniProps {
- /** Rollup from /distill-savings (or the overview-summary headline);
+ /** The savings report (or the overview-summary headline);
* null/undefined when unavailable. */
data?: SavingsMiniData | null;
/** Repo id, for the "View costs →" link. */
@@ -29,19 +30,23 @@ interface SavingsMiniProps {
}
/**
- * Compact overview tile for agent token savings — the headline number, dollar
- * value priced at the detected agent model, and a distill-vs-MCP split, with a
- * jump to the full Costs results page.
+ * Compact overview tile for agent token savings — the headline number, what the
+ * priced part of it was worth, and the measured-vs-inferred evidence split,
+ * with a jump to the full Costs results page.
+ *
+ * The evidence split rides on the tile rather than the surface split because a
+ * lone headline reads as one confident number, and a counterfactual estimate
+ * and a measured before/after are not the same claim.
*/
export function SavingsMini({ data, repoId, trackable = true }: SavingsMiniProps) {
- const distillSaved = data?.saved_tokens ?? 0;
- const mcpSaved = data?.mcp_tokens ?? 0;
- const total = distillSaved + mcpSaved;
+ const total = data?.saved_input_tokens ?? 0;
+ const measured = data?.measured_saved_input_tokens ?? 0;
+ const inferred = data?.inferred_saved_input_tokens ?? 0;
const hasData = !!data?.available && total > 0;
const costsHref = `/repos/${repoId}/costs`;
- const distillPct = total > 0 ? Math.round((distillSaved / total) * 100) : 0;
- const mcpPct = 100 - distillPct;
+ const measuredPct = total > 0 ? Math.round((measured / total) * 100) : 0;
+ const inferredPct = 100 - measuredPct;
return (
<Card>
@@ -71,28 +76,28 @@ export function SavingsMini({ data, repoId, trackable = true }: SavingsMiniProps
</span>
</div>
<p className="text-xs text-[var(--color-text-secondary)] -mt-1">
- tokens saved for your agent
- {data!.pricing_model ? (
+ {inferred > 0 ? "estimated tokens saved for your agent" : "tokens saved for your agent"}
+ {(data!.unpriced_saved_input_tokens ?? 0) > 0 ? (
<span className="text-[var(--color-text-tertiary)]">
{" "}
- · priced at {data!.pricing_model}
+ · some events carry no recorded rate
</span>
) : null}
</p>
<div className="flex h-2 w-full overflow-hidden rounded-full bg-[var(--color-bg-inset)]">
- {distillSaved > 0 && (
+ {measured > 0 && (
<div
className="h-full"
- style={{ width: `${distillPct}%`, background: "var(--color-accent-fill)" }}
- title={`Distill — ${formatTokens(distillSaved)}`}
+ style={{ width: `${measuredPct}%`, background: "var(--color-accent-fill)" }}
+ title={`Measured — ${formatTokens(measured)}`}
/>
)}
- {mcpSaved > 0 && (
+ {inferred > 0 && (
<div
className="h-full"
- style={{ width: `${mcpPct}%`, background: "var(--color-accent-secondary)" }}
- title={`MCP tools — ${formatTokens(mcpSaved)}`}
+ style={{ width: `${inferredPct}%`, background: "var(--color-accent-secondary)" }}
+ title={`Inferred — ${formatTokens(inferred)}`}
/>
)}
</div>
@@ -103,10 +108,10 @@ export function SavingsMini({ data, repoId, trackable = true }: SavingsMiniProps
className="h-2 w-2 rounded-full shrink-0"
style={{ background: "var(--color-accent-fill)" }}
/>{" "}
- Distill
+ Measured
</span>
<span className="tabular-nums text-[var(--color-text-tertiary)] shrink-0">
- {formatTokens(distillSaved)}
+ {formatTokens(measured)}
</span>
</div>
<div className="flex items-center justify-between gap-2">
@@ -115,10 +120,10 @@ export function SavingsMini({ data, repoId, trackable = true }: SavingsMiniProps
className="h-2 w-2 rounded-full shrink-0"
style={{ background: "var(--color-accent-secondary)" }}
/>{" "}
- MCP tools
+ Inferred
</span>
<span className="tabular-nums text-[var(--color-text-tertiary)] shrink-0">
- {formatTokens(mcpSaved)}
+ {formatTokens(inferred)}
</span>
</div>
</div>
diff --git a/packages/web/src/app/repos/[id]/costs/page.tsx b/packages/web/src/app/repos/[id]/costs/page.tsx
index dcd2259f2..62866448f 100644
--- a/packages/web/src/app/repos/[id]/costs/page.tsx
+++ b/packages/web/src/app/repos/[id]/costs/page.tsx
@@ -15,14 +15,14 @@ import { CHART_HEIGHT, operationBreakdownHeight } from "@repowise-dev/ui/costs/c
import {
CostHeatmap,
DailySpendChart,
- DistillSavingsCard,
+ SavingsCard,
ProviderComparison,
OperationBreakdown,
RoiCard,
SavingsTrendChart,
} from "@repowise-dev/ui/costs";
-import { listCosts, getCostSummary, getDistillSavings } from "@/lib/api/costs";
-import type { CostGroup, CostSummary, DistillSavings } from "@/lib/api/costs";
+import { listCosts, getCostSummary, getSavings } from "@/lib/api/costs";
+import type { CostGroup, CostSummary, Savings } from "@/lib/api/costs";
import { formatCost, formatNumber, formatTokens } from "@repowise-dev/ui/lib/format";
export default function CostsPage() {
@@ -76,11 +76,9 @@ export default function CostsPage() {
data: distillSavings,
error: distillError,
mutate: retryDistill,
- } = useSWR<DistillSavings>(
- `distill-savings:${id}`,
- () => getDistillSavings(id),
- { revalidateOnFocus: false },
- );
+ } = useSWR<Savings>(`savings:${id}`, () => getSavings(id), {
+ revalidateOnFocus: false,
+ });
// A discriminated union rather than a bare string, so the populated branch
// carries the data it is populated with and TypeScript can see that.
@@ -112,7 +110,7 @@ export default function CostsPage() {
</CardContent>
</Card>
) : (
- <DistillSavingsCard data={distillSavings} />
+ <SavingsCard data={distillSavings} />
)}
{/* ROI and the savings trend are gated on `available`, which is a
@@ -140,9 +138,9 @@ export default function CostsPage() {
<>
{summary ? (
<RoiCard
- savedUsd={savings.data.estimated_usd_saved}
+ savedUsd={savings.data.priced_input_savings_usd}
spentUsd={summary.total_cost_usd}
- savedTokens={savings.data.saved_tokens + savings.data.mcp_tokens}
+ savedTokens={savings.data.saved_input_tokens}
/>
) : null}
{(savings.data.per_day?.length ?? 0) > 0 ? (
diff --git a/packages/web/src/app/repos/[id]/overview/page.tsx b/packages/web/src/app/repos/[id]/overview/page.tsx
index e3e1e3751..bed1bcdea 100644
--- a/packages/web/src/app/repos/[id]/overview/page.tsx
+++ b/packages/web/src/app/repos/[id]/overview/page.tsx
@@ -216,17 +216,24 @@ export default async function OverviewPage({ params }: Props) {
// same component without it — no flag, no empty state pitching a CLI the
// viewer is not running.
const savings = summary.savings;
- const savedTokens = (savings.saved_tokens ?? 0) + (savings.mcp_tokens ?? 0);
+ const savedTokens = savings.saved_input_tokens ?? 0;
if (savings.available && savedTokens > 0) {
+ // "Estimated" while any of the total rests on a counterfactual rather than
+ // a measured before and after. The two are different claims, and the row
+ // is too small to show the split, so it qualifies the label instead.
+ const inferred = savings.inferred_saved_input_tokens ?? 0;
reads.push({
key: "savings",
- label: "Agent savings",
+ label: inferred > 0 ? "Estimated agent savings" : "Agent savings",
value: formatTokens(savedTokens),
...(savings.estimated_usd_saved
? { unit: formatCost(savings.estimated_usd_saved) }
: {}),
href: `${base}/costs`,
- why: `Tokens your agent did not spend${savings.pricing_model ? `, priced at ${savings.pricing_model}` : ""}`,
+ why:
+ inferred > 0
+ ? "Input tokens your agent did not have to read, part of it estimated"
+ : "Input tokens your agent did not have to read",
});
}
diff --git a/tests/unit/agents/test_identity.py b/tests/unit/agents/test_identity.py
index 3cb4a230e..83733b834 100644
--- a/tests/unit/agents/test_identity.py
+++ b/tests/unit/agents/test_identity.py
@@ -238,7 +238,18 @@ def test_the_registry_is_where_a_label_comes_from(agent: AgentIdentity) -> None:
def test_an_unregistered_slug_is_labelled_verbatim() -> None:
"""A retired agent still in the ledger gets its id back, not an invented name."""
assert display_name_for("retired_agent") == "retired_agent"
- assert display_name_for(UNKNOWN_AGENT) == UNKNOWN_AGENT
+
+
+def test_the_unknown_sentinel_is_labelled_rather_than_echoed() -> None:
+ """``unknown`` is this registry's own word, not an agent id.
+
+ It reaches a screen whenever a client announces nothing, so the label
+ belongs here beside every other label rather than being title-cased by each
+ surface that has to render it.
+ """
+ assert display_name_for(UNKNOWN_AGENT) == "Unknown"
+ # Still not an agent: it must not appear in the registry itself.
+ assert identity.get_identity(UNKNOWN_AGENT) is None
def test_the_shipped_registry_is_the_six_integrated_agents() -> None:
diff --git a/tests/unit/distill/test_saved_cmd.py b/tests/unit/distill/test_saved_cmd.py
index b8e97a5e1..ac8383ed4 100644
--- a/tests/unit/distill/test_saved_cmd.py
+++ b/tests/unit/distill/test_saved_cmd.py
@@ -14,6 +14,22 @@ from repowise.core.distill import tracking
from repowise.core.distill.store import OmissionStore
[email protected](autouse=True)
+def _no_transcript_scan(monkeypatch) -> None:
+ """Keep the pricing scan out of this suite.
+
+ ``repowise saved`` warms the pricing cache when a report shows unpriced
+ savings, and resolving it reads the user's real ``~/.codex`` transcripts --
+ seconds per call, and machine-dependent besides. What that warm does is
+ covered hermetically in ``tests/unit/savings/test_pricing_snapshot.py``;
+ this suite is about what the command renders.
+ """
+ from repowise.core.savings import pricing
+
+ monkeypatch.setattr(pricing, "_scan", lambda repo_root: None)
+ pricing.clear_pricing_cache()
+
+
@pytest.fixture()
def repo_cwd(tmp_path: Path, monkeypatch) -> Path:
"""A scratch repo with .repowise/ so the store lands locally."""
@@ -50,6 +66,63 @@ def _store(repo: Path) -> OmissionStore:
return OmissionStore(repo / ".repowise" / "omissions" / "omissions.db")
+def _canonical(
+ repo: Path,
+ *,
+ operation: str = "test_output",
+ surface: str = "distill",
+ agent: str = "unknown",
+ baseline: int = 10_000,
+ delivered: int = 1_000,
+ evidence_kind: str = "measured",
+ priced: bool = False,
+ occurred_at: str | None = None,
+) -> None:
+ """Write one canonical savings event, which is what the command reads."""
+ from datetime import UTC, datetime
+
+ from repowise.core.savings import recorder
+ from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key
+
+ event_id = new_event_id()
+ payload: dict = {
+ "event_id": event_id,
+ "idempotency_key": scoped_idempotency_key(str(repo), surface, event_id),
+ "occurred_at": occurred_at
+ or datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z"),
+ "surface": surface,
+ "integration": agent,
+ "agent": agent,
+ "operation": operation,
+ "evidence_kind": evidence_kind,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": True,
+ "baseline_input_tokens": baseline,
+ "pre_budget_input_tokens": baseline,
+ "delivered_input_tokens": delivered,
+ }
+ if priced:
+ payload.update(
+ model="claude-sonnet-4-6",
+ currency="USD",
+ pricing_source="session_model:unknown",
+ pricing_version="pricing:test",
+ input_rate_usd_per_million=3.0,
+ output_rate_usd_per_million=15.0,
+ )
+ assert recorder.record_event(repo, payload) is True
+
+
+def _seed_canonical(repo: Path) -> None:
+ """The canonical twin of :func:`_seed`: 13,800 saved input tokens."""
+ _store(repo).close()
+ _canonical(repo, operation="test_output", baseline=10_000, delivered=1_000)
+ _canonical(repo, operation="test_output", surface="hook", baseline=5_000, delivered=500)
+ _canonical(repo, operation="git_status", surface="hook", baseline=400, delivered=100)
+
+
# -- tracking rollups -------------------------------------------------------
@@ -111,50 +184,88 @@ def test_rollup_dimensions_constant_matches_columns() -> None:
# -- repowise saved ---------------------------------------------------------
-def test_saved_reports_totals_and_per_filter(repo_cwd: Path) -> None:
- s = _store(repo_cwd)
- _seed(s)
- s.close()
+def test_saved_reports_totals_and_per_operation(repo_cwd: Path) -> None:
+ _seed_canonical(repo_cwd)
result = CliRunner().invoke(saved_command, [])
assert result.exit_code == 0
assert "test_output" in result.output
assert "git_status" in result.output
assert "TOTAL" in result.output
- assert "13,800" in result.output # total saved tokens
- assert "Estimated saved" in result.output
+ assert "13,800" in result.output # total saved input tokens
# The scope caption must be visible in the report itself (normalize
# whitespace — rich wraps the caption at terminal width).
flat = " ".join(result.output.split())
- assert "MCP counterfactual savings (mcp:<tool>)" in flat
+ assert "the hooks that replace a tool result, and MCP calls" in flat
+
+
+def test_saved_splits_savings_by_surface(repo_cwd: Path) -> None:
+ """The grouping that replaced ``--by source``.
+
+ Asserted on the row values rather than on the surface names: both words
+ also appear in the table caption, which prints whether or not the grouping
+ produced any rows at all.
+ """
+ _seed_canonical(repo_cwd)
+ result = CliRunner().invoke(saved_command, ["--by", "surface"])
+ assert result.exit_code == 0
+ # Cell borders removed before collapsing whitespace, so a row reads as one
+ # run of text rather than as three fragments separated by box drawing.
+ flat = " ".join(result.output.replace("│", " ").split())
+ # distill: one event, 10,000 - 1,000.
+ assert "distill 1 9,000" in flat
+ # hook: two events, (5,000 - 500) + (400 - 100).
+ assert "hook 2 4,800" in flat
+
+
+def test_saved_labels_agents_from_the_registry(repo_cwd: Path) -> None:
+ """No label map in this command; the report carries the display name."""
+ _store(repo_cwd).close()
+ _canonical(repo_cwd, agent="claude_code", baseline=1_000, delivered=0)
+ result = CliRunner().invoke(saved_command, ["--by", "agent"])
+ assert result.exit_code == 0
+ assert "Claude Code" in result.output
+
+
+def test_saved_keeps_measured_and_inferred_apart(repo_cwd: Path) -> None:
+ """The total must not read as one confident number."""
+ _store(repo_cwd).close()
+ _canonical(repo_cwd, baseline=1_000, delivered=0, evidence_kind="measured")
+ _canonical(repo_cwd, baseline=400, delivered=0, evidence_kind="inferred")
+ result = CliRunner().invoke(saved_command, [])
+ assert result.exit_code == 0
+ flat = " ".join(result.output.split())
+ assert "Measured: 1,000" in flat
+ assert "Inferred: 400" in flat
def test_saved_by_day(repo_cwd: Path) -> None:
- s = _store(repo_cwd)
- _seed(s)
- s.close()
+ _seed_canonical(repo_cwd)
result = CliRunner().invoke(saved_command, ["--by", "day"])
assert result.exit_code == 0
assert "Events" in result.output
-def test_saved_dollar_estimate_uses_input_rate(repo_cwd: Path) -> None:
- s = _store(repo_cwd)
- s.record_saving(
- filter_name="test_output",
- source="cli",
- command="pytest",
- raw_tokens=1_000_000,
- distilled_tokens=0,
- )
- s.close()
- # claude-sonnet-4-6 input rate is $3.00/M -> exactly $3.00 for 1M saved.
- # Pinned explicitly: the rate is now detected, and a tmp repo happens to
- # have no session to detect, which is not something to assert by accident.
- result = CliRunner().invoke(saved_command, ["--model", "claude-sonnet-4-6"])
+def test_saved_dollar_estimate_uses_the_rate_recorded_on_the_event(repo_cwd: Path) -> None:
+ """Priced from the event, not from whatever model is detected today."""
+ _store(repo_cwd).close()
+ _canonical(repo_cwd, baseline=1_000_000, delivered=0, priced=True)
+ # The event carries $3.00/M input -> exactly $3.00 for 1M saved.
+ result = CliRunner().invoke(saved_command, [])
assert result.exit_code == 0
assert "$3.0000" in result.output
+def test_saved_reports_unpriced_tokens_rather_than_valuing_them(repo_cwd: Path) -> None:
+ """An event written without a rate is counted but not valued."""
+ _store(repo_cwd).close()
+ _canonical(repo_cwd, baseline=1_000_000, delivered=0, priced=False)
+ result = CliRunner().invoke(saved_command, [])
+ assert result.exit_code == 0
+ flat = " ".join(result.output.split())
+ assert "1,000,000 tokens carry no recorded rate" in flat
+ assert "Estimated saved" not in flat
+
+
class TestPricingModelResolution:
"""Saved tokens must cost what the agent that saved them costs.
@@ -207,7 +318,16 @@ class TestPricingModelResolution:
assert saved_cmd.DEFAULT_PRICING_MODEL == DEFAULT_MODEL
- def test_detected_rate_reaches_the_dollar_line(self, repo_cwd: Path, monkeypatch) -> None:
+ def test_the_rate_on_the_event_is_what_reaches_the_dollar_line(
+ self, repo_cwd: Path, monkeypatch
+ ) -> None:
+ """Detection no longer prices the report; the event does.
+
+ An event priced at write time keeps its rate even when the newest
+ session reports a different model, which is the whole point of
+ snapshotting. Detection is monkeypatched to a *different* model here
+ precisely so a report that still repriced from the session would fail.
+ """
from repowise.core.distill import session_model
detected = session_model.ResolvedModel(
@@ -217,20 +337,13 @@ class TestPricingModelResolution:
source="detected from Claude Code session",
)
monkeypatch.setattr(session_model, "resolve_session_model", lambda *a, **k: detected)
- s = _store(repo_cwd)
- s.record_saving(
- filter_name="test_output",
- source="cli",
- command="pytest",
- raw_tokens=1_000_000,
- distilled_tokens=0,
- )
- s.close()
+ _store(repo_cwd).close()
+ _canonical(repo_cwd, baseline=1_000_000, delivered=0, priced=True)
result = CliRunner().invoke(saved_command, [])
assert result.exit_code == 0
- # Opus input is $5.00/M, not the $3.00 this command used to assume.
- assert "$5.0000" in result.output
- assert "claude-opus-5" in result.output
+ # The event's own $3.00/M rate, not Opus's $5.00 repriced from the session.
+ assert "$3.0000" in result.output
+ assert "$5.0000" not in result.output
def test_saved_no_store_prints_hint(repo_cwd: Path) -> None:
@@ -244,17 +357,19 @@ def test_saved_empty_ledger_prints_message(repo_cwd: Path) -> None:
_store(repo_cwd).close() # creates the DB with zero ledger rows
result = CliRunner().invoke(saved_command, [])
assert result.exit_code == 0
- assert "No distillation events recorded" in result.output
+ assert "No savings events recorded" in result.output
def test_saved_since_filters_events(repo_cwd: Path) -> None:
- s = _store(repo_cwd)
- _seed(s)
- s._conn.execute(
- "UPDATE savings SET created_at = created_at - 10 * 86400 WHERE filter = 'git_status'"
+ _store(repo_cwd).close()
+ _canonical(repo_cwd, operation="test_output", baseline=10_000, delivered=1_000)
+ _canonical(
+ repo_cwd,
+ operation="git_status",
+ baseline=400,
+ delivered=100,
+ occurred_at="2020-01-01T00:00:00.000000Z",
)
- s._conn.commit()
- s.close()
from datetime import date, timedelta
cutoff = (date.today() - timedelta(days=1)).isoformat()
@@ -273,9 +388,7 @@ def test_saved_bad_since_fails_cleanly(repo_cwd: Path) -> None:
def test_saved_explicit_path_argument(tmp_path: Path) -> None:
repo = tmp_path / "elsewhere"
(repo / ".repowise").mkdir(parents=True)
- s = _store(repo)
- _seed(s)
- s.close()
+ _seed_canonical(repo)
result = CliRunner().invoke(saved_command, [str(repo)])
assert result.exit_code == 0
assert "test_output" in result.output
diff --git a/tests/unit/savings/test_pricing_snapshot.py b/tests/unit/savings/test_pricing_snapshot.py
new file mode 100644
index 000000000..175f206bd
--- /dev/null
+++ b/tests/unit/savings/test_pricing_snapshot.py
@@ -0,0 +1,332 @@
+"""The pricing snapshot: what it captures, and what it refuses to pay for.
+
+The cache is not an optimization detail. Detecting the agent's model scans the
+local transcripts, which was measured at about six seconds on a machine with
+700 Codex sessions, and the hook is a fresh process per tool call. So "the hook
+never scans" is a correctness property of the hot path, and it is asserted here
+rather than trusted.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import pytest
+
+from repowise.core.savings import pricing
+from repowise.core.savings.pricing import (
+ PricingSnapshot,
+ clear_pricing_cache,
+ resolve_pricing_snapshot,
+)
+
+
[email protected](autouse=True)
+def _clear() -> None:
+ clear_pricing_cache()
+ yield
+ clear_pricing_cache()
+
+
+def repo(tmp_path: Path) -> Path:
+ (tmp_path / ".repowise" / "omissions").mkdir(parents=True)
+ return tmp_path
+
+
+def _count_scans(monkeypatch: pytest.MonkeyPatch) -> list[int]:
+ """Replace the transcript scan with a counter, so a scan is observable."""
+ calls: list[int] = []
+
+ def fake(repo_root: Path) -> PricingSnapshot:
+ calls.append(1)
+ return PricingSnapshot(
+ model="claude-opus-5",
+ pricing_source="session_model:claude_code",
+ pricing_version="pricing:test",
+ input_rate_usd_per_million=5.0,
+ output_rate_usd_per_million=25.0,
+ )
+
+ monkeypatch.setattr(pricing, "_scan", fake)
+ return calls
+
+
+def test_a_snapshot_carries_the_fields_an_event_needs(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _count_scans(monkeypatch)
+ payload = resolve_pricing_snapshot(repo).as_payload()
+ assert payload == {
+ "model": "claude-opus-5",
+ "currency": "USD",
+ "pricing_source": "session_model:claude_code",
+ "pricing_version": "pricing:test",
+ "input_rate_usd_per_million": 5.0,
+ "output_rate_usd_per_million": 25.0,
+ }
+
+
+def test_the_scan_runs_once_and_is_then_served_from_disk(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ calls = _count_scans(monkeypatch)
+ first = resolve_pricing_snapshot(repo)
+ clear_pricing_cache() # a fresh process, with the cache file already on disk
+ second = resolve_pricing_snapshot(repo)
+ assert first == second
+ assert len(calls) == 1
+
+
+def test_the_hook_reads_the_cache_but_never_scans(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The whole reason the switch exists."""
+ calls = _count_scans(monkeypatch)
+
+ # Nothing cached yet: the hook takes an unpriced event rather than a stall.
+ assert resolve_pricing_snapshot(repo, allow_scan=False) is None
+ assert calls == []
+
+ # Once some other surface has filled the cache, the hook gets a price.
+ resolve_pricing_snapshot(repo)
+ clear_pricing_cache()
+ assert resolve_pricing_snapshot(repo, allow_scan=False) is not None
+ assert len(calls) == 1
+
+
+#: Modules that call the resolver from inside an agent's own tool call. Each
+#: must pass ``allow_scan=False`` at every call site, without exception.
+_AGENT_FACING = (
+ "repowise.server.mcp_server._savings.event",
+ "repowise.cli.commands.augment_cmd._shared",
+)
+
+
+def test_no_agent_facing_surface_can_trigger_a_scan() -> None:
+ """The surfaces that run inside a tool call must never resolve inline.
+
+ Asserted against the call sites rather than left to the docstrings, because
+ the only thing that made the regression visible was an unrelated test file
+ getting fourteen times slower. The MCP path resolved inline, so the first
+ tool call in every repository paid the full six-second scan, and not one
+ assertion failed.
+ """
+ import ast
+ import importlib
+ import inspect
+
+ checked = 0
+ for module_name in _AGENT_FACING:
+ module = importlib.import_module(module_name)
+ tree = ast.parse(inspect.getsource(module))
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Call):
+ continue
+ func = node.func
+ name = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", None)
+ if name != "resolve_pricing_snapshot":
+ continue
+ checked += 1
+ flags = {kw.arg: kw.value for kw in node.keywords}
+ assert "allow_scan" in flags, f"{module_name} resolves without allow_scan"
+ value = flags["allow_scan"]
+ assert isinstance(value, ast.Constant) and value.value is False, (
+ f"{module_name} must pass allow_scan=False"
+ )
+ # The walk finding nothing would pass vacuously, which is the failure mode
+ # this whole test exists to prevent.
+ assert checked == len(_AGENT_FACING)
+
+
+def test_the_distill_engine_only_scans_off_the_hook_path() -> None:
+ """The rewrite hook turns the agent's Bash call into ``repowise distill``.
+
+ So the engine's surface decides: a direct CLI run may scan, a hook-sourced
+ one may not. Reading the flag rather than trusting the comment, since the
+ two disagreed once already.
+ """
+ import ast
+ import inspect
+
+ from repowise.core.distill import engine
+
+ tree = ast.parse(inspect.getsource(engine))
+ calls = [
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call)
+ and getattr(node.func, "id", getattr(node.func, "attr", None))
+ == "resolve_pricing_snapshot"
+ ]
+ assert len(calls) == 1
+ flags = {kw.arg: kw.value for kw in calls[0].keywords}
+ # Conditional on the surface, not an unconditional True.
+ assert isinstance(flags.get("allow_scan"), ast.Compare)
+
+
+def test_declining_to_scan_does_not_poison_the_memo(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A hook miss must not make the next scanning caller wait out a TTL."""
+ calls = _count_scans(monkeypatch)
+ assert resolve_pricing_snapshot(repo, allow_scan=False) is None
+ assert resolve_pricing_snapshot(repo) is not None
+ assert len(calls) == 1
+
+
+def test_a_stale_cache_is_rescanned(repo: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ calls = _count_scans(monkeypatch)
+ resolve_pricing_snapshot(repo)
+ cache = repo / ".repowise" / "omissions" / "pricing-snapshot.json"
+ payload = json.loads(cache.read_text(encoding="utf-8"))
+ payload["resolved_at"] = time.time() - (pricing._TTL_SECONDS + 60)
+ cache.write_text(json.dumps(payload), encoding="utf-8")
+ clear_pricing_cache()
+
+ resolve_pricing_snapshot(repo)
+ assert len(calls) == 2
+
+
+ "content",
+ [
+ "not json at all",
+ json.dumps({"version": 999, "resolved_at": 0}),
+ json.dumps({"version": 1, "resolved_at": "yesterday", "model": "m"}),
+ json.dumps({"version": 1, "resolved_at": True, "model": "m"}),
+ json.dumps({"version": 1, "resolved_at": 0}), # epoch: older than any TTL
+ json.dumps({"version": 1, "resolved_at": time.time(), "model": "m" * 129}),
+ json.dumps([1, 2, 3]),
+ ],
+)
+def test_an_unusable_cache_is_treated_as_absent(
+ repo: Path, monkeypatch: pytest.MonkeyPatch, content: str
+) -> None:
+ """Never an exception on a read path, and never a half-built snapshot."""
+ calls = _count_scans(monkeypatch)
+ cache = repo / ".repowise" / "omissions" / "pricing-snapshot.json"
+ cache.write_text(content, encoding="utf-8")
+
+ assert resolve_pricing_snapshot(repo) is not None
+ assert len(calls) == 1
+ clear_pricing_cache()
+ cache.write_text(content, encoding="utf-8")
+ assert resolve_pricing_snapshot(repo, allow_scan=False) is None
+
+
+def test_a_missing_repository_is_unpriced_rather_than_an_error() -> None:
+ assert resolve_pricing_snapshot(None) is None
+
+
+def test_a_failing_scan_never_raises(repo: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ def boom(repo_root: Path) -> PricingSnapshot:
+ raise RuntimeError("transcripts exploded")
+
+ monkeypatch.setattr(pricing, "_scan", boom)
+ assert resolve_pricing_snapshot(repo) is None
+
+
+def test_the_cache_write_leaves_no_temporary_behind(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _count_scans(monkeypatch)
+ resolve_pricing_snapshot(repo)
+ directory = repo / ".repowise" / "omissions"
+ assert [p.name for p in directory.iterdir()] == ["pricing-snapshot.json"]
+
+
+def test_the_pricing_table_version_changes_with_the_table(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A hand-maintained version would go stale on exactly the edit that matters.
+
+ So the property under test is that editing a rate moves the version. Each
+ table is edited separately, because a version derived from only one of them
+ would still look correct here if the others were left out.
+ """
+ from repowise.core.generation import cost_tracker
+
+ before = cost_tracker.pricing_table_version()
+ assert before == cost_tracker.pricing_table_version() # stable across calls
+ assert before.startswith("pricing:")
+
+ monkeypatch.setitem(cost_tracker._PRICING, "claude-sonnet-4-6", {"input": 9.0, "output": 9.0})
+ assert cost_tracker.pricing_table_version() != before
+ monkeypatch.undo()
+
+ monkeypatch.setitem(cost_tracker._FALLBACK_PRICING, "input", 99.0)
+ assert cost_tracker.pricing_table_version() != before
+ monkeypatch.undo()
+
+ monkeypatch.setattr(
+ cost_tracker,
+ "_CLAUDE_FAMILY_PRICING",
+ (("claude-opus", {"input": 99.0, "output": 99.0}),),
+ )
+ assert cost_tracker.pricing_table_version() != before
+
+
+def test_a_model_id_too_long_for_the_contract_yields_no_snapshot(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """An unusable snapshot must cost the event its price, not its existence.
+
+ The model id is read out of a transcript, and the event contract bounds it
+ at 128 characters by raising -- which would drop the whole event before it
+ was written, so a repository with one odd transcript would silently record
+ no savings at all for a day.
+ """
+ from repowise.core.distill import session_model
+
+ monkeypatch.setattr(
+ session_model,
+ "resolve_session_model",
+ lambda *a, **k: session_model.ResolvedModel(
+ model="m" * 129, raw="m" * 129, agent="claude_code", source="detected"
+ ),
+ )
+ assert resolve_pricing_snapshot(repo) is None
+ # And nothing unusable was cached for the next caller to read back.
+ assert resolve_pricing_snapshot(repo, allow_scan=False) is None
+
+
+def test_a_cached_snapshot_expires_when_the_file_does(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The memo must not refresh a snapshot's lifetime every time it is read.
+
+ Otherwise a long-lived process that reads a 23-hour-old file keeps serving
+ it for another full day.
+ """
+ calls = _count_scans(monkeypatch)
+ resolve_pricing_snapshot(repo)
+ cache = repo / ".repowise" / "omissions" / "pricing-snapshot.json"
+ payload = json.loads(cache.read_text(encoding="utf-8"))
+ payload["resolved_at"] = time.time() - (pricing._TTL_SECONDS - 5)
+ cache.write_text(json.dumps(payload), encoding="utf-8")
+ clear_pricing_cache()
+
+ resolve_pricing_snapshot(repo) # reads the nearly-expired file
+ assert len(calls) == 1
+ entry = pricing._memo[str(repo)]
+ # Seconds of life left, not another whole TTL.
+ assert entry[1] - time.monotonic() < 60
+
+
+def test_a_scan_whose_cache_write_fails_is_still_used(
+ repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A six-second scan must not be thrown away because the disk said no."""
+ calls = _count_scans(monkeypatch)
+
+ def refuse(path: Path, snapshot: PricingSnapshot) -> None:
+ raise OSError("read-only file system")
+
+ monkeypatch.setattr(pricing, "_write_cache", refuse)
+ assert resolve_pricing_snapshot(repo) is not None
+ # And the process does not scan again for the same repository.
+ assert resolve_pricing_snapshot(repo) is not None
+ assert len(calls) == 1
diff --git a/tests/unit/savings/test_repository.py b/tests/unit/savings/test_repository.py
index 249f92a55..cb0b260e5 100644
--- a/tests/unit/savings/test_repository.py
+++ b/tests/unit/savings/test_repository.py
@@ -260,8 +260,17 @@ def test_report_queries_are_read_only_and_breakdowns_are_bounded(tmp_path: Path)
assert report.priced_saved_output_tokens == 0
assert report.unpriced_saved_output_tokens == 0
assert len(report.per_operation) == 3
- assert len(statements) == 3
+ # Every breakdown honours the cap, not just the first one.
+ for breakdown in (report.per_operation, report.per_surface, report.per_agent):
+ assert len(breakdown) <= 3
+ # Read-only, and every grouped query is bounded. Asserted as properties
+ # rather than as a statement count: the count changes whenever a breakdown
+ # is added, which is not the thing worth protecting.
+ assert statements
assert all(statement.lstrip().upper().startswith("SELECT") for statement in statements)
+ grouped = [statement for statement in statements if "GROUP BY" in statement.upper()]
+ assert grouped, "expected at least one grouped breakdown query"
+ assert all("LIMIT" in statement.upper() for statement in grouped)
@pytest.mark.parametrize("column", ["integration", "agent"])
diff --git a/tests/unit/savings/test_service.py b/tests/unit/savings/test_service.py
new file mode 100644
index 000000000..6deeeac07
--- /dev/null
+++ b/tests/unit/savings/test_service.py
@@ -0,0 +1,213 @@
+"""The one report service every first-party savings surface reads through."""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+import pytest
+
+from repowise.core.distill.store import OmissionStore
+from repowise.core.savings import recorder
+from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key
+from repowise.core.savings.reporting import build_report
+from repowise.core.savings.service import load_report
+
+
+def _sidecar(repo: Path) -> None:
+ OmissionStore(repo / ".repowise" / "omissions" / "omissions.db").close()
+
+
+def _record(
+ repo: Path,
+ *,
+ baseline: int,
+ surface: str = "mcp",
+ agent: str = "codex",
+ operation: str = "get_answer",
+ evidence_kind: str = "measured",
+ occurred_at: datetime | str | None = None,
+ priced: bool = False,
+) -> None:
+ event_id = new_event_id()
+ payload: dict = {
+ "event_id": event_id,
+ "idempotency_key": scoped_idempotency_key(str(repo), surface, event_id),
+ "occurred_at": occurred_at or datetime.now(UTC),
+ "surface": surface,
+ "integration": agent,
+ "agent": agent,
+ "operation": operation,
+ "evidence_kind": evidence_kind,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": True,
+ "baseline_input_tokens": baseline,
+ "pre_budget_input_tokens": baseline,
+ "delivered_input_tokens": 0,
+ }
+ if priced:
+ payload.update(
+ model="claude-opus-5",
+ currency="USD",
+ pricing_source="session_model:claude_code",
+ pricing_version="pricing:test",
+ input_rate_usd_per_million=5.0,
+ output_rate_usd_per_million=25.0,
+ )
+ assert recorder.record_event(repo, payload)
+
+
+def test_a_repository_with_no_sidecar_reports_nothing_rather_than_zero(
+ tmp_path: Path,
+) -> None:
+ """Absent and zero are different claims, and the callers render them differently."""
+ assert load_report(tmp_path) is None
+ assert load_report(None) is None
+
+
+def test_an_initialized_but_empty_sidecar_reports_a_measured_zero(tmp_path: Path) -> None:
+ _sidecar(tmp_path)
+ report = load_report(tmp_path)
+ assert report is not None
+ assert report.unique_events == 0
+ assert report.saved_input_tokens == 0
+ assert report.last_event_at is None
+
+
+def test_the_reader_asks_with_the_same_repository_id_the_recorder_wrote(
+ tmp_path: Path,
+) -> None:
+ """The recorder files events under the path it wrote to. If the reader asks
+ with a different string it finds nothing and reports a confident zero --
+ which looks exactly like a working report of a quiet repository."""
+ _sidecar(tmp_path)
+ _record(tmp_path, baseline=1_000)
+ report = load_report(tmp_path)
+ assert report is not None
+ assert report.saved_input_tokens == 1_000
+
+
+def test_an_unnormalized_path_still_finds_its_own_events(tmp_path: Path) -> None:
+ """The reader and the writer must agree on the id, whatever spelling they get.
+
+ The server stores ``local_path`` verbatim from the request that registered
+ the repository, so it can carry a trailing separator or forward slashes on
+ Windows. ``sidecar_path`` normalizes through Path and finds the database
+ either way, so a mismatch here does not error -- it reports ``available``
+ with a confident zero, which is indistinguishable from a quiet repository.
+ """
+ _sidecar(tmp_path)
+ _record(tmp_path, baseline=1_000)
+
+ for spelling in (f"{tmp_path}{os.sep}", str(tmp_path).replace(os.sep, "/")):
+ report = load_report(spelling)
+ assert report is not None, spelling
+ assert report.saved_input_tokens == 1_000, spelling
+
+
+def test_an_enormous_window_reports_nothing_rather_than_raising(tmp_path: Path) -> None:
+ """``days`` large enough to overflow a timedelta is still a read path.
+
+ OverflowError is not a ValueError, so it escaped the guard and surfaced as
+ a 500 from the savings endpoint.
+ """
+ _sidecar(tmp_path)
+ _record(tmp_path, baseline=1_000)
+ assert load_report(tmp_path, days=999_999_999) is None
+ assert load_report(tmp_path, days=10**12) is None
+
+
+def test_a_corrupt_sidecar_degrades_instead_of_raising(tmp_path: Path) -> None:
+ """This runs inside a dashboard endpoint and a CLI command; neither may die
+ because a sidecar was truncated mid-write."""
+ database = tmp_path / ".repowise" / "omissions" / "omissions.db"
+ database.parent.mkdir(parents=True)
+ database.write_bytes(b"this is not a sqlite database")
+ assert load_report(tmp_path) is None
+
+
+def test_the_service_does_not_write_to_the_sidecar(tmp_path: Path) -> None:
+ """Reporting must never upgrade a schema or create a store as a side effect."""
+ _sidecar(tmp_path)
+ _record(tmp_path, baseline=500)
+ database = tmp_path / ".repowise" / "omissions" / "omissions.db"
+ before = database.stat().st_mtime_ns, database.read_bytes()
+
+ load_report(tmp_path)
+
+ assert (database.stat().st_mtime_ns, database.read_bytes()) == before
+
+
+def test_the_sql_report_and_the_pure_report_agree(tmp_path: Path) -> None:
+ """Two report builders exist, and they are only useful while identical.
+
+ The pure one is the hand-checkable oracle; the SQL one is what ships. A
+ breakdown added to one and not the other is the drift this catches.
+ """
+ import sqlite3
+ from dataclasses import asdict
+
+ _sidecar(tmp_path)
+ # Deliberately the cases a three-identical-event fixture would not reach:
+ # priced beside unpriced (so the null-model group exists and the USD sums
+ # are non-zero), a tie on saved tokens across a null and a non-null group
+ # (the exact ordering the two builders have to agree on), both evidence
+ # kinds, and a multi-day series.
+ _record(tmp_path, baseline=1_000, surface="mcp", agent="claude_code", priced=True)
+ _record(tmp_path, baseline=1_000, surface="distill", agent="codex", priced=False)
+ _record(
+ tmp_path,
+ baseline=250,
+ surface="hook",
+ agent="claude_code",
+ operation="read_skeleton",
+ evidence_kind="inferred",
+ occurred_at="2026-09-10T08:00:00.000000Z",
+ )
+ _record(
+ tmp_path,
+ baseline=90,
+ surface="mcp",
+ agent="unknown",
+ occurred_at="2026-09-11T08:00:00.000000Z",
+ priced=True,
+ )
+
+ as_of = datetime.now(UTC)
+ from_sql = load_report(tmp_path, as_of=as_of)
+ assert from_sql is not None
+
+ database = tmp_path / ".repowise" / "omissions" / "omissions.db"
+ connection = sqlite3.connect(database)
+ connection.row_factory = sqlite3.Row
+ rows = connection.execute("SELECT * FROM savings_events").fetchall()
+ connection.close()
+
+ from repowise.core.savings.contracts import SavingsEvent
+
+ events = [
+ SavingsEvent.from_mapping(
+ {**dict(row), "is_usable": bool(row["is_usable"])}, accept_event_id=True
+ )
+ for row in rows
+ ]
+ from_pure = build_report(events, (), as_of=as_of)
+
+ sql, pure = asdict(from_sql), asdict(from_pure)
+ # Floats compared with a tolerance: SQLite sums the priced tokens in table
+ # order and the pure builder in list order, and float addition is not
+ # associative, so exact equality here would be a flake waiting to happen.
+ for key in ("priced_input_savings_usd", "priced_output_savings_usd"):
+ assert sql.pop(key) == pytest.approx(pure.pop(key))
+ assert sql == pure
+
+ # Guard rails on the fixture itself: if it ever stops covering the mixed
+ # cases, the equality above stops being worth much.
+ assert from_sql.priced_input_savings_usd > 0
+ assert from_sql.unpriced_saved_input_tokens > 0
+ assert len(from_sql.per_day) == 3
+ assert any(row["model"] is None for row in from_sql.per_model)
+ assert from_sql.inferred_saved_input_tokens > 0
diff --git a/tests/unit/server/test_distill_savings.py b/tests/unit/server/test_distill_savings.py
deleted file mode 100644
index 5aa609ecf..000000000
--- a/tests/unit/server/test_distill_savings.py
+++ /dev/null
@@ -1,191 +0,0 @@
-"""Unit tests for GET /api/repos/{repo_id}/distill-savings."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from httpx import AsyncClient
-
-from repowise.core.distill.store import OmissionStore
-
-from .conftest import create_test_repo
-
-
-def _seed_store(repo_dir: Path) -> None:
- store = OmissionStore(repo_dir / ".repowise" / "omissions" / "omissions.db")
- store.record_saving(
- filter_name="test_output",
- source="hook",
- command="pytest",
- raw_tokens=10_000,
- distilled_tokens=1_000,
- )
- store.record_saving(
- filter_name="git_log",
- source="cli",
- command="git log",
- raw_tokens=2_000,
- distilled_tokens=200,
- )
- store.close()
-
-
-async def test_savings_endpoint_returns_rollups(client: AsyncClient, tmp_path: Path) -> None:
- repo = await create_test_repo(client, tmp_path)
- _seed_store(Path(repo["local_path"]))
-
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings")
- assert resp.status_code == 200
- data = resp.json()
- assert data["available"] is True
- assert data["events"] == 2
- assert data["saved_tokens"] == 10_800
- assert data["pricing_model"]
- assert data["estimated_usd_saved"] > 0
- filters = {row["group"]: row for row in data["per_filter"]}
- assert filters["test_output"]["saved_tokens"] == 9_000
- assert filters["git_log"]["events"] == 1
- assert len(data["per_day"]) == 1 # both events landed today
-
-
-async def test_savings_endpoint_surfaces_mcp_drops_and_pricing(
- client: AsyncClient, tmp_path: Path
-) -> None:
- """MCP truncation drops (omissions store) ride on the response, and the
- dollar estimate covers distill + MCP priced at the resolved agent model."""
- repo = await create_test_repo(client, tmp_path)
- repo_dir = Path(repo["local_path"])
- _seed_store(repo_dir) # 10_800 distill saved tokens
- store = OmissionStore(repo_dir / ".repowise" / "omissions" / "omissions.db")
- store.put("x" * 400, source="mcp:get_risk", original_tokens=5_000, kept_tokens=0)
- store.put("y" * 400, source="mcp:get_overview", original_tokens=1_000, kept_tokens=0)
- store.close()
-
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings")
- assert resp.status_code == 200
- data = resp.json()
- assert data["mcp_events"] == 2
- assert data["mcp_tokens"] == 6_000
- tools = {row["tool"]: row for row in data["mcp_per_tool"]}
- assert tools["get_risk"]["tokens"] == 5_000
- # Distill saved_tokens stays distill-only; the dollar figure is the union
- # of distill (10_800) + MCP (6_000) priced at the resolved agent model.
- assert data["saved_tokens"] == 10_800
- assert data["pricing_agent"] == "unknown" # no transcripts in a tmp repo
- assert data["pricing_source"] == "default"
- assert data["estimated_usd_saved"] > 0
-
-
-async def test_savings_endpoint_adds_avoided_tool_call_output_credit(
- client: AsyncClient, tmp_path: Path
-) -> None:
- """Each answered counterfactual MCP query credits a little output token
- value (the tool call the agent skipped), on top of the input-priced saved
- tokens. Priced at the resolved agent's output rate."""
- import pytest
-
- from repowise.server.routers.costs import _AVOIDED_CALL_OUTPUT_TOKENS
-
- repo = await create_test_repo(client, tmp_path)
- repo_dir = Path(repo["local_path"])
- store = OmissionStore(repo_dir / ".repowise" / "omissions" / "omissions.db")
- # A counterfactual MCP saving (savings table, mcp:<tool> source) — one query.
- store.record_saving(
- filter_name="get_risk",
- source="mcp:get_risk",
- command=None,
- raw_tokens=5_000,
- distilled_tokens=500,
- )
- store.close()
-
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings")
- assert resp.status_code == 200
- data = resp.json()
- assert data["mcp_queries"] == 1
- # Default agent (no transcripts) → sonnet $3 input / $15 output per 1M.
- saved = data["saved_tokens"] + data["mcp_tokens"] # 0 distill + 4_500 mcp
- input_usd = saved * 3.0 / 1_000_000
- output_usd = 1 * _AVOIDED_CALL_OUTPUT_TOKENS * 15.0 / 1_000_000
- assert data["estimated_usd_saved"] == pytest.approx(input_usd + output_usd)
- assert data["estimated_usd_saved"] > input_usd # the credit actually applied
-
-
-async def test_savings_endpoint_no_store_is_unavailable(
- client: AsyncClient, tmp_path: Path
-) -> None:
- repo = await create_test_repo(client, tmp_path)
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings")
- assert resp.status_code == 200
- data = resp.json()
- assert data["available"] is False
- assert data["events"] == 0
- assert data["saved_tokens"] == 0
-
-
-async def test_savings_endpoint_since_filter(client: AsyncClient, tmp_path: Path) -> None:
- repo = await create_test_repo(client, tmp_path)
- repo_dir = Path(repo["local_path"])
- _seed_store(repo_dir)
- # Backdate one event past the filter window.
- import sqlite3
-
- db = repo_dir / ".repowise" / "omissions" / "omissions.db"
- conn = sqlite3.connect(db)
- conn.execute("UPDATE savings SET created_at = created_at - 10 * 86400 WHERE filter = 'git_log'")
- conn.commit()
- conn.close()
-
- from datetime import date, timedelta
-
- cutoff = (date.today() - timedelta(days=1)).isoformat()
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings", params={"since": cutoff})
- assert resp.status_code == 200
- data = resp.json()
- assert data["events"] == 1
- assert [row["group"] for row in data["per_filter"]] == ["test_output"]
-
-
-async def test_savings_endpoint_unknown_repo_404(client: AsyncClient) -> None:
- resp = await client.get("/api/repos/nope/distill-savings")
- assert resp.status_code == 404
-
-
-async def test_savings_endpoint_reports_missed_stats(
- client: AsyncClient, tmp_path: Path, monkeypatch
-) -> None:
- """The missed-savings secondary stat rides on the same response."""
- repo = await create_test_repo(client, tmp_path)
- _seed_store(Path(repo["local_path"]))
-
- import repowise.core.distill.missed as missed
-
- monkeypatch.setattr(
- missed,
- "scan_missed_savings",
- lambda root, **kw: {
- "events": 3,
- "raw_tokens": 9_000,
- "est_saved_tokens": 4_200,
- "per_filter": {},
- "window_days": 7.0,
- },
- )
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings")
- assert resp.status_code == 200
- data = resp.json()
- assert data["missed_events"] == 3
- assert data["missed_tokens_est"] == 4_200
- assert data["missed_window_days"] == 7.0
-
-
-async def test_savings_endpoint_no_transcripts_means_zero_missed(
- client: AsyncClient, tmp_path: Path
-) -> None:
- repo = await create_test_repo(client, tmp_path)
- _seed_store(Path(repo["local_path"]))
- resp = await client.get(f"/api/repos/{repo['id']}/distill-savings")
- assert resp.status_code == 200
- data = resp.json()
- assert data["missed_events"] == 0
- assert data["missed_tokens_est"] == 0
diff --git a/tests/unit/server/test_savings_endpoint.py b/tests/unit/server/test_savings_endpoint.py
new file mode 100644
index 000000000..9dfe74313
--- /dev/null
+++ b/tests/unit/server/test_savings_endpoint.py
@@ -0,0 +1,282 @@
+"""Unit tests for GET /api/repos/{repo_id}/savings.
+
+The endpoint reads the canonical ledger through the one core report service,
+so these tests are as much about what it must *not* do -- reprice history,
+credit a dead end, or collapse two calls to one tool -- as about the totals.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from httpx import AsyncClient
+
+from repowise.core.distill.store import OmissionStore
+from repowise.core.savings import recorder
+from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key
+
+from .conftest import create_test_repo
+
+#: Sonnet's input rate per million, the table's default tier. Written out so an
+#: expected dollar figure below is hand-checkable rather than recomputed with
+#: the expression under test.
+SONNET_INPUT = 3.0
+
+
+def _sidecar(repo_dir: Path) -> None:
+ """Create the sidecar. The recorder never creates one; absence is opt-out."""
+ OmissionStore(repo_dir / ".repowise" / "omissions" / "omissions.db").close()
+
+
+def _event(
+ repo_dir: Path,
+ *,
+ surface: str = "mcp",
+ agent: str = "claude_code",
+ operation: str = "get_answer",
+ baseline: int = 1_000,
+ delivered: int = 0,
+ result_state: str = "success",
+ is_usable: bool = True,
+ evidence_kind: str = "measured",
+ priced: bool = False,
+ occurred_at: str | None = None,
+) -> None:
+ event_id = new_event_id()
+ payload: dict = {
+ "event_id": event_id,
+ "idempotency_key": scoped_idempotency_key(str(repo_dir), surface, event_id),
+ "occurred_at": occurred_at or _now(),
+ "surface": surface,
+ "integration": agent,
+ "agent": agent,
+ "operation": operation,
+ "evidence_kind": evidence_kind,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": result_state,
+ "is_usable": is_usable,
+ "baseline_input_tokens": baseline,
+ "pre_budget_input_tokens": baseline,
+ "delivered_input_tokens": delivered,
+ }
+ if priced:
+ payload.update(
+ model="claude-sonnet-4-6",
+ currency="USD",
+ pricing_source="session_model:claude_code",
+ pricing_version="pricing:test",
+ input_rate_usd_per_million=SONNET_INPUT,
+ output_rate_usd_per_million=15.0,
+ )
+ assert recorder.record_event(repo_dir, payload) is True
+
+
+def _now() -> str:
+ from datetime import UTC, datetime
+
+ return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+async def test_savings_endpoint_returns_canonical_totals_and_breakdowns(
+ client: AsyncClient, tmp_path: Path
+) -> None:
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, surface="mcp", agent="claude_code", baseline=1_000)
+ _event(repo_dir, surface="distill", agent="codex", operation="git_log", baseline=400)
+
+ resp = await client.get(f"/api/repos/{repo['id']}/savings")
+ assert resp.status_code == 200
+ data = resp.json()
+
+ assert data["available"] is True
+ assert data["unique_events"] == 2
+ assert data["saved_input_tokens"] == 1_400
+ surfaces = {row["group"]: row for row in data["per_surface"]}
+ assert surfaces["mcp"]["saved_input_tokens"] == 1_000
+ assert surfaces["distill"]["saved_input_tokens"] == 400
+ # The display name rides on the payload, so no consumer needs a label map.
+ agents = {row["agent"]: row for row in data["per_agent"]}
+ assert agents["claude_code"]["agent_display_name"] == "Claude Code"
+ assert agents["codex"]["agent_display_name"] == "Codex CLI"
+ assert data["last_event_at"]
+
+
+async def test_priced_and_unpriced_savings_are_reported_separately(
+ client: AsyncClient, tmp_path: Path
+) -> None:
+ """An event carries the rate it was worth; one without a rate is not guessed at."""
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, baseline=1_000, priced=True)
+ _event(repo_dir, baseline=500, priced=False)
+
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+
+ assert data["saved_input_tokens"] == 1_500
+ assert data["priced_saved_input_tokens"] == 1_000
+ assert data["unpriced_saved_input_tokens"] == 500
+ # 1_000 tokens at $3/M. Only the priced half contributes.
+ assert data["priced_input_savings_usd"] == pytest.approx(1_000 * SONNET_INPUT / 1_000_000)
+ models = {row["group"]: row for row in data["per_model"]}
+ assert models["claude-sonnet-4-6"]["saved_input_tokens"] == 1_000
+ # The unpriced bucket is a real row, not a dropped one.
+ assert models[None]["saved_input_tokens"] == 500
+
+
+async def test_a_dead_end_saves_nothing_and_is_not_an_answered_query(
+ client: AsyncClient, tmp_path: Path
+) -> None:
+ """The legacy ledger wrote a dead end as a *negative* saving and counted it
+ as a query answered. Both contradict the contract: a call that answered
+ nothing saved nothing, and it did not answer."""
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, baseline=1_000, delivered=0)
+ _event(repo_dir, baseline=0, delivered=800, result_state="dead_end", is_usable=False)
+
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+
+ assert data["dead_ends"] == 1
+ assert data["mcp_queries_answered"] == 1 # the success, not the dead end
+ # The dead end contributed zero rather than -800.
+ assert data["saved_input_tokens"] == 1_000
+
+
+async def test_two_calls_to_one_tool_stay_independent(
+ client: AsyncClient, tmp_path: Path
+) -> None:
+ """The legacy summary applied counterfactual precedence per *tool*, so one
+ counterfactual row discarded every truncation row for that tool, including
+ unrelated later calls. The canonical ledger correlates per interaction."""
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, operation="get_risk", baseline=1_000, evidence_kind="inferred")
+ _event(repo_dir, operation="get_risk", baseline=700, evidence_kind="measured")
+
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+
+ assert data["unique_events"] == 2
+ assert data["saved_input_tokens"] == 1_700 # neither call discards the other
+ assert data["inferred_saved_input_tokens"] == 1_000
+ assert data["measured_saved_input_tokens"] == 700
+ operations = {row["group"]: row for row in data["per_operation"]}
+ assert operations["get_risk"]["events"] == 2
+
+
+async def test_no_fixed_output_credit_is_added(client: AsyncClient, tmp_path: Path) -> None:
+ """The endpoint used to add a flat 60 output tokens per answered query. A
+ saving with no output evidence now reports none rather than a invented one."""
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, baseline=1_000, priced=True)
+
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+
+ assert data["saved_output_tokens"] is None
+ assert data["priced_output_savings_usd"] == 0.0
+ # The dollar figure is exactly the input side, with nothing added on top.
+ assert data["priced_input_savings_usd"] == pytest.approx(1_000 * SONNET_INPUT / 1_000_000)
+
+
+async def test_a_repository_with_no_sidecar_is_unavailable(
+ client: AsyncClient, tmp_path: Path
+) -> None:
+ """Unavailable is not zero: nothing has been measured here."""
+ repo = await create_test_repo(client, tmp_path)
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+ assert data["available"] is False
+ assert data["saved_input_tokens"] == 0
+
+
+async def test_the_window_excludes_older_events(client: AsyncClient, tmp_path: Path) -> None:
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, baseline=1_000)
+ _event(repo_dir, baseline=400, occurred_at="2020-01-01T00:00:00.000000Z")
+
+ everything = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+ recent = (
+ await client.get(f"/api/repos/{repo['id']}/savings", params={"days": 1})
+ ).json()
+
+ assert everything["saved_input_tokens"] == 1_400
+ assert recent["saved_input_tokens"] == 1_000
+ assert recent["window_days"] == 1
+
+
+async def test_unknown_repo_404(client: AsyncClient) -> None:
+ resp = await client.get("/api/repos/nope/savings")
+ assert resp.status_code == 404
+
+
+async def test_observed_opportunities_ride_along_without_entering_the_total(
+ client: AsyncClient, tmp_path: Path, monkeypatch
+) -> None:
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, baseline=1_000)
+
+ import repowise.core.distill.missed as missed
+
+ monkeypatch.setattr(
+ missed,
+ "scan_missed_savings",
+ lambda root, **kw: {
+ "events": 3,
+ "raw_tokens": 9_000,
+ "est_saved_tokens": 4_200,
+ "per_filter": {},
+ "window_days": 7.0,
+ },
+ )
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+
+ assert data["missed_events"] == 3
+ assert data["missed_tokens_est"] == 4_200
+ # The headline is untouched by what was *not* saved.
+ assert data["saved_input_tokens"] == 1_000
+
+
+async def test_the_endpoint_and_the_core_report_agree(
+ client: AsyncClient, tmp_path: Path
+) -> None:
+ """The phase's exit criterion, asserted rather than assumed.
+
+ If the endpoint ever recomputes a total from parts instead of reading the
+ report, this is what catches it.
+ """
+ from repowise.core.savings.service import load_report
+
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = Path(repo["local_path"])
+ _sidecar(repo_dir)
+ _event(repo_dir, surface="mcp", baseline=1_000, priced=True)
+ _event(repo_dir, surface="hook", agent="codex", baseline=250)
+ _event(repo_dir, baseline=0, delivered=90, result_state="dead_end", is_usable=False)
+
+ data = (await client.get(f"/api/repos/{repo['id']}/savings")).json()
+ report = load_report(repo_dir)
+ assert report is not None
+
+ for field in (
+ "unique_events",
+ "saved_input_tokens",
+ "measured_saved_input_tokens",
+ "inferred_saved_input_tokens",
+ "priced_saved_input_tokens",
+ "unpriced_saved_input_tokens",
+ "priced_input_savings_usd",
+ "mcp_queries_answered",
+ "dead_ends",
+ ):
+ assert data[field] == pytest.approx(getattr(report, field)), field