osdy-pi 1.8.0 → 1.10.0

package/README.md

@@ -6,11 +6,13 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 ## Release highlights
 
-The **1.8.0 release candidate** includes the changes below; npm publication is not yet confirmed.
+**1.10.0 adds four-page local usage analytics** with shared period and profile/provider/model filters, keyboard navigation, and metadata-only history. The bundle retains **20 themes**. These highlights describe the 1.10.0 release source; verify npm availability and the resolved version before installing.
 
 | Area | What ships |
 | --- | --- |
-| New themes (included starting in 1.8.0) | Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute bring the bundle to 18 themes. |
+| Local analytics (1.10.0) | `/osdy-usage` opens Summary, Profiles, Models, and History pages for recorded tokens and estimated cost—not billing or subscription quota. |
+| Themes introduced in 1.9.0 | Halloween and Halloween Killer add two dark palettes, bringing the bundle to 20 themes. |
+| Themes introduced in 1.8.0 | Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute. |
 | Message cards | Pi-native colored user cards without emojis and plain assistant Markdown preceded by a separate `🦝` transcript row. |
 | Header and mascot | A theme-aware `neon` header and selectable `bts` mascot, both responsive and persisted independently. |
 | Accounts | `/osdy-account` switches Codex profiles in place with atomic activation, rollback, bounded auth files, and process-safe locks. |
@@ -37,7 +39,7 @@ The **1.8.0 release candidate** includes the changes below; npm publication is n
    pi install git:github.com/OsdyOrtiz/Osdy-Pi
    ```
 
-   Already using a pinned npm version? `pi update` does not move a pinned version. First-party TODO is included starting in 1.5.0. Starting in 1.6.0, `/osdy-pi uninstall` and explicit agent provider modes are available. Check the resolved version when installing from npm or use a 1.6.0-or-later checkout to try these changes. Installing Osdy does not automatically install Joker; see [explicit agent provider modes](#explicit-agent-provider-modes-in-normal-pi).
+   Check the resolved npm version: local analytics requires 1.10.0 or later. Once 1.10.0 is available on npm, `pi install npm:osdy-pi@1.10.0` selects it explicitly. For an unpinned installation, use `pi update`; it does not move a pinned version, so replace an older pin explicitly. First-party TODO is included starting in 1.5.0; `/osdy-pi uninstall` and explicit agent provider modes start in 1.6.0. Installing Osdy does not automatically install Joker; see [explicit agent provider modes](#explicit-agent-provider-modes-in-normal-pi).
 
 2. Start Pi:
 
@@ -45,7 +47,7 @@ The **1.8.0 release candidate** includes the changes below; npm publication is n
    pi
    ```
 
