@nijaru/pi-peak-hours 0.0.2 → 0.0.4

package/README.md

@@ -4,11 +4,11 @@ Correct pi's recorded cost for providers that bill by time of day, and show the
 
 DeepSeek is the current example. Its peak windows are `01:00–04:00` and `06:00–10:00` UTC, Monday to Friday, and off-peak is half the peak rate. pi has no notion of time-of-day pricing: `usage.cost` is computed once from the model's flat rates when usage is finalized, so a session is over- or understated by up to 2x depending on which side of the schedule the recorded rate sits.
 
-Two schedules ship built in, because pi's own catalog is inconsistent about that side: `deepseek/deepseek-flash` direct is listed at its **peak** rate while the same model through OpenRouter is listed at its **off-peak** rate. The DeepSeek schedule therefore scales the OpenRouter route by 2 during peak windows and leaves the direct provider alone; naming your own providers in the config replaces both.
+Both built-in entries follow what DeepSeek advertises: ×2 inside those windows and ×1 outside, because the published rate is the off-peak one and peak is a surcharge on it. Since the extension scales whatever rate pi recorded, an entry is right only where that rate really is the off-peak one — true of the OpenRouter route, which pi rates at `0.15/0.60`, and of the direct provider wherever `models.json` pins it to off-peak. Stock pi.dev rates direct as `deepseek-flash` at `0.30/1.20`, its peak number, so the configuration below inverts that one entry; the pair exists because each entry is scoped, covering the DeepSeek models on both routes without claiming unrelated OpenRouter models. Naming your own providers replaces both.
 
 This extension rewrites `usage.cost` on the finalized assistant message, so the footer total, the per-model breakdown, and the HTML export all reflect the billed rate. The status line quotes the rate in force for the selected model — `· ▲ peak $0.30/$1.20/M` during a peak window, `· $0.15/$0.60/M` off it — with `▲ peak` or `▼ off-peak` added when the hour costs more or less than the rate pi recorded. `/peak-hours status` names the schedule behind it.
 
-The quoted rate is pi's recorded rate scaled by the schedule, so it always agrees with the cost written to the session. Where pi's rate table is stale or wrong for your route, the quoted rate is stale in the same way — the extension corrects the shape of the bill, not the base rate.
+The quoted rate is pi's recorded rate scaled by the schedule, so it always agrees with the cost written to the session. It describes the hour in force rather than a particular request, though: a request that started before a boundary is billed by its start time while the footer has already moved to the new hour. Where pi's rate table is stale or wrong for your route, the quoted rate is stale in the same way — the extension corrects the shape of the bill, not the base rate.
 
 ## Install
 
@@ -25,7 +25,7 @@ Or copy `extensions/index.ts` to `~/.pi/agent/extensions/` for a single-machine
 /peak-hours on|off    # toggle correction; persists to pi-peak-hours.json
 ```
 
-The footer status is a separate line under the stats bar. It shows the model's current rate while a schedule covers it, and clears when correction is off, no schedule applies, or pi records no cost for the model. It re-evaluates on model switch, on every turn, and when a message is finalized, so a window boundary crossed mid-session is picked up by the next turn.
+The footer status is a separate line under the stats bar. It shows the model's current rate while a schedule covers it, and clears when correction is off, no schedule applies, or pi records no cost for the model. It re-evaluates on model switch, on every turn, and when a message is finalized — and it arms a timer for the next instant the rate it quotes actually changes, so a session sitting idle across 04:00 UTC flips to the new rate on time instead of at its next turn.
 
 ## Configuration
 
@@ -94,15 +94,16 @@ Note that a coding plan is billed in credits against a subscription, so pi's cos
 
 OpenRouter publishes the same windows machine-readably for models it hosts (`pricing.overrides` with `utc_days` / `utc_start` / `utc_end` on `https://openrouter.ai/api/v1/models`), but this extension reads its schedule from config rather than the network: the correction is a rate difference, not a price lookup, and a fetch would add a failure mode to a handler that must never throw.
 
-A malformed field falls back to its default rather than disabling the extension; a malformed file warns once and resolves to defaults.
+A malformed field falls back to its default rather than disabling the extension; a malformed file warns and resolves to defaults.
 
 ## Design notes
 
 - **Only the selected model drives the indicator.** Schedules are provider- and model-scoped, so the footer never shows a rate for a service that does not bill by time of day. A rate above the recorded one reads `peak`, below it `off-peak`, and a discount is never labelled a peak. The quoted rate and the written cost come from the same multiplication, so they cannot disagree.
