@gavin-hu/my-pi-agent 0.0.0-stage → 0.7.0

package/extensions/bytefly/footer/price/schedule.ts

@@ -0,0 +1,112 @@
+/**
+ * Peak / off-peak evaluation for a priced record.
+ *
+ * A window is stated in a configured IANA zone, because the tariff a provider
+ * publishes is stated in its own local time. `isPeak` takes the formatter as an
+ * argument: building one is the expensive part, so a pricer builds it once and
+ * reuses it across a branch, keeping this module pure and cheap to call.
+ */
+
+import { asRecord } from "../../../../lib/config.ts";
+import type { PeakSchedule, PeakWindow } from "./types.ts";
+
+const TIME_OF_DAY = /^(\d{1,2}):(\d{2})$/;
+/** Every ISO weekday; the meaning of an omitted `days`. */
+const ALL_DAYS: readonly number[] = [1, 2, 3, 4, 5, 6, 7];
+
+/** The `en-US` short weekday names `peakFormatter` can produce. */
+const WEEKDAYS: Readonly<Record<string, number>> = {
+	Mon: 1,
+	Tue: 2,
+	Wed: 3,
+	Thu: 4,
+	Fri: 5,
+	Sat: 6,
+	Sun: 7,
+};
+
+/**
+ * Weekday numbers for a window.
+ *
+ * Omitted or empty means every day. A non-empty list is filtered to valid
+ * weekdays; a list yielding none means the window itself is malformed, so it is
+ * dropped rather than silently widened to the whole week.
+ */
+function parseDays(raw: unknown): readonly number[] | null {
+	if (raw === undefined) return ALL_DAYS;
+	if (!Array.isArray(raw)) return null;
+	if (raw.length === 0) return ALL_DAYS;
+	const days = new Set<number>();
+	for (const value of raw) {
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 7) continue;
+		days.add(value);
+	}
+	if (days.size === 0) return null;
+	return [...days].sort((a, b) => a - b);
+}
+
+/** Minutes since midnight for a `HH:MM` string, or `null`. */
+function parseTimeOfDay(raw: unknown): number | null {
+	if (typeof raw !== "string") return null;
+	const match = TIME_OF_DAY.exec(raw.trim());
+	if (!match) return null;
+	const hours = Number(match[1]);
+	const minutes = Number(match[2]);
+	if (hours > 23 || minutes > 59) return null;
+	return hours * 60 + minutes;
+}
+
+/**
+ * Parse one peak window; a malformed window is dropped rather than guessed.
+ *
+ * A `to` equal to `from` states no duration, so it is treated as malformed.
+ */
+export function parseWindow(raw: unknown): PeakWindow | null {
+	const value = asRecord(raw);
+	if (!value) return null;
+	const days = parseDays(value.days);
+	const from = parseTimeOfDay(value.from);
+	const to = parseTimeOfDay(value.to);
+	if (!days || from === null || to === null || from === to) return null;
+	return { days, from, to };
+}
+
+/** A formatter resolving the weekday and h23 time of day in `timezone`. */
+export function peakFormatter(timezone: string): Intl.DateTimeFormat {
+	return new Intl.DateTimeFormat("en-US", {
+		timeZone: timezone,
+		weekday: "short",
+		hour: "2-digit",
+		minute: "2-digit",
+		hourCycle: "h23",
+	});
+}
+
+/** Whether the local time of `at` falls inside a peak window. */
+export function isPeak(schedule: PeakSchedule, at: number, format: Intl.DateTimeFormat): boolean {
+	// No windows stated means the rate is flat, so every moment is peak.
+	if (schedule.windows.length === 0) return true;
+	const parts = format.formatToParts(at);
+	let weekday = 0;
+	let minutes = 0;
+	for (const part of parts) {
+		if (part.type === "weekday") weekday = WEEKDAYS[part.value] ?? 0;
+		else if (part.type === "hour") minutes = Number(part.value) * 60;
+		else if (part.type === "minute") minutes += Number(part.value);
+	}
+	return schedule.windows.some((window) => covers(window, weekday, minutes));
+}
+
+/**
+ * Whether a weekday and time of day fall inside a window.
+ *
+ * `from` is inclusive and `to` exclusive. A `to` before `from` wraps midnight,
+ * and the tail after midnight belongs to the day the window opened, so a
+ * Monday 22:00–02:00 window covers Tuesday 00:00–02:00 too.
+ */
+function covers(window: PeakWindow, weekday: number, minutes: number): boolean {
+	if (window.to > window.from) return window.days.includes(weekday) && minutes >= window.from && minutes < window.to;
+	if (minutes >= window.from) return window.days.includes(weekday);
+	const previous = weekday === 1 ? 7 : weekday - 1;
+	return window.days.includes(previous) && minutes < window.to;
+}

