osdy-pi 1.9.0 → 1.11.0

package/README.md

@@ -1,16 +1,18 @@
 # Osdy Pi — a themed, responsive Pi workspace
 
-Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive terminal presentation with a header, editor, working indicator, and Git view. Visit the [Osdy landing page](https://landing-osdy.vercel.app/).
+Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive terminal presentation with a header, editor, working indicator, and Git view. Visit the [Osdy landing page](https://osdy-pi.vercel.app/).
 
 <img width="1857" height="847" alt="Osdy Pi interface" src="https://github.com/user-attachments/assets/028eeb14-3f43-4f1c-9603-0c55a8d2856d" />
 
 ## Release highlights
 
-**1.9.0 adds Halloween and Halloween Killer**, bringing the bundle to **20 themes**. The table below summarizes these additions and existing features.
+**1.11.0 adds three Spider-Man-inspired dark palettes**, bringing the bundle to **23 themes**. It retains the four-page local usage analytics introduced in 1.10.0, with shared period and profile/provider/model filters, keyboard navigation, and metadata-only history. These highlights describe the 1.11.0 release source; verify npm availability and the resolved version before installing.
 
 | Area | What ships |
 | --- | --- |
-| New themes (1.9.0) | Halloween and Halloween Killer add two dark palettes, bringing the bundle to 20 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.11.0 | Spider-Man Classic, Miles Morales, and Spider-Verse add three distinct dark palettes. |
+| Themes introduced in 1.9.0 | Halloween and Halloween Killer add two dark palettes. |
 | 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. |
@@ -38,7 +40,7 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
    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: the Spider-Man-inspired themes require 1.11.0 or later; local analytics requires 1.10.0 or later. To select this release explicitly, use `pi install npm:osdy-pi@1.11.0` once it is available on npm. 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:
 
@@ -46,7 +48,7 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
    pi
    ```
 
-Osdy Pi's own extension and themes are bundled—do not install them separately. Version **1.9.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.
+Osdy Pi's own extension and themes are bundled—do not install them separately. Version **1.11.0** bundles **23 themes**, including Spider-Man Classic, Miles Morales, and Spider-Verse: 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. 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
 
@@ -250,11 +252,12 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 
 | Area | Included behavior |
 | --- | --- |
-| Themes | 20 built-in themes, including Osdy, Kanagawa, Dracula, Gruvbox, Nord, Rosé Pine, Daniela Cute, Halloween, Halloween Killer, Catppuccin, Matrix, and Lucent Orange palettes |
+| Themes | 23 built-in themes, including Osdy, Kanagawa, Dracula, Gruvbox, Nord, Rosé Pine, Daniela Cute, Halloween, Halloween Killer, Catppuccin, Matrix, Lucent Orange, and three Spider-Man-inspired 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 |
 
@@ -264,10 +267,10 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 
 ### Themes
 
-Version **1.9.0** contains **20 themes**. Gruvbox Dark, Nord, Rosé Pine base dark, and Daniela Cute were introduced in **1.8.0**; **1.9.0** adds Halloween and Halloween Killer. To try the themes from a checkout:
+Version **1.11.0** contains **23 themes**, including the new Spider-Man Classic, Miles Morales, and Spider-Verse palettes. 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.9.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.
+1. Run `npm run pi:dev` from the 1.11.0 checkout, or `/reload` if that checkout is already loaded in Pi.
+2. Open `/settings` → **Theme** and select `osdy-pi-spider-man-classic`, `osdy-pi-miles-morales`, `osdy-pi-spider-verse`, or another name below.
 
 | Theme | Use |
 | --- | --- |
@@ -291,6 +294,9 @@ Version **1.9.0** contains **20 themes**. Gruvbox Dark, Nord, Rosé Pine base da
 | `osdy-pi-catppuccin-mocha` | Catppuccin Mocha dark palette. |
 | `osdy-pi-matrix` | OpenCode Matrix dark palette. |
 | `osdy-pi-lucent-orange` | Lucent Orange dark palette with terminal-background passthrough. |
+| `osdy-pi-spider-man-classic` | Classic Peter Parker: night-blue panels, red accents, and web-white text, with blue links and distinct green success/yellow warning indicators. |
+| `osdy-pi-miles-morales` | Miles Morales: black and charcoal panels with intense red accents, pale text, and distinct green success/yellow warning indicators. |
+| `osdy-pi-spider-verse` | Spider-Verse: dark violet panels, red, electric-blue, and magenta highlights, with readable syntax and distinct green success/yellow warning indicators. |
 
 Osdy Pi preserves your selected Pi theme when it enables, reapplies, or disables its UI. Choose any theme in Pi:
 
@@ -358,6 +364,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.
 
@@ -375,9 +382,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, 20);
-	assert.equal(new Set(manifest.pi.themes).size, 20, "theme registrations must be unique");
+	assert.equal(manifest.pi.themes.length, 23);
+	assert.equal(new Set(manifest.pi.themes).size, 23, "theme registrations must be unique");
 	for (const themePath of manifest.pi.themes) {
 		const theme = JSON.parse(
 			readFileSync(
@@ -438,18 +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", "osdy-pi-halloween", "osdy-pi-halloween-killer"]) {
+	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", "osdy-pi-spider-man-classic", "osdy-pi-miles-morales", "osdy-pi-spider-verse"]) {
 		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 20 themes including both Halloween palettes", () => {
+void test("README documents all 23 themes including three Spider-Man-inspired palettes", () => {
 	const readme = readFileSync(new URL("../../README.md", import.meta.url), "utf8");
-	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, /\*\*23 themes\*\*/);
+	assert.match(readme, /23 built-in themes/);
+	assert.doesNotMatch(readme, /\b(?:18|20) (?:built-in )?themes\b/);
+	assert.equal(readme.match(/^\| `osdy-pi-[^`]+` \|/gm)?.length, 23);
+	for (const name of ["osdy-pi-spider-man-classic", "osdy-pi-miles-morales", "osdy-pi-spider-verse"]) {
+		assert.ok(readme.includes(`| \`${name}\` |`), `${name}: documented theme row`);
+	}
 	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/);

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)),
+	};
+}