@gavin-hu/my-pi-agent 0.19.0 → 0.20.0

package/extensions/bytefly/panel/format.ts

@@ -127,23 +127,24 @@ const SECTION_LABELS: Record<PanelSection, string> = {
 	settings: "Settings",
 };
 
+/** One section's name, as the tab row prints it. */
+export function sectionLabel(section: PanelSection): string {
+	return SECTION_LABELS[section];
+}
+
 /**
- * The section bar's segments, in screen order. The active section takes the
- * accent and the others recede, so the bar reads as a left-to-right switch.
+ * The header's attention line: the worst thing the screen knows, then how many
+ * changes a reload would apply. `all clear` is said out loud rather than left
+ * blank, so the header never reads as "nothing loaded".
  */
-export function sectionSegments(active: PanelSection): SummarySegment[] {
-	return SECTION_ORDER.map((section) => ({
-		text: SECTION_LABELS[section],
-		color: active === section ? "accent" : "faint",
-	}));
-}
-
-/** The Settings section's counts: the scope and how many rows it shows. */
-export function settingsSummarySegments(scope: PanelScope, count: number): SummarySegment[] {
-	return [
-		{ text: scope === "global" ? "Global" : "Project", color: "accent" },
-		{ text: `${count} settings`, color: "meta" },
-	];
+export function attentionSegments(counts: PanelCounts, dirty: boolean): SummarySegment[] {
+	const segments: SummarySegment[] = [];
+	if (counts.missing > 0) segments.push({ text: `${counts.missing} missing`, color: "bad" });
+	else if (counts.degraded > 0) segments.push({ text: `${counts.degraded} degraded`, color: "warn" });
+	else if (counts.off > 0) segments.push({ text: `${counts.off} off`, color: "faint" });
+	else segments.push({ text: "all clear", color: "ok" });
+	if (dirty) segments.push({ text: "unsaved changes", color: "warn" });
+	return segments;
 }
 
 /**

package/extensions/bytefly/panel/join.ts

@@ -31,6 +31,17 @@ export function extensionName(path: string): string {
 	return basename(dirname(path));
 }
 
+/**
+ * The name a resource is called by on screen: the directory for an entry file
+ * (`…/worktree/index.ts`, `…/pdf/SKILL.md`), and the file's own stem otherwise, so
+ * a flat `extensions/auto.ts` is `auto` rather than the directory every flat file
+ * shares.
+ */
+export function resourceName(path: string): string {
+	const stem = basename(path).replace(/\.(ts|js|mjs|cjs|md)$/u, "");
+	return stem === "index" || stem === "SKILL" ? basename(dirname(path)) : stem;
+}
+
 /** Row key for a report that has no resolved extension item. */
 function reportKey(name: string): string {
 	return `report:${name}`;
@@ -46,13 +57,24 @@ export interface PanelJoinOptions {
 	agentDir: string;
 	/** Narrow to one extension directory or report name, or `undefined` for the full list. */
 	filter?: string;
+	/** Keep only the rows this accepts; a group's count follows what survives. */
+	where?: (row: PanelRow) => boolean;
 	/** Which resource kind the list is, for labels and grouping. */
 	kind?: ResourceKind;
 }
 
+/**
+ * The rows one group list produces, group headings included. The screen measures
+ * a section's height from this rather than from a built model, so a section it is
+ * not showing costs no `SKILL.md` read.
+ */
+export function groupedEntryCount(items: readonly ResourceItem[], agentDir: string, kind: ResourceKind): number {
+	return buildEntries([...items], agentDir, kind).length;
+}
+
 /** Build the merged model for the current items and reports. */
 export function buildPanelModel(options: PanelJoinOptions): PanelModel {
-	const { items, reports, agentDir, filter, kind = "extensions" } = options;
+	const { items, reports, agentDir, filter, where, kind = "extensions" } = options;
 	const byName = new Map(reports.map((report) => [report.extension, report]));
 
 	// A directory name may claim a report only when exactly one unique resource
@@ -60,7 +82,7 @@ export function buildPanelModel(options: PanelJoinOptions): PanelModel {
 	// the report and it stays available to the trailing `Not resolved` group.
 	const pathsByName = new Map<string, Set<string>>();
 	for (const item of items) {
-		const name = extensionName(item.path);
+		const name = resourceName(item.path);
 		const paths = pathsByName.get(name) ?? new Set<string>();
 		paths.add(resourceKey(item));
 		pathsByName.set(name, paths);
@@ -83,12 +105,23 @@ export function buildPanelModel(options: PanelJoinOptions): PanelModel {
 		const report = unambiguous(name) ? byName.get(name) : undefined;
 		if (report) claimed.add(name);
 		if (filter !== undefined && name !== filter) continue;
-		rows.push({ key: resourceKey(item), item, report, label: entry.label, group: current?.key ?? "" });
+		// The row is named for the resource, not for its file: a name is only unique
+		// enough to be a name when one resource uses it, which is the same rule that
+		// lets a directory claim a report. Otherwise the picker's `folder/file.ts`
+		// stays, because two rows would otherwise read alike.
+		const label = unambiguous(name) ? resourceName(item.path) : entry.label;
+		const row: PanelRow = { key: resourceKey(item), item, report, label, group: current?.key ?? "" };
+		if (where !== undefined && !where(row)) continue;
+		rows.push(row);
 		if (current) current.count += 1;
 	}
 
 	const extras = reports.filter(
-		(report) => !claimed.has(report.extension) && (filter === undefined || report.extension === filter),
+		(report) =>
+			!claimed.has(report.extension) &&
+			(filter === undefined || report.extension === filter) &&
+			(where === undefined ||
+				where({ key: reportKey(report.extension), report, label: report.extension, group: REPORT_ONLY_GROUP })),
 	);
 	if (extras.length > 0) {
 		const group: PanelGroup = { key: REPORT_ONLY_GROUP, label: REPORT_ONLY_LABEL, count: extras.length };
@@ -111,14 +144,24 @@ export function buildSkillModel(options: {
 	items: readonly ResourceItem[];
 	index: ReadonlyMap<string, SkillInfo>;
 	agentDir: string;
+	where?: (row: PanelRow) => boolean;
 }): PanelModel {
-	const model = buildPanelModel({ items: options.items, reports: [], agentDir: options.agentDir, kind: "skills" });
-	return {
-		groups: model.groups,
-		rows: model.rows.map((row) => {
-			const skill = row.item ? options.index.get(row.item.path) : undefined;
-			if (skill === undefined) return row;
-			return { ...row, label: skill.name ?? row.label, skill };
-		}),
-	};
+	// The filter runs after the join: a skill's name and its `SKILL.md` facts are
+	// what a reader searches and what decides whether it needs attention.
+	const model = buildPanelModel({
+		items: options.items,
+		reports: [],
+		agentDir: options.agentDir,
+		kind: "skills",
+	});
+	const joined = model.rows.map((row) => {
+		const skill = row.item ? options.index.get(row.item.path) : undefined;
+		if (skill === undefined) return row;
+		return { ...row, label: skill.name ?? row.label, skill };
+	});
+	const rows = options.where === undefined ? joined : joined.filter(options.where);
+	const groups = model.groups
+		.map((group) => ({ ...group, count: rows.filter((row) => row.group === group.key).length }))
+		.filter((group) => group.count > 0);
+	return { groups, rows };
 }

package/extensions/bytefly/panel/prices.ts

@@ -0,0 +1,43 @@
+/**
+ * The `/bytefly prices` report: which models this session could not price.
+ *
+ * A record nothing priced contributes no cost, so the footer's total is smaller than
+ * the work done and the reason is a *model*, not a record count. This is the answer to
+ * the question the footer can only hint at: the keys, in the `price.rates` vocabulary,
+ * and the one line saying what to do with them.
+ *
+ * Nothing here quotes a price: a rate is the user's to state, and inventing one is the
+ * rate table this command exists instead of.
+ */
+
+import { sanitizeLine } from "../../../lib/format.ts";
+import type { PricedUsage } from "../footer/types.ts";
+import { formatCost } from "../footer/render/format.ts";
+import { recordsText } from "../footer/unpriced.ts";
+import type { Currency } from "../footer/price/types.ts";
+
+/** How many keys the report prints before it counts the rest. */
+export const REPORTED_MODELS = 8;
+
+/**
+ * The report as the lines a reader gets.
+ *
+ * The headline says what the total is and how much of the session it leaves out; one
+ * line per key says what to add; the last line says where to add it. Pure: the caller
+ * has already priced the session.
+ */
+export function pricesReport(priced: PricedUsage, currency: Currency): string[] {
+	const models = priced.unpricedModels;
+	if (models.length === 0) return ["bytefly: every record in this session has a rate — nothing to add."];
+	const count = models.reduce((total, model) => total + model.records, 0);
+	const headline =
+		`bytefly: ${formatCost(priced.cost, currency)} priced · ` +
+		`${recordsText(count)} in ${models.length === 1 ? "1 model" : `${models.length} models`} ${count === 1 ? "has" : "have"} no rate`;
+	const keys = models
+		.slice(0, REPORTED_MODELS)
+		.map((model) => `  ${sanitizeLine(model.key)} · ${recordsText(model.records)}`);
+	const rest = models.length - keys.length;
+	if (rest > 0) keys.push(`  +${rest} more`);
+	keys.push('  add these under "price.rates" in bytefly.json — a key may be `*`, or a prefix like `gpt-*`.');
+	return [headline, ...keys];
+}

package/extensions/bytefly/panel/settings.ts

@@ -9,7 +9,7 @@
  * The catalogue is the shortlist a session changes, not the whole document: every
  * row is one a workflow differs on, and each states its own rule so a value the
  * screen accepts is a value the loader keeps. The catalogue order is the screen's
- * order, and it is capped so the section fits a 24-row terminal (`panel.test.ts`
+ * order, and it is capped so the section fits a 24-row terminal (`settings.test.ts`
  * holds the ceiling); a new row has to displace one. Everything else stays
  * `bytefly.json` — a list (`doctor.skip`), a table (`price.rates`), a schedule
  * (`price.peak`), and the tuning numbers and labels this screen deliberately does
@@ -28,9 +28,11 @@ import { configSection, configValueAt } from "../../../lib/config.ts";
 import { DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG, normalizeConfig as normalizeDoctorConfig } from "../doctor/config.ts";
 import {
 	CURRENCY_DEFAULTS,
+	CURRENCY_SYMBOLS,
 	DEFAULT_BYTEFLY_CONFIG,
 	DEFAULT_CURRENCY,
 	MAX_BUDGET,
+	MAX_DECIMALS,
 	normalizeByteflyConfig,
 } from "../footer/price/config.ts";
 import type { CurrencyCode } from "../footer/price/types.ts";
@@ -46,6 +48,13 @@ type SettingKind = "boolean" | "enum" | "text";
 /** Where the effective value came from. */
 type SettingOrigin = "default" | "global" | "project" | "inherited";
 
+/**
+ * The heading a row sits under. The screen draws one heading per group, so twelve
+ * rows read as four short lists: what a session starts with, what it tells you
+ * about, what it keeps, and what it costs.
+ */
+export type SettingGroup = "Startup" | "Notifications" | "Session" | "Price";
+
 /** One curated value a row can take. */
 interface SettingOption {
 	value: string;
@@ -80,6 +89,8 @@ interface SettingLeaf {
 export interface SettingDescriptor {
 	/** Stable identity, also the focus key. */
 	id: string;
+	/** The heading this row is listed under. */
+	group: SettingGroup;
 	label: string;
 	description: string;
 	source: SettingSource;
@@ -152,8 +163,10 @@ function amountRule(min: number, max: number): TextRule {
 export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	{
 		id: "byteflyUi",
-		label: "Bytefly startup TUI",
-		description: "Use bytefly's startup header in place of Pi's startup TUI.",
+		group: "Startup",
+		label: "Startup screen",
+		description:
+			"Show bytefly's header in place of Pi's own, so a session opens on the versions, the help keys, and the update marker.",
 		source: "app",
 		kind: "boolean",
 		fallback: "false",
@@ -162,9 +175,10 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "theme",
+		group: "Startup",
 		label: "Theme",
 		description:
-			"Pi's color theme, chosen from the palettes this package ships; `system` follows the terminal's colors. Takes effect after reload.",
+			"The palette every bytefly surface is drawn with; `system` follows Pi's own colors. Takes effect after reload.",
 		source: "app",
 		kind: "enum",
 		fallback: "system",
@@ -173,8 +187,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.enabled",
+		group: "Notifications",
 		label: "Desktop notifications",
-		description: "Raise an OS notification when a run or job finishes, or the agent asks for input.",
+		description: "The master switch for OS notifications; with it off, none of the four below is raised.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "false",
@@ -184,8 +199,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.turnFinished",
-		label: "Turn finished",
-		description: "Announce it when a full agent run settles.",
+		group: "Notifications",
+		label: "When a turn ends",
+		description: "Raise a notification once the agent has finished a reply.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -195,8 +211,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.needsInput",
-		label: "Needs input",
-		description: "Announce it when the agent opens a prompt and waits for an answer.",
+		group: "Notifications",
+		label: "When the agent needs you",
+		description: "Raise a notification when a question or a permission prompt is waiting.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -206,8 +223,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.jobFinished",
-		label: "Job finished",
-		description: "Announce it when a background job or watcher settles.",
+		group: "Notifications",
+		label: "When a job ends",
+		description: "Raise a notification when a background job or a watcher settles.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -217,8 +235,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "notify.matchFound",
-		label: "Watcher matched",
-		description: "Announce it when a `watch` whose `wake` is on matches, once the agent is idle.",
+		group: "Notifications",
+		label: "When a watcher matches",
+		description: "Raise a notification when a watched pattern appears, once the agent is idle.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -228,8 +247,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "job.wakeOnFinish",
-		label: "Wake when a job finishes",
-		description: "Start one agent turn when any background job finishes.",
+		group: "Session",
+		label: "Resume after a job",
+		description: "Wake the agent once a background job finishes, so it can read the output.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "false",
@@ -239,8 +259,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "rewind.autoSnapshots",
-		label: "Automatic snapshots",
-		description: "Take one rewind snapshot per prompt, before the first mutating tool call.",
+		group: "Session",
+		label: "Snapshot before a turn",
+		description: "Keep one rewind point per prompt, so `/rewind` can take you back.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -250,8 +271,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "doctor.proactive",
-		label: "Proactive health check",
-		description: "Probe enabled extensions at session start and warn about a missing requirement.",
+		group: "Session",
+		label: "Health check at startup",
+		description: "Probe what the extensions need before the first turn and say what is missing.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -261,9 +283,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "price.currency.code",
+		group: "Price",
 		label: "Currency",
-		description:
-			"CNY prices DeepSeek from its yuan rates; USD from its published dollars, falling back to Pi's recorded cost.",
+		description: "The currency the footer prices a session in, at that currency's published rates.",
 		source: "bytefly",
 		kind: "enum",
 		fallback: DEFAULT_CURRENCY.code,
@@ -283,8 +305,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 	{
 		id: "price.budget",
+		group: "Price",
 		label: "Session budget",
-		description: "Warn once when the session's cost reaches this amount; 0 is off. It never stops a turn.",
+		description: "Where the footer's `spent/limit` warns: one notice and one notification at the limit; 0 is off.",
 		source: "bytefly",
 		kind: "text",
 		fallback: "0",
@@ -329,6 +352,31 @@ function themeOptions(themes: readonly string[]): readonly SettingOption[] {
 	return names.map((name) => ({ value: name, label: name }));
 }
 
+/** The currency and precision a session prices in, through the price reader. */
+function currencyOf(snapshot: SettingsSnapshot, scope: WriteScope): { code: CurrencyCode; decimals: number } {
+	const reader = SECTION_READERS.price;
+	const globalRaw = configSection(snapshot.global, "price");
+	const projectRaw = scope === "project" ? configSection(snapshot.project, "price") : undefined;
+	const code = reader?.(globalRaw, projectRaw, ["currency", "code"]);
+	const decimals = reader?.(globalRaw, projectRaw, ["currency", "decimals"]);
+	return {
+		code: typeof code === "string" && code in CURRENCY_SYMBOLS ? (code as CurrencyCode) : DEFAULT_CURRENCY.code,
+		decimals: typeof decimals === "number" ? Math.min(decimals, MAX_DECIMALS) : DEFAULT_CURRENCY.decimals,
+	};
+}
+
+/**
+ * The budget's display value: `Off` for zero, otherwise the amount in the currency
+ * the session prices in. A reader thinks in `¥5`, not in `5`, and in `Off` rather
+ * than in `0`.
+ */
+function budgetLabel(raw: string, snapshot: SettingsSnapshot, scope: WriteScope): string {
+	const amount = Number(raw);
+	if (!Number.isFinite(amount) || amount <= 0) return "Off";
+	const { code, decimals } = currencyOf(snapshot, scope);
+	return `${CURRENCY_SYMBOLS[code]}${amount.toFixed(decimals)}`;
+}
+
 /** The display label for `raw`, or the raw value when it is a valid custom one. */
 function labelFor(row: SettingDescriptor, raw: string): string {
 	const option = row.options.find((entry) => entry.value === raw);
@@ -428,7 +476,8 @@ export function settingViews(snapshot: SettingsSnapshot, scope: WriteScope): Set
 		const options = row.id === "theme" ? themeOptions(snapshot.themes) : row.options;
 		const { value, origin } = row.source === "app" ? appValue(snapshot, row) : byteflyValue(snapshot, row, scope);
 		const view = { ...row, options, value };
-		return { ...view, valueLabel: labelFor(view, value), origin };
+		const valueLabel = row.id === "price.budget" ? budgetLabel(value, snapshot, scope) : labelFor(view, value);
+		return { ...view, valueLabel, origin };
 	});
 }
 

package/extensions/bytefly/panel/tui/entries.ts

@@ -1,10 +1,12 @@
 /**
- * The panel's entry model: one flat list of selectable rows per section.
+ * The panel's entry model: one flat list of display entries per section, made of
+ * group headings interleaved with the selectable rows under them.
  *
- * Extensions interleaves group headings with rows — a source group says where a
- * resource came from, which the row cannot — while Settings is flat, in catalogue
- * order. Both are built from a model or a set of views, so the component only has
- * to keep one cursor per section.
+ * Every section groups. A resource list groups by source — where an extension came
+ * from is something its row cannot say — and Settings groups by what the
+ * preference does, so twelve rows read as four short lists instead of one long
+ * one. Both are built from a model or a set of views, so the component only has to
+ * keep one cursor per section.
  *
  * Pure: the list is rebuilt from a model or a set of views, and navigation is
  * index arithmetic.
@@ -76,9 +78,25 @@ export function entriesOf(model: PanelModel): PanelEntry[] {
 }
 
 /**
- * The Settings entries: one row per view, in catalogue order, with no group
- * headings — the list is short enough to read whole.
+ * The Settings entries: one heading per group, in catalogue order, then its rows.
+ * The group key names the heading so a filter cannot collide a setting id with it.
  */
 export function settingEntries(views: readonly SettingView[]): PanelEntry[] {
-	return views.map((setting) => ({ kind: "setting", setting }));
+	const entries: PanelEntry[] = [];
+	for (const [group, settings] of groupSettings(views)) {
+		entries.push({ kind: "group", key: `setting:${group}`, label: group, count: settings.length });
+		for (const setting of settings) entries.push({ kind: "setting", setting });
+	}
+	return entries;
+}
+
+/** The views by their group, in catalogue order of first appearance. */
+function groupSettings(views: readonly SettingView[]): Map<string, SettingView[]> {
+	const groups = new Map<string, SettingView[]>();
+	for (const view of views) {
+		const list = groups.get(view.group) ?? [];
+		list.push(view);
+		groups.set(view.group, list);
+	}
+	return groups;
 }