package/extensions/bytefly/footer/price/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Price-configuration types for the footer.
+ *
+ * These describe `bytefly.json` and the rate lookup only: currency, per-model
+ * rates, and the peak schedule. The footer's own data model lives in
+ * `../types.ts`.
+ */
+
+/** How a cost is rendered. */
+export interface Currency {
+	/** Printed before the number, e.g. `$` or `¥`. */
+	symbol: string;
+	/** Digits after the decimal point. */
+	decimals: number;
+}
+
+/** Per-million-token rates for one model, expressed in the configured currency. */
+export interface ModelRates {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	/** Multiplier applied outside every peak window; `1` means no discount. */
+	offPeakMultiplier: number;
+}
+
+/** One peak window in local time, as minutes since midnight. */
+export interface PeakWindow {
+	/** ISO weekday numbers, 1 = Monday .. 7 = Sunday. */
+	days: readonly number[];
+	/** Inclusive start, in minutes since local midnight. */
+	from: number;
+	/** Exclusive end; a value `<= from` wraps past midnight. */
+	to: number;
+}
+
+/** When a provider charges its peak rate. */
+export interface PeakSchedule {
+	/** IANA zone the windows are stated in. */
+	timezone: string;
+	/** No windows means every moment is peak, so a rate is flat. */
+	windows: readonly PeakWindow[];
+}
+
+/** Everything the price calculation is configured with. */
+export interface ByteflyConfig {
+	currency: Currency;
+	/** Fall back to Pi's recorded cost for a record that no rate matches. */
+	fallbackToRecordedCost: boolean;
+	/** Rates keyed by `provider/model`, matched through wildcards. */
+	rates: Readonly<Record<string, ModelRates>>;
+	peak: PeakSchedule;
+}

package/extensions/bytefly/footer/register.ts

