@herbertgao/pi-extensions 2026.8.3 → 2026.8.4

package/node_modules/pi-footer/src/widgets/tokens/output-tokens.ts

@@ -0,0 +1,18 @@
+import { defineWidget } from "../types.js";
+import { formatTokenCount, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const OutputTokensWidget = defineWidget({
+  type: "output-tokens",
+  label: "Output Tokens",
+  category: "Tokens",
+  description: "Output token total",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "hideWhenZero", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "⬇️", nerd: "󰧚", text: "out" },
+  defaultStyle: { fg: "white", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(formatTokenCount(ctx.metrics.outputTokens, options.tokenFormatStyle));
+  },
+});

package/node_modules/pi-footer/src/widgets/tokens/tokens.ts

@@ -0,0 +1,20 @@
+import { defineWidget } from "../types.js";
+import { formatTokenCount, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const TokensWidget = defineWidget({
+  type: "tokens",
+  label: "Input/Output Tokens",
+  category: "Tokens",
+  description: "Input and output token totals",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "🔢", nerd: "󰓹", text: "tok" },
+  defaultStyle: { fg: "cyan", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(
+      `↑${formatTokenCount(ctx.metrics.inputTokens, options.tokenFormatStyle)} ↓${formatTokenCount(ctx.metrics.outputTokens, options.tokenFormatStyle)}`,
+    );
+  },
+});

package/node_modules/pi-footer/src/widgets/tokens/total-speed.ts

@@ -0,0 +1,25 @@
+import { defineWidget } from "../types.js";
+import { formatTokenSpeed, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const TotalSpeedWidget = defineWidget({
+  type: "total-speed",
+  label: "Total Speed",
+  category: "Tokens",
+  description: "Average total tokens per minute",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "hideWhenZero", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "⚡", nerd: "↕", text: "tok/min" },
+  defaultStyle: { fg: "brightGreen", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(
+      formatTokenSpeed(
+        ctx.metrics.totalTokens,
+        ctx.metrics.firstTimestampMs,
+        ctx.metrics.lastTimestampMs,
+        options.tokenFormatStyle,
+      ),
+    );
+  },
+});

package/node_modules/pi-footer/src/widgets/tokens/total-tokens.ts

@@ -0,0 +1,18 @@
+import { defineWidget } from "../types.js";
+import { formatTokenCount, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const TotalTokensWidget = defineWidget({
+  type: "total-tokens",
+  label: "Total Tokens",
+  category: "Tokens",
+  description: "Total token count",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "hideWhenZero", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "🔢", nerd: "󰓹", text: "tok" },
+  defaultStyle: { fg: "cyan", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(formatTokenCount(ctx.metrics.totalTokens, options.tokenFormatStyle));
+  },
+});

package/node_modules/pi-footer/src/widgets/types.ts