-- **Rate by request start.** DeepSeek bills by arrival time, so the multiplier is chosen from the `message_start` timestamp rather than `message_end`. A request spanning a window boundary would otherwise land on the wrong side.
+- **The footer follows the window it quotes.** pi has no render tick and fires no event while a session is idle, and a rate that changes at 04:00 would otherwise stay on screen until the next turn. The extension arms a single timer for the next instant the quoted rate changes and re-arms it after each fire, from the same clock reading as the status it is keeping fresh. It arms nothing when there is no status on screen, and the timer is unreferenced and cleared on session shutdown, so it neither holds pi open nor outlives its session.
+- **Rate by request start.** DeepSeek bills by arrival time, so the multiplier is chosen from the logical request start captured in `before_provider_request`, not `message_end`. `message_start` only fires once the response begins, so it would misprice a request that spans a window boundary.
 - **Scaled once.** Retries and overflow recovery can re-deliver the same message object, so adjustments are guarded by identity; the replacement returned to pi is registered too, so a replayed replacement cannot be scaled twice.
 - **Only cost moves.** The four cost fields are scaled and `total` is recomputed from them, matching pi's own invariant. Token counts are untouched, so rate-from-cost derivations stay self-consistent — including pi's cache-miss accounting, which derives its paid and read rates from the same message and scales with it.
-- **Coverage.** Assistant messages carry the bulk of a session's spend. Compaction and branch-summary usage, plus token usage reported by tools, also feed the footer but cannot be adjusted after the fact, so totals stay an estimate rather than an invoice.
+- **Coverage.** Assistant messages carry the bulk of a session's spend. Compaction and branch-summary usage, prompt-cache-warming refreshes, and token usage reported by tools also consume budget but cannot be adjusted after the fact, so totals stay an estimate rather than an invoice.
 
 ## Stack
 

package/extensions/index.ts

@@ -21,6 +21,10 @@
  * extension writes. A session on a provider or model no schedule covers never
  * shows a rate, and switching models re-evaluates it.
  *
+ * The indicator is a snapshot of the current hour, and pi fires no event while a
+ * session sits idle — so a timer armed at the next window boundary keeps it from
+ * quoting a rate that has already expired. See `arm`.
+ *
  * Schedules are provider-scoped and there can be several, because the shape of
  * the correction differs: DeepSeek's list price is its off-peak rate, so peak is
  * a surcharge (×2), while Z.ai's coding plan and Alibaba's night discount are