@@ -0,0 +1,116 @@
+/**
+ * The footer surface: the two-line status bar, the `/bytefly` surface toggle,
+ * and the session lifecycle that installs and restores the footer.
+ *
+ * The footer is installed only in interactive (`tui`) sessions, and the price
+ * configuration is read once per install, so toggling the footer — or starting
+ * a new session — is how an edited `bytefly.json` is picked up. Nothing watches
+ * the file.
+ *
+ * `/bytefly` also drives the header surface, injected by the composition root
+ * so this folder never imports `header/`.
+ */
+
+import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createSnapshotReader } from "./collect/snapshot.ts";
+import { loadByteflyConfig } from "./price/config.ts";
+import { createFooter } from "./render/footer.ts";
+
+/** A bytefly surface the `/bytefly` command can enable or disable. */
+export interface ChromeSurface {
+	/** Install the surface, or restore Pi's built-in one, from the current state. */
+	apply(ctx: ExtensionContext): void;
+	/** Whether the surface is currently on. */
+	isEnabled(): boolean;
+	/** Set the enabled flag without installing. */
+	setEnabled(enabled: boolean): void;
+}
+
+/** Host seams for the footer surface. */
+export interface FooterDeps {
+	/** The header surface, toggled by `/bytefly header` and the master switch. */
+	header?: ChromeSurface;
+}
+
+/** Register `/bytefly [header|footer|status]` and the install/restore lifecycle. */
+export function registerFooter(pi: ExtensionAPI, deps: FooterDeps = {}): void {
+	let enabled = true;
+
+	const install = (ctx: ExtensionContext): void => {
+		if (ctx.mode !== "tui") return;
+		const config = loadByteflyConfig(ctx.cwd);
+		const read = createSnapshotReader(config);
+
+		if (enabled) {
+			ctx.ui.setFooter((tui, _theme, footerData) =>
+				createFooter(
+					tui,
+					footerData,
+					() => read(ctx, footerData),
+					() => ctx.ui.theme,
+					homedir(),
+				),
+			);
+		} else {
+			ctx.ui.setFooter(undefined);
+		}
+	};
+
+	const header = deps.header;
+	const headerState = (): string => (header?.isEnabled() ? "on" : "off");
+
+	pi.registerCommand("bytefly", {
+		description: "Toggle the TUI bytefly chrome: /bytefly [header|footer|status]",
+		getArgumentCompletions: (prefix: string) => {
+			const action = prefix.trim();
+			const options = ["footer", "header", "status"].filter((option) => option.startsWith(action));
+			return options.length > 0 ? options.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") return;
+			const sub = args.trim().toLowerCase();
+
+			if (sub === "status") {
+				ctx.ui.notify(`bytefly: header ${headerState()}, footer ${enabled ? "on" : "off"}`, "info");
+				return;
+			}
+			if (sub === "header") {
+				if (!header) {
+					ctx.ui.notify("bytefly: header surface is not available", "warning");
+					return;
+				}
+				header.setEnabled(!header.isEnabled());
+				header.apply(ctx);
+				ctx.ui.notify(`bytefly header ${headerState()}`, "info");
+				return;
+			}
+			if (sub === "footer") {
+				enabled = !enabled;
+				install(ctx);
+				ctx.ui.notify(`bytefly footer ${enabled ? "on" : "off"}`, "info");
+				return;
+			}
+			if (sub === "") {
+				// The master switch brings both surfaces to one state.
+				const next = !(enabled && (header?.isEnabled() ?? true));
+				enabled = next;
+				install(ctx);
+				if (header) {
+					header.setEnabled(next);
+					header.apply(ctx);
+				}
+				ctx.ui.notify(`bytefly ${next ? "on" : "off"}`, "info");
+				return;
+			}
+			ctx.ui.notify("usage: /bytefly [header|footer|status]", "warning");
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => install(ctx));
+	pi.on("session_tree", (_event, ctx) => install(ctx));
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		ctx.ui.setFooter(undefined);
+	});
+}

package/extensions/bytefly/footer/render/footer.ts

@@ -0,0 +1,51 @@
+/**
+ * The custom footer component installed with `ctx.ui.setFooter()`.
+ *
+ * The component reads a fresh snapshot on every render and resolves the theme
+ * through a getter, so a theme change or a settings change is picked up without
+ * rebuilding the component. `createFooter` also subscribes to git branch
+ * changes and returns the unsubscribe callback as `dispose`.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { renderLine } from "./layout.ts";
+import { buildLines } from "./lines.ts";
+import type { FooterData, StatusSnapshot, TuiLike } from "../types.ts";
+
+/** A two-line, width-adaptive status bar. */
+class StatusBar implements Component {
+	/** Unsubscribes the branch watcher; set by `createFooter`. */
+	dispose?: () => void;
+
+	constructor(
+		private readonly read: () => StatusSnapshot,
+		private readonly getTheme: () => Theme,
+		private readonly home: string | undefined,
+	) {}
+
+	invalidate(): void {
+		// The bar recomputes from a fresh snapshot each render, so there is
+		// nothing cached to clear. Theme-dependent strings are built in render.
+	}
+
+	render(width: number): string[] {
+		const snapshot = this.read();
+		const theme = this.getTheme();
+		const target = Math.max(1, width);
+		return buildLines(snapshot, theme, this.home).map((line) => renderLine(line, target, theme));
+	}
+}
+
+/** Factory passed to `ctx.ui.setFooter()`. */
+export function createFooter(
+	tui: TuiLike,
+	footerData: FooterData,
+	read: () => StatusSnapshot,
+	getTheme: () => Theme,
+	home: string | undefined,
+): Component & { dispose?(): void } {
+	const bar = new StatusBar(read, getTheme, home);
+	bar.dispose = footerData.onBranchChange(() => tui.requestRender());
+	return bar;
+}