-Osdy Pi's own extension and themes are bundled—do not install them separately. The **1.8.0 release candidate** bundles **18 themes**, including Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute starting in 1.8.0. Check your installed npm version; publication of 1.8.0 is not yet confirmed. Launch through `osdy-pi` (or `npm run pi:dev`) to activate a valid Osdy default account into Pi's shared agent directory before Pi starts. With no default, Pi remains unmanaged; run `/osdy-account` to create a profile and establish a default. On session start, Osdy Pi restores its persisted enabled state when a UI is available and preserves your selected Pi theme. When disabled, it leaves Gentle Shell (or Pi's native UI) untouched.
+Osdy Pi's own extension and themes are bundled—do not install them separately. Version **1.10.0** bundles **20 themes**: Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute were introduced in 1.8.0; Halloween and Halloween Killer are added in 1.9.0. Check your installed npm version to see which themes are available. Launch through `osdy-pi` (or `npm run pi:dev`) to activate a valid Osdy default account into Pi's shared agent directory before Pi starts. With no default, Pi remains unmanaged; run `/osdy-account` to create a profile and establish a default. On session start, Osdy Pi restores its persisted enabled state when a UI is available and preserves your selected Pi theme. When disabled, it leaves Gentle Shell (or Pi's native UI) untouched.
 
 ### Optional: isolated `osdy` command
 
@@ -249,11 +251,12 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 
 | Area | Included behavior |
 | --- | --- |
-| Themes | 18 built-in themes, including Osdy, Kanagawa, Dracula, Gruvbox, Nord, Rosé Pine, Daniela Cute, Catppuccin, Matrix, and Lucent Orange palettes |
+| Themes | 20 built-in themes, including Osdy, Kanagawa, Dracula, Gruvbox, Nord, Rosé Pine, Daniela Cute, Halloween, Halloween Killer, Catppuccin, Matrix, and Lucent Orange palettes |
 | Header and mascot | Independently selectable `osdy-theme`/`neon` headers and `current`/`bts` mascots |
 | Messages | Native colored user cards without emojis and plain assistant Markdown with a separate assistant `🦝` row |
 | Input | Responsive auto editor by default, with selectable simple Pi-native or extended framed modes |
 | Status | Theme-aware Braille spinner and animated working label, responsive footer metrics, dynamic extension statuses, and Codex subscription quota with low-capacity emphasis |
+| Local analytics | Four keyboard-selectable pages with shared filters, token charts, estimated cost, and private metadata-only history from new assistant turns |
 | Git | Working-tree summary and a centered, filterable diff panel |
 | Audio | Optional event sounds on macOS and Windows |
 
@@ -263,10 +266,10 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 
 ### Themes
 
-The bundle contains **18 themes**; Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute are included starting in **1.8.0**. To try the **1.8.0 release candidate** before npm publication is confirmed:
+Version **1.10.0** contains **20 themes**. Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute were introduced in **1.8.0**; Halloween and Halloween Killer were added in **1.9.0**. To try the themes from a checkout:
 
-1. Run `npm run pi:dev` from the 1.8.0 checkout, or `/reload` if that checkout is already loaded in Pi.
-2. Open `/settings` → **Theme** and select `osdy-pi-gruvbox-dark`, `osdy-pi-nord`, `osdy-pi-rose-pine`, `osdy-pi-daniela-cute`, or another name below.
+1. Run `npm run pi:dev` from the 1.10.0 checkout, or `/reload` if that checkout is already loaded in Pi.
+2. Open `/settings` → **Theme** and select `osdy-pi-gruvbox-dark`, `osdy-pi-nord`, `osdy-pi-rose-pine`, `osdy-pi-daniela-cute`, `osdy-pi-halloween`, `osdy-pi-halloween-killer`, or another name below.
 
 | Theme | Use |
 | --- | --- |
@@ -282,6 +285,8 @@ The bundle contains **18 themes**; Gruvbox Dark, Nord, Rosé Pine base dark, and
 | `osdy-pi-nord` | [Nord](https://www.nordtheme.com/docs/colors-and-palettes) dark palette: cool, restrained Polar Night, Snow Storm, Frost, and Aurora colors. |
 | `osdy-pi-rose-pine` | [Rosé Pine](https://rosepinetheme.com/palette/ingredients/) base dark palette: soft colors, not Moon or Dawn. |
 | `osdy-pi-daniela-cute` | Daniela Cute: navy panels/export page (`#0B1220`), blue cards (`#111F33`), borders (`#253A55`), blue accents (`#3584E4`), main text (`#D8E2EF`), secondary text (`#93A6BE`), and selection (`#193655`). Distinct status and syntax colors remain; the terminal background remains unchanged. |
+| `osdy-pi-halloween` | Pumpkin orange, spectral violet, and lime accents on dark plum panels, with warm text and distinct success/error colors. |
+| `osdy-pi-halloween-killer` | Gothic/slasher dark palette: near-black panels, blood-red and violet accents, bone-colored text, and sage success indicators distinct from red errors. |
 | `osdy-pi-catppuccin-latte` | Catppuccin Latte light palette. |
 | `osdy-pi-catppuccin-frappe` | Catppuccin Frappé dark palette. |
 | `osdy-pi-catppuccin-macchiato` | Catppuccin Macchiato dark palette. |
@@ -355,6 +360,7 @@ The enabled state, editor mode, working-tree visibility preference, header, and
 | Diff | `/osdy-pi diff` |
 | Package | `/osdy-pi uninstall` |
 | Codex subscription | `/usage` |
+| Local usage analytics (starting in 1.10.0) | `/osdy-usage` |
 
 `/osdy-pi uninstall` finds a unique Osdy Pi package in Pi's configured package list and asks you to confirm its exact source and user/project scope before calling Pi's `remove` command. Run it from a trusted project with interactive UI. Git registrations are checked against Pi's host/path identity; a local registration must point to this running extension's package root and have a matching manifest. Ambiguous or changed registrations, unrecognized sources, and cancelled confirmation remove nothing. It removes only the Pi package registration, not Osdy profiles, accounts, the globally installed CLI, or other packages. Restart Pi afterward to unload the extension. If no unique source is found, inspect `pi list` and use `pi remove <source> [-l]` manually.
 
@@ -372,9 +378,41 @@ Usage loads once when the session starts and refreshes when the modal opens or `
 
 > **Privacy:** OAuth is resolved only through Pi's `modelRegistry`. Osdy Pi does not read `auth.json`, persist or log credentials, or display account IDs, tokens, response bodies, or endpoint internals in the UI. Requests use a fixed HTTPS endpoint with bounded timeout, response size, and redirects.
 
+### Local usage analytics (starting in 1.10.0)
+
+Run `/osdy-usage` in interactive terminal Pi. **Summary** opens by default; use Tab / Shift+Tab or `1`–`4` to choose a focused page. Period, filters and the loaded snapshot are shared; switching pages resets scroll without reading history or making network requests.
+
+| Page | Content |
+| --- | --- |
+| `1` Summary | Total tokens, recorded turns, estimated USD and compact timeline |
+| `2` Profiles | Every profile's consumption ranking |
+| `3` Models | Every provider/model ranking and exact input/output/cache composition of the selection; use `f` to inspect one model |
+| `4` History | Timeline and exact local bucket values, timezone and repeated DST hours with UTC offsets |
+
+Narrow terminals stack metrics and wrap names; every group remains reachable by scrolling. Shares use the selected total tokens; bars scale to each ranking's maximum. Loading, stale, scan-limit/warning and unpriced/partial-cost states remain on every page and in help. Sticky status lines wrap instead of concealing cost status behind scan warnings, including at End. When height is scarce, statuses take priority over optional headings, charts and footer controls; the active page remains visible when space permits. Press `?` for methodology and full controls, then `?` again to return. Choosing a page also leaves help without discarding filters.
+
+This is separate from the unchanged `/usage` subscription quota panel. RPC, JSON and print modes receive a short notification instead of charts. The four-page UI passed independent scripted synthetic PTY checks for navigation, shared selection and responsive statuses at 12/32/100 columns, including a five-row terminal. Human visual confirmation and provider-backed capture remain unverified.
+
+| Control | Action |
+| --- | --- |
+| Tab / Shift+Tab, `1` / `2` / `3` / `4` | Cycle pages with wrap; jump to Summary / Profiles / Models / History |
+| `?` | Toggle methodology/control help; `?` returns to the selected page |
+| `d` / `w` / `m`, left / right | Local calendar day, Monday-based week or month; previous / next range (not pages) |
+| `p` / `v` / `f`, `x` | Cycle profile / provider / model filters; reset filters |
+| `r`, arrows / Page Up / Page Down / Home / End | Refresh history; scroll |
+| Esc / `q` / Ctrl+C | Close, including from help |
+
+**Collection starts with new assistant turns begun while Osdy is enabled**, after session settings finish loading. `/osdy-pi off` stops collection; `/osdy-pi on` enables it for subsequent turns. Existing history remains viewable while disabled. No old-session import or replay/compaction backfill occurs. Processes without this extension and non-message/background usage (including summaries and cache warming) are not recorded.
+
+**Storage and privacy:** metadata-only private JSONL shards live at `<active agent dir>/extensions/osdy-pi/usage-analytics/`: an absolute `PI_CODING_AGENT_DIR`, otherwise `~/.pi/agent/extensions/osdy-pi/usage-analytics/`. No files are created until an actual append. Same-agent profiles share history; isolated agent directories keep separate histories. Records contain timestamps, session/entry IDs, the selected Codex profile label, actual provider/model, token counts and nullable estimated cost—no prompts, responses, credentials, account IDs or session paths. Analytics never reads auth files. No automatic deletion or retention engine is provided.
+
+Codex labels are snapshotted at turn start, not verified account identities; later switches cannot reattribute that turn. Other providers or missing labels are **unmanaged**. Rename/delete does not rewrite old labels; case-only differences share profile identity. Calendar ranges use the machine's local timezone (shown in the panel), including daylight-saving boundaries.
+
+Costs are Pi's per-message estimates, **not quota, a provider bill, or confirmed spending**. No matching records, entirely unavailable costs and reported zero are distinct states. Partial estimates show the unpriced turn count. Zero-priced models remain zero; absent prices remain unknown. History scans are bounded and prefer recent data, so limited/corrupt coverage warnings mean totals may omit records. Write failures produce generic warnings; subsequent reads report unavailable/incomplete coverage rather than presenting those totals as complete.
+
 ## Native message cards
 
-Pi renders the colored user card and assistant Markdown natively. User messages have no emoji; Osdy Pi places a separate `🦝` transcript entry before each assistant response with visible text, not inside message content. Previously saved user `👤` entries remain in session history but render no row on replay. Selecting only the native message keeps its body clean; a wide selection that includes the emoji row copies the emoji too. Assistant markers persist with the session but do not enter model context. The installed Pi 0.87.1 does not use `assistantMessage*` theme palette keys, so these keys do not create a native assistant card. Osdy does not install a Markdown transformer or change streaming. The current user card colors remain unchanged. Try both roles in your selected theme with `npm run pi:dev`; terminal rendering and selection still need a live visual check. When disabled, Osdy does not add new markers.
+Pi renders the colored user card and assistant Markdown natively. User messages have no emoji; Osdy Pi places a separate `🦝` transcript entry before each assistant response with visible text, not inside message content. Previously saved user `👤` entries remain in session history but render no row on replay. Selecting only the native message keeps its body clean; a wide selection that includes the emoji row copies the emoji too. Assistant markers persist with the session but do not enter model context. Earlier checks on Pi 0.87.1 found that it did not use `assistantMessage*` theme palette keys; these keys alone should not be assumed to create a native assistant card. Osdy does not install a Markdown transformer or change streaming. The current user card colors remain unchanged. Try both roles in your selected theme with `npm run pi:dev`; terminal rendering and selection still need a live visual check. When disabled, Osdy does not add new markers.
 
 ## Editor and working indicator
 

package/extensions/osdy-pi/runtime.test.ts

@@ -408,8 +408,8 @@ void test("every registered theme defines native user message colors", () => {
 		readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
 	) as { pi: { themes: string[] } };
 
-	assert.equal(manifest.pi.themes.length, 18);
-	assert.equal(new Set(manifest.pi.themes).size, 18, "theme registrations must be unique");
+	assert.equal(manifest.pi.themes.length, 20);
+	assert.equal(new Set(manifest.pi.themes).size, 20, "theme registrations must be unique");
 	for (const themePath of manifest.pi.themes) {
 		const theme = JSON.parse(
 			readFileSync(
@@ -438,17 +438,21 @@ void test("new dark themes are explicitly registered with unique matching names"
 		return theme.name;
 	});
 	assert.equal(new Set(names).size, names.length, "theme names must be unique");
-	for (const name of ["osdy-pi-gruvbox-dark", "osdy-pi-nord", "osdy-pi-rose-pine", "osdy-pi-daniela-cute"]) {
+	for (const name of ["osdy-pi-gruvbox-dark", "osdy-pi-nord", "osdy-pi-rose-pine", "osdy-pi-daniela-cute", "osdy-pi-halloween", "osdy-pi-halloween-killer"]) {
 		assert.equal(manifest.pi.themes.filter((path) => path === `./themes/${name}.json`).length, 1);
 		assert.equal(names.filter((registered) => registered === name).length, 1);
 	}
 });
 
-void test("README documents all 18 themes including Daniela Cute", () => {
+void test("README documents all 20 themes including both Halloween palettes", () => {
 	const readme = readFileSync(new URL("../../README.md", import.meta.url), "utf8");
-	assert.match(readme, /\*\*18 themes\*\*/);
-	assert.match(readme, /18 built-in themes/);
+	assert.match(readme, /\*\*20 themes\*\*/);
+	assert.match(readme, /20 built-in themes/);
+	assert.doesNotMatch(readme, /\b18 (?:built-in )?themes\b/);
+	assert.equal(readme.match(/^\| `osdy-pi-[^`]+` \|/gm)?.length, 20);
 	assert.match(readme, /\| `osdy-pi-daniela-cute` \| Daniela Cute/);
+	assert.match(readme, /\| `osdy-pi-halloween` \|.*[Pp]umpkin.*violet.*lime/);
+	assert.match(readme, /\| `osdy-pi-halloween-killer` \|.*[Gg]othic.*blood.red.*violet/);
 });
 
 void test("Tokyo Night retains its approved native user card colors", () => {

package/extensions/osdy-pi/runtime.ts

@@ -62,6 +62,7 @@ import { registerTodosCommand } from "./todo-command.js";
 import { createTodoSessionStore } from "./todo-session.js";
 import { registerMessageRoleMarkers } from "./message-role-markers.js";
 import { registerTodoWidget } from "./todo-widget.js";
+import { registerUsageAnalytics } from "./usage-analytics.js";
 
 function scheduleOsdyRefresh(
 	delayMs: number,
@@ -946,6 +947,7 @@ export function registerOsdyPi(pi: ExtensionAPI): void {
 		| ReturnType<typeof createResponsiveCoordinator>
 		| undefined;
 	let sessionContext: ExtensionContext | undefined;
+	let usageSettingsReady = false;
 	let codexUsageAbort: AbortController | undefined;
 	const refreshCurrentCodexUsage = async (
 		ctx: ExtensionContext,
@@ -1026,6 +1028,7 @@ export function registerOsdyPi(pi: ExtensionAPI): void {
 		}
 	});
 	pi.on("session_shutdown", () => {
+		usageSettingsReady = false;
 		codexUsageAbort?.abort();
 		codexUsageAbort = undefined;
 		state.codexUsage = { kind: "idle" };
@@ -1036,6 +1039,7 @@ export function registerOsdyPi(pi: ExtensionAPI): void {
 		sessionContext = undefined;
 	});
 	pi.on("session_start", async (_event, ctx) => {
+		usageSettingsReady = false;
 		cancelOsdyRefreshes();
 		stopResponsive();
 		sessionContext = ctx;
@@ -1043,6 +1047,7 @@ export function registerOsdyPi(pi: ExtensionAPI): void {
 		if (sessionContext !== ctx) return;
 		state.fallbackEditorFactory = ctx.ui.getEditorComponent();
 		state.enabled = editorSettings.enabled;
+		usageSettingsReady = true;
 		state.editorMode = editorSettings.editorMode;
 		state.workingTreeEnabled = editorSettings.workingTreeEnabled;
 		state.headerVariant = editorSettings.headerVariant;
@@ -1065,6 +1070,7 @@ export function registerOsdyPi(pi: ExtensionAPI): void {
 		void refreshCurrentCodexUsage(ctx);
 	});
 
+	registerUsageAnalytics(pi, { isEnabled: () => usageSettingsReady && state.enabled });
 	registerUsageCommand(
 		pi,
 		state,

package/extensions/osdy-pi/usage-analytics-data.ts

@@ -0,0 +1,208 @@
+export interface UsageRecord {
+	version: 1;
+	timestamp: number;
+	sessionId: string;
+	entryId: string;
+	profile: string | null;
+	provider: string;
+	model: string;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	estimatedCost: number | null;
+}
+
+function text(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0 && value.length <= 256 && !/[\p{Cc}\p{Cf}]/u.test(value);
+}
+function identifier(value: unknown): value is string {
+	return text(value) && !value.includes("/") && !value.includes("\\");
+}
+function count(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function validProfile(value: unknown): value is string | null {
+	return value === null || (
+		typeof value === "string" &&
+		/^[A-Za-z0-9][A-Za-z0-9-]{0,62}$/.test(value) &&
+		!["default", "profiles", "auth.json"].includes(value.toLowerCase())
+	);
+}
+
+/** Narrow unknown input and copy only approved metadata; absent cost means unavailable. */
+export function parseUsageRecord(value: unknown): UsageRecord | null {
+	if (typeof value !== "object" || value === null) return null;
+	if (
+		!("version" in value) || value.version !== 1 ||
+		!("timestamp" in value) || !count(value.timestamp) || value.timestamp > 8.64e15
+	) return null;
+	if (
+		!("sessionId" in value) || !identifier(value.sessionId) ||
+		!("entryId" in value) || !identifier(value.entryId)
+	) return null;
+	if (
+		!("profile" in value) || !validProfile(value.profile) ||
+		!("provider" in value) || !text(value.provider) ||
+		!("model" in value) || !text(value.model)
+	) return null;
+	if (
+		!("input" in value) || !count(value.input) ||
+		!("output" in value) || !count(value.output) ||
+		!("cacheRead" in value) || !count(value.cacheRead) ||
+		!("cacheWrite" in value) || !count(value.cacheWrite)
+	) return null;
+	const cost = "estimatedCost" in value ? value.estimatedCost : null;
+	if (cost !== null && cost !== undefined && (
+		typeof cost !== "number" || !Number.isFinite(cost) || cost < 0 || cost > Number.MAX_SAFE_INTEGER
+	)) return null;
+	return {
+		version: 1,
+		timestamp: value.timestamp,
+		sessionId: value.sessionId,
+		entryId: value.entryId,
+		profile: value.profile,
+		provider: value.provider,
+		model: value.model,
+		input: value.input,
+		output: value.output,
+		cacheRead: value.cacheRead,
+		cacheWrite: value.cacheWrite,
+		estimatedCost: cost ?? null,
+	};
+}
+
+/** Tagged keys prevent a named "unmanaged" profile colliding with missing attribution. */
+export function profileKey(profile: string | null): string {
+	if (!validProfile(profile)) throw new Error("Invalid profile label");
+	return profile === null ? "unmanaged:" : `profile:${profile.toLowerCase()}`;
+}
+
+export type UsagePeriodKind = "day" | "week" | "month";
+export interface UsagePeriod { kind: UsagePeriodKind; start: number; end: number }
+
+function civilMidnight(year: number, month: number, day: number): Date {
+	// Build each boundary independently: a skipped midnight may normalize to 01:00,
+	// but that hour must not carry into the next civil date. setFullYear handles 0–99.
+	const boundary = new Date(0);
+	boundary.setFullYear(year, month, day);
+	boundary.setHours(0, 0, 0, 0);
+	return boundary;
+}
+
+export function usagePeriod(kind: UsagePeriodKind, anchor: Date): UsagePeriod {
+	if (!["day", "week", "month"].includes(kind) || !Number.isFinite(anchor.getTime())) throw new Error("Invalid calendar period");
+	const year = anchor.getFullYear();
+	const month = anchor.getMonth();
+	const day = kind === "month" ? 1 : anchor.getDate() - (kind === "week" ? (anchor.getDay() + 6) % 7 : 0);
+	const start = civilMidnight(year, month, day);
+	const end = kind === "month" ? civilMidnight(year, month + 1, 1) : civilMidnight(year, month, day + (kind === "week" ? 7 : 1));
+	if (!Number.isFinite(start.getTime()) || !Number.isFinite(end.getTime())) throw new Error("Calendar period out of range");
+	return { kind, start: start.getTime(), end: end.getTime() };
+}
+function validatePeriod(period: UsagePeriod): void {
+	const canonical = usagePeriod(period.kind, new Date(period.start));
+	if (canonical.start !== period.start || canonical.end !== period.end) throw new Error("Invalid calendar period boundaries");
+}
+export function adjacentPeriod(period: UsagePeriod, direction: -1 | 1): UsagePeriod {
+	validatePeriod(period);
+	if (direction !== -1 && direction !== 1) throw new Error("Invalid navigation direction");
+	const anchor = new Date(period.start);
+	if (period.kind === "month") anchor.setMonth(anchor.getMonth() + direction);
+	else anchor.setDate(anchor.getDate() + direction * (period.kind === "week" ? 7 : 1));
+	return usagePeriod(period.kind, anchor);
+}
+
+export interface UsageTotals {
+	records: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	/** Recorded estimates, never authoritative billing or subscription quota. */
+	estimatedCost: number;
+	unavailableCostRecords: number;
+}
+export interface UsageBucket { start: number; end: number; totals: UsageTotals }
+export interface UsageProfileGroup { key: string; profile: string | null; totals: UsageTotals }
+export interface UsageModelGroup { provider: string; model: string; totals: UsageTotals }
+export interface UsageFilter { profile?: string | null; provider?: string; model?: string }
+export interface UsageAggregation {
+	period: UsagePeriod;
+	totals: UsageTotals;
+	buckets: UsageBucket[];
+	profiles: UsageProfileGroup[];
+	models: UsageModelGroup[];
+}
+function emptyTotals(): UsageTotals {
+	return { records: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, estimatedCost: 0, unavailableCostRecords: 0 };
+}
+function add(totals: UsageTotals, record: UsageRecord): void {
+	totals.records++;
+	totals.input += record.input;
+	totals.output += record.output;
+	totals.cacheRead += record.cacheRead;
+	totals.cacheWrite += record.cacheWrite;
+	if (record.estimatedCost === null) totals.unavailableCostRecords++;
+	else totals.estimatedCost += record.estimatedCost;
+	for (const value of [totals.records, totals.input, totals.output, totals.cacheRead, totals.cacheWrite, totals.estimatedCost]) {
+		if (!Number.isFinite(value) || value > Number.MAX_SAFE_INTEGER) throw new Error("Usage totals exceed safe numeric range");
+	}
+}
+function compare(left: string, right: string): number { return left < right ? -1 : left > right ? 1 : 0; }
+
+/** Local timezone calendar boundaries, half-open intervals, and explicit empty buckets.
+ * Repeated fall-back hours are separate timestamped buckets; missing spring hours are absent.
+ */
+export function aggregateUsage(records: readonly UsageRecord[], period: UsagePeriod, filter: UsageFilter = {}): UsageAggregation {
+	validatePeriod(period);
+	if (filter.profile !== undefined) profileKey(filter.profile);
+	if ((filter.provider !== undefined && !text(filter.provider)) || (filter.model !== undefined && !text(filter.model))) throw new Error("Invalid model filter");
+	const buckets: UsageBucket[] = [];
+	let cursor = period.start;
+	while (cursor < period.end) {
+		const next = new Date(cursor);
+		// Local hour boundaries realign after fractional-hour DST jumps; elapsed hours
+		// retain repeated fall-back hours instead of skipping straight to the next label.
+		if (period.kind === "day") {
+			next.setHours(next.getHours() + 1, 0, 0, 0);
+			next.setTime(Math.min(next.getTime(), cursor + 3600000));
+		} else next.setTime(civilMidnight(next.getFullYear(), next.getMonth(), next.getDate() + 1).getTime());
+		const end = Math.min(next.getTime(), period.end);
+		buckets.push({ start: cursor, end, totals: emptyTotals() });
+		cursor = end;
+	}
+	const totals = emptyTotals();
+	const profiles = new Map<string, UsageProfileGroup>();
+	const models = new Map<string, UsageModelGroup>();
+	for (const input of records) {
+		const record = parseUsageRecord(input);
+		if (!record) throw new Error("Invalid usage record");
+		if (record.timestamp < period.start || record.timestamp >= period.end) continue;
+		const key = profileKey(record.profile);
+		if (filter.profile !== undefined && key !== profileKey(filter.profile)) continue;
+		if (filter.provider !== undefined && record.provider !== filter.provider) continue;
+		if (filter.model !== undefined && record.model !== filter.model) continue;
+		add(totals, record);
+		const bucket = buckets.find((item) => record.timestamp >= item.start && record.timestamp < item.end);
+		if (bucket) add(bucket.totals, record);
+		let profile = profiles.get(key);
+		if (!profile) {
+			profile = { key, profile: record.profile, totals: emptyTotals() };
+			profiles.set(key, profile);
+		}
+		add(profile.totals, record);
+		const modelKey = JSON.stringify([record.provider, record.model]);
+		let model = models.get(modelKey);
+		if (!model) {
+			model = { provider: record.provider, model: record.model, totals: emptyTotals() };
+			models.set(modelKey, model);
+		}
+		add(model.totals, record);
+	}
+	return {
+		period: { ...period }, totals, buckets,
+		profiles: [...profiles.values()].sort((a, b) => compare(a.key, b.key)),
+		models: [...models.values()].sort((a, b) => compare(a.provider, b.provider) || compare(a.model, b.model)),
+	};
+}