@@ -165,6 +169,14 @@ export const NEUTRAL_SCHEDULE: Schedule = {
 
 export const DEFAULT_ACTIVE = true;
 
+/**
+ * Only an explicit boolean is a toggle. A malformed `active` falls back like
+ * every other field, so a typo disables nothing silently.
+ */
+export function parseActive(value: unknown): boolean {
+	return typeof value === "boolean" ? value : DEFAULT_ACTIVE;
+}
+
 /** "HH:MM" in UTC to minutes from midnight, or undefined when unparseable. */
 export function parseClock(value: unknown): number | undefined {
 	if (typeof value !== "string") return undefined;
@@ -285,6 +297,60 @@ export function isPeakAt(startedAt: Date, schedule: Schedule): boolean {
 	return multiplierAt(startedAt, schedule) > 1;
 }
 
+const MS_PER_MINUTE = 60_000;
+
+/**
+ * Every instant the multiplier could move: the edges of each window, over a week
+ * of days plus a day of slack so a window that wraps midnight always contributes
+ * its closing edge and every weekday appears at least once. Sorted, and only
+ * ahead of `now`.
+ */
+function candidateEdges(now: Date, schedule: Schedule): number[] {
+	const nowMs = now.getTime();
+	const edges: number[] = [];
+
+	for (let offset = 0; offset <= 8; offset++) {
+		const midnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + offset);
+		const day = new Date(midnight).getUTCDay();
+		const previousDay = (day + 6) % 7;
+
+		for (const window of schedule.windows) {
+			// A window opens on its own day and closes on that day, or on the next one
+			// when it runs past midnight.
+			const closesOn = window.end > window.start ? day : previousDay;
+			if (schedule.days.includes(day)) edges.push(midnight + window.start * MS_PER_MINUTE);
+			if (schedule.days.includes(closesOn)) edges.push(midnight + window.end * MS_PER_MINUTE);
+		}
+	}
+
+	return edges.filter((edge) => edge > nowMs).sort((left, right) => left - right);
+}
+
+/**
+ * The earliest instant after `now` at which the schedule's multiplier changes,
+ * or undefined when it never does.
+ *
+ * A window edge is not enough: windows can overlap, so the edge that opens one
+ * may land inside another and leave the rate where it was. Testing the
+ * multiplier on both sides of each edge keeps the footer's trigger and the
+ * footer's value on the same function, and leaves a schedule whose multiplier
+ * never moves — a `multiplier` equal to its `outside`, say — with no timer at
+ * all.
+ */
+export function nextTransitionAt(now: Date, schedule: Schedule): Date | undefined {
+	if (schedule.windows.length === 0) return undefined;
+
+	// Edges are ordered, so the multiplier is constant between consecutive ones:
+	// the first edge that moves it is the first change after `now`.
+	for (const edge of candidateEdges(now, schedule)) {
+		if (multiplierAt(new Date(edge), schedule) !== multiplierAt(new Date(edge - 1), schedule)) {
+			return new Date(edge);
+		}
+	}
+
+	return undefined;
+}
+
 /** Glob match supporting `*` only, which is all a provider/model filter needs. */
 export function matchesPattern(pattern: string, value: string): boolean {
 	if (pattern === "*") return true;
@@ -483,18 +549,56 @@ export default function peakHours(pi: ExtensionAPI, options: PeakHoursOptions =
 	const configPath = options.configPath ?? CONFIG_PATH;
 	let config = readConfig(configPath) ?? {};
 	let schedules = resolveSchedules(config);
-	let active = config.active ?? DEFAULT_ACTIVE;
+	let active = parseActive(config.active);
 	const adjusted = adjustedMessages();
 	let pendingStart: number | undefined;
+	let requestStartMs: number | undefined;
+	let timer: ReturnType<typeof setTimeout> | undefined;
 
 	function refresh(): void {
 		config = readConfig(configPath) ?? {};
 		schedules = resolveSchedules(config);
-		active = config.active ?? DEFAULT_ACTIVE;
+		active = parseActive(config.active);
+	}
+
+	function disarm(): void {
+		if (timer === undefined) return;
+		clearTimeout(timer);
+		timer = undefined;
+	}
+
+	/**
+	 * Keep the footer in step with the window it quotes. pi fires no event while a
+	 * session sits idle, so a session idle across a boundary would keep describing
+	 * a rate that has expired. Armed only for a `status` that is on screen, and
+	 * from the instant that status was computed: `now` is the one clock reading
+	 * shared by the rate and the boundary that ends it, so the last millisecond of
+	 * a window cannot arm the timer past its own edge.
+	 */
+	function arm(ctx: ExtensionContext, model: ModelRate | undefined, status: string | undefined, now: Date): void {
+		disarm();
+		// Nothing to keep fresh, or no footer to keep fresh in.
+		if (status === undefined || !ctx.hasUI || !model) return;
+		const schedule = scheduleFor(schedules, model.provider, model.id);
+		if (!schedule) return;
+
+		const next = nextTransitionAt(now, schedule);
+		if (!next) return;
+		// Floored, so a boundary crossed between reading the clock and arming the
+		// timer cannot spin it; unreferenced, so a pending window never keeps pi
+		// alive after its work is done.
+		timer = setTimeout(() => {
+			timer = undefined;
+			updateStatus(ctx);
+		}, Math.max(1000, next.getTime() - now.getTime()));
+		timer.unref?.();
 	}
 
 	function updateStatus(ctx: ExtensionContext, model: ModelRate | undefined = ctx.model): void {
-		ctx.ui.setStatus(STATUS_KEY, statusIndicator(schedules, active, model));
+		const now = new Date();
+		const status = statusIndicator(schedules, active, model, now);
+		ctx.ui.setStatus(STATUS_KEY, status);
+		arm(ctx, model, status, now);
 	}
 
 	function notifyStatus(ctx: ExtensionContext, model: ModelRate | undefined = ctx.model): void {
@@ -532,6 +636,8 @@ export default function peakHours(pi: ExtensionAPI, options: PeakHoursOptions =
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		pendingStart = undefined;
+		requestStartMs = undefined;
+		disarm();
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 	});
 
@@ -545,8 +651,17 @@ export default function peakHours(pi: ExtensionAPI, options: PeakHoursOptions =
 		updateStatus(ctx);
 	});
 
+	// The provider bills when the request arrives, and `message_start` is emitted
+	// only once the response begins, so capture the logical request start here and
+	// fall back to the message clock when no request was observed.
+	pi.on("before_provider_request", async () => {
+		if (active) requestStartMs = Date.now();
+	});
+
 	pi.on("message_start", async (event) => {
-		if (event.message.role === "assistant") pendingStart = Date.now();
+		if (event.message.role !== "assistant") return;
+		pendingStart = requestStartMs ?? Date.now();
+		requestStartMs = undefined;
 	});
 
 	pi.on("message_end", async (event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nijaru/pi-peak-hours",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "Correct pi's recorded cost for providers that bill by time of day, with a peak multiplier in the footer status.",
   "keywords": [
@@ -34,8 +34,8 @@
     "check": "bun test && oxlint extensions/ tests/ && tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-ai": "0.87.0",
+    "@earendil-works/pi-coding-agent": "0.87.0",
     "@types/bun": "latest",
     "oxlint": "latest",
     "typescript": "^6.0.3"