package/extensions/bytefly/footer/render/format.ts

@@ -0,0 +1,106 @@
+/**
+ * Pure formatting helpers for the status bar.
+ *
+ * These never touch the terminal; they turn numbers and paths into the short
+ * strings the bar shows. Styling happens in `lines.ts`.
+ */
+
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences, truncateToWidth } from "@earendil-works/pi-tui";
+import { shortenPath } from "../../../../lib/format.ts";
+import { CONFIG } from "../config.ts";
+import { DEFAULT_CURRENCY } from "../price/config.ts";
+import type { Currency } from "../price/types.ts";
+
+/** Theme tokens for the reasoning-effort indicator. */
+export type ThinkingColor =
+	| "thinkingOff"
+	| "thinkingMinimal"
+	| "thinkingLow"
+	| "thinkingMedium"
+	| "thinkingHigh"
+	| "thinkingXhigh"
+	| "thinkingMax";
+
+/**
+ * A cost in the configured currency, at its configured precision.
+ *
+ * A positive amount below one minor unit never renders as zero — it shows
+ * `¥<0.01` — so a small cost is never reported as free.
+ */
+export function formatCost(cost: number, currency: Currency = DEFAULT_CURRENCY): string {
+	const { symbol, decimals } = currency;
+	if (!Number.isFinite(cost) || cost <= 0) return `${symbol}${(0).toFixed(decimals)}`;
+	const minimum = 10 ** -decimals;
+	if (cost < minimum) return `${symbol}<${minimum.toFixed(decimals)}`;
+	return `${symbol}${cost.toFixed(decimals)}`;
+}
+
+/** Rounded percentage, or `?` when the value is unknown. */
+export function formatPercent(percent: number | null): string {
+	return percent === null ? "?" : `${Math.round(percent)}%`;
+}
+
+/** The final path segment. */
+function basename(path: string): string {
+	const parts = path.split("/").filter(Boolean);
+	return parts.at(-1) ?? path;
+}
+
+/**
+ * Shorten a working directory.
+ * `0` = full (`~/repo/project`), `1` = `~/project`, `2` = `project`.
+ */
+export function formatCwd(cwd: string, home: string | undefined, level: 0 | 1 | 2): string {
+	// `shortenPath` normalizes separators and replaces the home prefix, so the
+	// level-1/2 logic below only splits an already-normalized path.
+	const shortened = shortenPath(cwd, home);
+	if (level === 0) return shortened;
+	const base = basename(shortened);
+	if (level === 2) return base;
+	if (shortened === "~") return "~";
+	if (shortened.startsWith("~/")) return `~/${base}`;
+	const parts = shortened.split("/").filter(Boolean);
+	return parts.length <= 2 ? shortened : `…/${parts.slice(-2).join("/")}`;
+}
+
+/** Filled/empty block counts for a percentage across `blocks` cells. */
+export function computeGauge(percent: number | null, blocks: number): { filled: number; empty: number } {
+	if (blocks <= 0) return { filled: 0, empty: 0 };
+	if (percent === null) return { filled: 0, empty: blocks };
+	const clamped = Math.max(0, Math.min(100, percent));
+	// Floor so the bar is only full at 100%; force one block for any non-zero
+	// usage so a small percentage is still visible.
+	const filled = Math.max(clamped > 0 ? 1 : 0, Math.floor((clamped / 100) * blocks));
+	return { filled, empty: blocks - filled };
+}
+
+/** Gauge color for a context percentage. Neutral until it crosses a threshold. */
+export function contextColor(percent: number | null): ThemeColor {
+	if (percent === null) return "muted";
+	if (percent > CONFIG.thresholds.danger) return "error";
+	if (percent > CONFIG.thresholds.warn) return "warning";
+	return "muted";
+}
+
+const THINKING_TOKENS: Record<ThinkingLevel, ThinkingColor> = {
+	off: "thinkingOff",
+	minimal: "thinkingMinimal",
+	low: "thinkingLow",
+	medium: "thinkingMedium",
+	high: "thinkingHigh",
+	xhigh: "thinkingXhigh",
+	max: "thinkingMax",
+};
+
+/** Truncate to `max` display columns, counting wide characters correctly. */
+export function truncateLabel(label: string, max: number): string {
+	return stripTerminalSequences(truncateToWidth(label, max, "…"));
+}
+
+/** Theme token for a reasoning-effort level. Mirrors Pi's own mapping; the
+ *  `thinkingOff` fallback only guards against an unknown runtime value. */
+export function thinkingColor(level: ThinkingLevel): ThinkingColor {
+	return THINKING_TOKENS[level] ?? "thinkingOff";
+}