@@ -0,0 +1,181 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { ColorLevel } from "../colors.js";
+import type { GetExtensionStatuses } from "../extension-statuses.js";
+import type {
+  IconMode,
+  StatuslineData,
+  WidgetEntry,
+  WidgetOptions,
+  WidgetStyle,
+} from "../types.js";
+
+export interface WidgetIconSet {
+  emoji: string;
+  nerd: string;
+  text: string;
+}
+
+export type PropertyKind = "boolean" | "number" | "choice" | "text";
+
+export interface ChoiceOption<TId extends string = string> {
+  id: TId;
+  label: string;
+  list: string;
+}
+
+export type WidgetPropertyDefault = string | number | boolean;
+
+// Edit-action discriminant for properties that open a dedicated editor flow. Extend as needed.
+export type WidgetEditAction = "external-status-key";
+
+export interface WidgetProperty {
+  id: string;
+  label: string;
+  kind: PropertyKind;
+  description: string;
+  default: WidgetPropertyDefault;
+  showWhen?: {
+    property: string;
+    equals: string | number | boolean;
+  };
+  options?: {
+    min?: number;
+    max?: number;
+    choices?: readonly ChoiceOption[];
+    label?: string;
+    showInFields?: boolean;
+    showInWidgets?: boolean;
+    showInColors?: boolean;
+    listProperty?: string;
+    quoteValue?: boolean;
+    editAction?: WidgetEditAction;
+  };
+}
+
+export type WidgetBaseOption = "raw" | "hideWhenEmpty" | "hideWhenZero" | "text" | "icon";
+
+export interface WidgetRenderOptions extends WidgetStyle {
+  icons?: WidgetIconSet;
+  preservedTrimStyles?: string;
+  stripIncomingStyles?: boolean;
+}
+
+// The widget dependency set is the materialized snapshot (StatuslineData) plus the one live
+// accessor that must never enter the snapshot — see F1 / pi live-accessor rule.
+export type WidgetDependencyValues = StatuslineData & {
+  getExtensionStatuses: GetExtensionStatuses | undefined;
+};
+
+export type WidgetDependency = keyof WidgetDependencyValues;
+
+export interface BaseWidgetContext {
+  iconMode: IconMode;
+  minimalist: boolean;
+  colorLevel: ColorLevel;
+  theme?: Theme;
+  requestRender?: () => void;
+}
+
+export type WidgetContext<TDeps extends readonly WidgetDependency[] = readonly []> =
+  BaseWidgetContext & Pick<WidgetDependencyValues, TDeps[number]>;
+
+export type WidgetInstanceOptions<TOptions extends object> = WidgetOptions & TOptions;
+
+export interface Widget<TOptions extends object = {}> {
+  readonly entry: WidgetEntry;
+  readonly id: string;
+  readonly type: WidgetEntry["type"];
+  enabled: boolean;
+  options: WidgetInstanceOptions<TOptions>;
+
+  render(ctx: WidgetContext): string | undefined;
+  toggle(enabled?: boolean): void;
+  update(options: Partial<WidgetInstanceOptions<TOptions>>): void;
+  toEntry(): WidgetEntry;
+}
+
+type BaseOptionsToObject<TBaseOptions extends readonly WidgetBaseOption[]> = Required<
+  Pick<WidgetOptions, TBaseOptions[number]>
+>;
+
+type WidgetChoiceValue<TProperty> = TProperty extends {
+  readonly kind: "choice";
+  readonly options: { readonly choices: readonly (infer TChoice)[] };
+}
+  ? TChoice extends { readonly id: infer TId extends string }
+    ? TId
+    : string
+  : string;
+
+type WidgetPropertyValue<TProperty extends Pick<WidgetProperty, "kind">> =
+  TProperty["kind"] extends "boolean"
+    ? boolean
+    : TProperty["kind"] extends "number"
+      ? number
+      : TProperty["kind"] extends "choice"
+        ? WidgetChoiceValue<TProperty>
+        : string;
+
+type PropertiesToObject<TProperties extends readonly WidgetProperty[]> = {
+  [TProperty in TProperties[number] as TProperty["id"]]: WidgetPropertyValue<TProperty>;
+};
+
+export type OptionsFor<TSpec extends Pick<WidgetSpec, "baseOptions" | "properties">> =
+  WidgetOptions &
+    BaseOptionsToObject<TSpec["baseOptions"]> &
+    PropertiesToObject<TSpec["properties"]> &
+    WidgetStyle;
+
+export type ContextFor<TSpec extends Pick<WidgetSpec, "dependencies">> = BaseWidgetContext &
+  Pick<WidgetDependencyValues, TSpec["dependencies"][number]>;
+
+export interface TypedWidgetRenderArgs<
+  TSpec extends Pick<WidgetSpec, "dependencies" | "baseOptions" | "properties">,
+> {
+  readonly ctx: ContextFor<TSpec>;
+  readonly options: OptionsFor<TSpec>;
+  readonly renderWidget: (
+    value: string | undefined,
+    renderOptions?: WidgetRenderOptions,
+  ) => string | undefined;
+}
+
+export interface WidgetSpec<
+  TType extends string = string,
+  TCategory extends string = string,
+  TDependencies extends readonly WidgetDependency[] = readonly WidgetDependency[],
+  TBaseOptions extends readonly WidgetBaseOption[] = readonly WidgetBaseOption[],
+  TProperties extends readonly WidgetProperty[] = readonly WidgetProperty[],
+> {
+  readonly type: TType;
+  readonly label: string;
+  readonly category: TCategory;
+  readonly description: string;
+  readonly dependencies: TDependencies;
+  readonly baseOptions: TBaseOptions;
+  readonly baseOptionDefaults?: Partial<WidgetOptions>;
+  readonly properties: TProperties;
+  readonly icons: WidgetIconSet;
+  readonly defaultStyle: WidgetStyle;
+  readonly createOptionDefaults?: () => Partial<WidgetOptions>;
+  render(
+    args: TypedWidgetRenderArgs<{
+      readonly dependencies: TDependencies;
+      readonly baseOptions: TBaseOptions;
+      readonly properties: TProperties;
+    }>,
+  ): string | undefined;
+}
+
+export function defineWidget<
+  const TType extends string,
+  const TCategory extends string,
+  const TDependencies extends readonly WidgetDependency[],
+  const TBaseOptions extends readonly WidgetBaseOption[],
+  const TProperties extends readonly WidgetProperty[],
+>(
+  spec: WidgetSpec<TType, TCategory, TDependencies, TBaseOptions, TProperties>,
+): WidgetSpec<TType, TCategory, TDependencies, TBaseOptions, TProperties> {
+  return spec;
+}