package/extensions/bytefly/footer/render/layout.ts

@@ -0,0 +1,139 @@
+/**
+ * Width-aware rendering for one footer line.
+ *
+ * A line has a left and a right zone. On a wide terminal the right zone is
+ * right-aligned; when space runs out it folds next to the left zone, and then
+ * segments shrink and drop from the highest weight down. Terminal-width
+ * measurement uses `visibleWidth`, so ANSI styling and wide characters count
+ * correctly.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { CONFIG } from "../config.ts";
+import type { LineSpec, Segment } from "../types.ts";
+
+type Zone = "left" | "right";
+
+interface State {
+	segment: Segment;
+	zone: Zone;
+	form: number;
+	dropped: boolean;
+	/** Rendered before the segment; shrinks to a single space as a last resort. */
+	separator: string;
+	/** True once the separator has been collapsed to a single space. */
+	separatorCompact: boolean;
+	order: number;
+}
+
+function makeStates(spec: LineSpec): State[] {
+	const states: State[] = [];
+	let order = 0;
+	const push = (segment: Segment, zone: Zone): void => {
+		states.push({
+			segment,
+			zone,
+			form: 0,
+			dropped: false,
+			separator: segment.separator,
+			separatorCompact: false,
+			order: order++,
+		});
+	};
+	for (const segment of spec.left) push(segment, "left");
+	for (const segment of spec.right) push(segment, "right");
+	return states;
+}
+
+function composeZone(states: State[], zone: Zone): string {
+	let out = "";
+	let first = true;
+	for (const state of states) {
+		if (state.zone !== zone || state.dropped) continue;
+		const text = state.segment.forms[Math.min(state.form, state.segment.forms.length - 1)] ?? "";
+		if (!text) continue;
+		out += (first ? "" : state.separator) + text;
+		first = false;
+	}
+	return out;
+}
+
+function assemble(states: State[], width: number): string {
+	const left = composeZone(states, "left");
+	const right = composeZone(states, "right");
+	if (!right) return left;
+	if (!left) return " ".repeat(Math.max(0, width - visibleWidth(right))) + right;
+
+	const leftWidth = visibleWidth(left);
+	const rightWidth = visibleWidth(right);
+	if (leftWidth + CONFIG.minGap + rightWidth <= width) {
+		return left + " ".repeat(width - leftWidth - rightWidth) + right;
+	}
+	return `${left}${" ".repeat(CONFIG.minGap)}${right}`;
+}
+
+/** Advance the form of, or drop, the lowest-priority segment that can change. */
+function reduceOnce(states: State[]): boolean {
+	let best: State | null = null;
+	for (const state of states) {
+		if (state.dropped) continue;
+		const atFloor = state.form >= state.segment.forms.length - 1;
+		if (atFloor && !state.segment.droppable) continue;
+		if (
+			!best ||
+			state.segment.weight > best.segment.weight ||
+			(state.segment.weight === best.segment.weight && state.order > best.order)
+		) {
+			best = state;
+		}
+	}
+
+	if (!best) return false;
+	if (best.form < best.segment.forms.length - 1) best.form++;
+	else best.dropped = true;
+	return true;
+}
+
+/** Collapse the lowest-priority padded separator to a single space, as a last
+ *  resort. A single space is kept so adjacent segments never collide; the
+ *  first visible segment in each zone has no separator to collapse. */
+function collapseSeparator(states: State[]): boolean {
+	const firstLeft = states.find((state) => state.zone === "left" && !state.dropped);
+	const firstRight = states.find((state) => state.zone === "right" && !state.dropped);
+	let best: State | null = null;
+	for (const state of states) {
+		if (state.dropped || !state.separator || state.separatorCompact) continue;
+		if (state === firstLeft || state === firstRight) continue;
+		if (
+			!best ||
+			state.segment.weight > best.segment.weight ||
+			(state.segment.weight === best.segment.weight && state.order > best.order)
+		) {
+			best = state;
+		}
+	}
+	if (!best) return false;
+	best.separator = " ";
+	best.separatorCompact = true;
+	return true;
+}
+
+/** Render one line to a single string no wider than `width`. */
+export function renderLine(spec: LineSpec, width: number, theme: Theme): string {
+	const target = Math.max(1, width);
+	const states = makeStates(spec);
+
+	let guard = 0;
+	while (visibleWidth(assemble(states, target)) > target && guard++ < states.length * 8 + 16) {
+		if (!reduceOnce(states)) break;
+	}
+	// Only once every segment is at its floor do we shrink separators, so the
+	// truncation ellipsis never replaces a separator's content and adjacent
+	// segments always keep at least one column of padding between them.
+	while (visibleWidth(assemble(states, target)) > target) {
+		if (!collapseSeparator(states)) break;
+	}
+
+	return truncateToWidth(assemble(states, target), target, theme.fg("dim", "…"));
+}

package/extensions/bytefly/footer/render/lines.ts

@@ -0,0 +1,50 @@
+/**
+ * Turn a `StatusSnapshot` into the two footer lines.
+ *
+ * Line 1 — identity: left `pwd`, right `⎇ branch · ⑂ worktree · ◉ browse`.
+ * Line 2 — resources: left the plan/alert statuses then the context gauge and
+ * usage meters, right the model and thinking level.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	branchSegment,
+	cacheSegment,
+	contextSegment,
+	costSegment,
+	modelSegment,
+	modesSegment,
+	pwdSegment,
+	browseSegment,
+	sessionSegment,
+	thinkingSegment,
+	tokensSegment,
+	windowSegment,
+	worktreeSegment,
+} from "./segments.ts";
+import type { LineSpec, Segment, StatusSnapshot } from "../types.ts";
+
+function defined(segments: Array<Segment | null>): Segment[] {
+	return segments.filter((segment): segment is Segment => segment !== null);
+}
+
+/** Build the identity and resources lines for a snapshot. */
+export function buildLines(snapshot: StatusSnapshot, theme: Theme, home: string | undefined): LineSpec[] {
+	const line1: LineSpec = {
+		left: defined([pwdSegment(snapshot, theme, home), sessionSegment(snapshot, theme)]),
+		right: defined([branchSegment(snapshot, theme), worktreeSegment(snapshot, theme), browseSegment(snapshot, theme)]),
+	};
+
+	const line2Left = defined([
+		contextSegment(snapshot, theme),
+		windowSegment(snapshot, theme),
+		costSegment(snapshot, theme),
+		tokensSegment(snapshot, theme),
+		cacheSegment(snapshot, theme),
+		modesSegment(snapshot, theme),
+	]);
+
+	const line2Right = defined([modelSegment(snapshot, theme), thinkingSegment(snapshot, theme)]);
+
+	return [line1, { left: line2Left, right: line2Right }];
+}