package/node_modules/pi-footer/src/widgets/utils/colors.ts

@@ -0,0 +1,11 @@
+import type { ColorName } from "../../colors.js";
+
+export function colorPair(
+  fg: ColorName | undefined,
+  bg: ColorName | undefined,
+): { fg?: ColorName; bg?: ColorName } {
+  return {
+    ...(fg === undefined ? {} : { fg }),
+    ...(bg === undefined ? {} : { bg }),
+  };
+}

package/node_modules/pi-footer/src/widgets/utils/context.ts

@@ -0,0 +1,112 @@
+import { normalizeColor, type ConditionalColorFields } from "../../colors.js";
+import type { WidgetOptions } from "../../types.js";
+import { colorPair } from "./colors.js";
+
+export function contextPercent(tokens: number | undefined, maxTokens: number | undefined) {
+  if (tokens === undefined || maxTokens === undefined || maxTokens <= 0) return undefined;
+  return Math.min(100, Math.max(0, (tokens / maxTokens) * 100));
+}
+
+interface ContextColorOptions extends WidgetOptions, ConditionalColorFields {
+  contextConditionalColors: boolean;
+  contextWarningPercent: number;
+  contextDangerPercent: number;
+}
+
+export function contextColors(
+  options: ContextColorOptions,
+  contextTokens: number | undefined,
+  contextMaxTokens: number | undefined,
+) {
+  if (!options.contextConditionalColors) return colorPair(options.fg, options.bg);
+  const percent = contextPercent(contextTokens, contextMaxTokens);
+  if (percent === undefined) return colorPair(options.fg, options.bg);
+
+  if (percent >= options.contextDangerPercent) {
+    return colorPair(
+      normalizeColor(options.dangerFg) ?? options.fg,
+      normalizeColor(options.dangerBg) ?? options.bg,
+    );
+  }
+
+  if (percent >= options.contextWarningPercent) {
+    return colorPair(
+      normalizeColor(options.warningFg) ?? options.fg,
+      normalizeColor(options.warningBg) ?? options.bg,
+    );
+  }
+
+  return colorPair(options.fg, options.bg);
+}
+
+export function contextColorProperties() {
+  return [
+    {
+      id: "contextConditionalColors",
+      label: "Conditional colors",
+      kind: "boolean",
+      description: "Use warning/danger colors based on context usage",
+      default: false,
+      options: {
+        label: "with-colors",
+        showInWidgets: true,
+        showInColors: true,
+        listProperty: "",
+      },
+    },
+    {
+      id: "contextWarningPercent",
+      label: "Warning zone threshold",
+      kind: "number",
+      description: "Context usage percentage for warning colors",
+      default: 70,
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { min: 0, max: 100, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "contextDangerPercent",
+      label: "Danger zone threshold",
+      kind: "number",
+      description: "Context usage percentage for danger colors",
+      default: 90,
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { min: 0, max: 100, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "warningFg",
+      label: "Warning foreground",
+      kind: "text",
+      description: "Warning foreground",
+      default: "yellow",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "warningBg",
+      label: "Warning background",
+      kind: "text",
+      description: "Warning background",
+      default: "default",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "dangerFg",
+      label: "Danger foreground",
+      kind: "text",
+      description: "Danger foreground",
+      default: "red",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "dangerBg",
+      label: "Danger background",
+      kind: "text",
+      description: "Danger background",
+      default: "default",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+  ] as const;
+}

package/node_modules/pi-footer/src/widgets/utils/session.ts

@@ -0,0 +1,19 @@
+export function formatTime(timestamp: number | undefined): string {
+  if (timestamp === undefined) return "";
+  return new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}
+
+function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "0m";
+  const totalMinutes = Math.max(1, Math.floor(ms / 60_000));
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours === 0) return `${minutes}m`;
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+}
+
+export function formatElapsed(first: number | undefined, last: number | undefined): string {
+  if (first === undefined) return "0m";
+  const end = last === undefined || last < first ? Date.now() : last;
+  return formatDuration(end - first);
+}

package/node_modules/pi-footer/src/widgets/utils/token-format.ts

@@ -0,0 +1,78 @@
+export function formatCount(value: number) {
+  if (value < 1000) return `${value}`;
+  if (value < 1000000) return `${trimFixed(value / 1000, 1)}k`;
+  return `${trimFixed(value / 1000000, 1)}m`;
+}
+
+export function formatPiTokenCount(value: number) {
+  if (value < 1000) return `${value}`;
+  if (value < 10000) return `${(value / 1000).toFixed(1)}k`;
+  if (value < 1000000) return `${Math.round(value / 1000)}k`;
+  if (value < 10000000) return `${(value / 1000000).toFixed(1)}M`;
+  return `${Math.round(value / 1000000)}M`;
+}
+
+function trimFixed(value: number, digits: number) {
+  return value.toFixed(digits).replace(/\.0$/, "");
+}
+const TOKEN_FORMAT_STYLES = {
+  default: {
+    label: "Default",
+    list: "Default",
+    format: formatCount,
+  },
+  compact: {
+    label: "Compact",
+    list: "Compact",
+    format: formatPiTokenCount,
+  },
+} as const;
+
+export type TokenFormatStyle = keyof typeof TOKEN_FORMAT_STYLES;
+
+const TOKEN_FORMAT_STYLE_VALUES = Object.keys(TOKEN_FORMAT_STYLES) as TokenFormatStyle[];
+
+const TOKEN_FORMAT_CHOICES = TOKEN_FORMAT_STYLE_VALUES.map((style) => ({
+  id: style,
+  label: TOKEN_FORMAT_STYLES[style].label,
+  list: TOKEN_FORMAT_STYLES[style].list,
+}));
+
+export function formatTokenCount(value: number, style: TokenFormatStyle) {
+  return TOKEN_FORMAT_STYLES[style].format(value);
+}
+
+export function formatTokenSpeed(
+  tokens: number,
+  first: number | undefined,
+  last: number | undefined,
+  tokenFormatStyle: TokenFormatStyle,
+) {
+  if (
+    first === undefined ||
+    last === undefined ||
+    !Number.isFinite(first) ||
+    !Number.isFinite(last) ||
+    last <= first
+  ) {
+    return "0/min";
+  }
+  const minutes = Math.max((last - first) / 60000, 1 / 60);
+  return `${formatTokenCount(Math.round(tokens / minutes), tokenFormatStyle)}/min`;
+}
+
+export function tokenFormatStyleProperty() {
+  return {
+    id: "tokenFormatStyle",
+    label: "Token format",
+    kind: "choice",
+    description: "Token display format",
+    default: "default",
+    options: {
+      choices: TOKEN_FORMAT_CHOICES,
+      showInWidgets: true,
+      showInColors: false,
+      listProperty: "format",
+    },
+  } as const;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-extensions",
-  "version": "2026.8.3",
+  "version": "2026.8.4",
   "description": "Aggregate installer for HerbertGao-maintained Pi extensions.",
   "keywords": [
     "extensions",
@@ -20,6 +20,7 @@
     "directory": "packages/pi-extensions"
   },
   "files": [
+    "examples/pi-footer.json",
     "README.md",
     "LICENSE"
   ],
@@ -68,6 +69,7 @@
     "@sinclair/typebox": "^0.34.49",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "chalk": "^6.0.0",
     "croner": "^10.0.1",
     "cross-spawn": "^7.0.6",
     "effect": "4.0.0-beta.103",
@@ -79,6 +81,7 @@
     "nanoid": "^5.0.0",
     "open": "^10.2.0",
     "p-limit": "^6.1.0",
+    "pi-footer": "0.5.1",
     "pi-lens": "3.8.74",
     "pi-mcp-adapter": "2.23.0",
     "pi-web-access": "0.22.0",
@@ -117,6 +120,7 @@
     "@juicesharp/rpiv-ask-user-question",
     "@narumitw/pi-btw",
     "@pi-plugins/fast-mode",
+    "pi-footer",
     "pi-lens",
     "pi-mcp-adapter",
     "pi-web-access",
@@ -147,7 +151,8 @@
       "./node_modules/pi-lens/dist/index.js",
       "./node_modules/pi-web-access/index.ts",
       "./node_modules/remote-pi/dist/index.js",
-      "./node_modules/@czottmann/pi-automode/extensions/auto-mode.ts"
+      "./node_modules/@czottmann/pi-automode/extensions/auto-mode.ts",
+      "./node_modules/pi-footer/src/index.ts"
     ],
     "themes": [
       "./node_modules/@herbertgao/pi-cc-extensions/themes/cc-dark.json",