@herbertgao/pi-extensions 2026.8.2 → 2026.8.4

package/node_modules/pi-footer/src/git.ts

@@ -0,0 +1,135 @@
+import { basename } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { asyncCache, CACHE_NAMESPACES } from "./cache.js";
+import type { GitInfo, StatuslineConfig } from "./types.js";
+
+const CACHE_TTL_MS = 2000;
+
+export const EMPTY_GIT_INFO: GitInfo = {
+  branch: null,
+  sha: null,
+  root: null,
+  staged: 0,
+  unstaged: 0,
+  untracked: 0,
+  insertions: 0,
+  deletions: 0,
+  ahead: 0,
+  behind: 0,
+  remote: null,
+  isRepo: false,
+};
+
+interface GitFetch {
+  pi: ExtensionAPI;
+  cwd: string;
+  branchHint: string | null;
+}
+
+// SWR read for the live footer: returns the cached (possibly stale) value immediately, kicks an
+// async refresh through asyncCache, and repaints via requestRender when fresh data lands. Stays
+// off the render path's critical section — the git subprocesses run async via pi.exec.
+export function getGitInfo(
+  pi: ExtensionAPI,
+  cwd: string,
+  branchHint: string | null,
+  requestRender: () => void,
+): GitInfo {
+  return (
+    asyncCache.get(
+      CACHE_NAMESPACES.git,
+      `${cwd}:${branchHint ?? ""}`,
+      CACHE_TTL_MS,
+      { pi, cwd, branchHint },
+      fetchGitInfo,
+      requestRender,
+    ) ?? EMPTY_GIT_INFO
+  );
+}
+
+// Awaitable git fetch for callers that can block (e.g. the config-UI preview command). Same work
+// the SWR fetcher does, exposed directly so a one-shot snapshot can await real data.
+export function loadGitInfo(
+  pi: ExtensionAPI,
+  cwd: string,
+  branchHint: string | null,
+): Promise<GitInfo> {
+  return fetchGitInfo({ pi, cwd, branchHint }).then((info) => info ?? EMPTY_GIT_INFO);
+}
+
+async function fetchGitInfo({ pi, cwd, branchHint }: GitFetch): Promise<GitInfo | null> {
+  const rootPath = await git(pi, cwd, ["rev-parse", "--show-toplevel"]);
+  if (!rootPath) return EMPTY_GIT_INFO;
+
+  const [branch, sha, porcelain, shortstat, aheadBehind, remote] = await Promise.all([
+    branchHint ? Promise.resolve(branchHint) : git(pi, cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    git(pi, cwd, ["rev-parse", "--short", "HEAD"]),
+    git(pi, cwd, ["status", "--porcelain=v1"]),
+    git(pi, cwd, ["diff", "--shortstat", "HEAD"]),
+    git(pi, cwd, ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"]),
+    git(pi, cwd, ["remote", "get-url", "origin"]),
+  ]);
+
+  return {
+    branch,
+    sha,
+    root: basename(rootPath),
+    ...parsePorcelain(porcelain),
+    ...parseShortstat(shortstat),
+    ...parseAheadBehind(aheadBehind),
+    remote,
+    isRepo: true,
+  };
+}
+
+async function git(pi: ExtensionAPI, cwd: string, args: string[]): Promise<string | null> {
+  const { stdout, code, killed } = await pi.exec("git", args, { cwd, timeout: 500 });
+  // trimEnd, not trim: `status --porcelain=v1` encodes staged vs unstaged in columns 1/2, so the
+  // leading space of the first line is significant. trim() would strip it and miscount that file.
+  return code !== 0 || killed ? null : stdout.trimEnd() || null;
+}
+
+function parsePorcelain(output: string | null): Pick<GitInfo, "staged" | "unstaged" | "untracked"> {
+  let staged = 0;
+  let unstaged = 0;
+  let untracked = 0;
+
+  for (const line of output?.split("\n") ?? []) {
+    if (line.length < 2) continue;
+    const x = line[0];
+    const y = line[1];
+    if (x === "?" && y === "?") {
+      untracked += 1;
+      continue;
+    }
+    if (x !== " " && x !== undefined) staged += 1;
+    if (y !== " " && y !== undefined) unstaged += 1;
+  }
+
+  return { staged, unstaged, untracked };
+}
+
+function parseShortstat(output: string | null): Pick<GitInfo, "insertions" | "deletions"> {
+  const insertions = /([0-9]+) insertion/.exec(output ?? "")?.[1];
+  const deletions = /([0-9]+) deletion/.exec(output ?? "")?.[1];
+  return {
+    insertions: insertions ? Number(insertions) : 0,
+    deletions: deletions ? Number(deletions) : 0,
+  };
+}
+
+function parseAheadBehind(output: string | null): Pick<GitInfo, "ahead" | "behind"> {
+  const [behind, ahead] = output?.split(/\s+/).map(Number) ?? [];
+  return {
+    ahead: Number.isFinite(ahead) ? (ahead ?? 0) : 0,
+    behind: Number.isFinite(behind) ? (behind ?? 0) : 0,
+  };
+}
+
+export function hasEnabledGitWidgets(config: Pick<StatuslineConfig, "lines">): boolean {
+  return config.lines.some((line) =>
+    line.some((widget) => widget.enabled && widget.type.startsWith("git-")),
+  );
+}

package/node_modules/pi-footer/src/index.ts

@@ -0,0 +1,268 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+import {
+  cloneConfig,
+  configWithPreset,
+  DEFAULT_CONFIG,
+  isPreset,
+  loadConfig,
+  saveConfig,
+  STATUS_KEY,
+} from "./config.js";
+import { EventWidgetValues, UPDATE_EVENT_WIDGET_EVENT } from "./event-widgets.js";
+import {
+  EMPTY_EXTENSION_STATUSES,
+  visibleExtensionStatusRowEntries,
+} from "./extension-statuses.js";
+import { EMPTY_GIT_INFO, getGitInfo, hasEnabledGitWidgets, loadGitInfo } from "./git.js";
+import { collectSessionMetrics, collectTurnMetrics } from "./metrics.js";
+import { renderStatuslines } from "./render.js";
+import { isRecord, type GitInfo, type StatuslineConfig, type StatuslineData } from "./types.js";
+import { openStatuslineConfigUi } from "./ui.js";
+import { WidgetStore } from "./widgets/store.js";
+
+// Structural mirror of pi's footerData — collectStatuslineData only needs the branch getter.
+interface FooterDataLike {
+  getGitBranch(): string | null;
+}
+
+export default async function statuslineExtension(pi: ExtensionAPI): Promise<void> {
+  let config = await loadConfig();
+  let widgetStore = WidgetStore.fromConfig(config);
+  const eventWidgets = new EventWidgetValues();
+  let liveTextVerbosity: string | undefined;
+  let renderCurrentFooter: (() => void) | undefined;
+  let getExtensionStatuses = (): ReadonlyMap<string, string> => EMPTY_EXTENSION_STATUSES;
+
+  function apply(ctx: ExtensionContext | ExtensionCommandContext): void {
+    if (!ctx.hasUI || !config.enabled) {
+      ctx.ui.setFooter(undefined);
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+
+    ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("accent", "pi-footer"));
+    ctx.ui.setFooter((tui, theme, footerData) => {
+      getExtensionStatuses = () => footerData.getExtensionStatuses();
+      renderCurrentFooter = () => tui.requestRender();
+      const unsubscribeBranch = footerData.onBranchChange(() => tui.requestRender());
+      return {
+        dispose(): void {
+          unsubscribeBranch();
+          if (renderCurrentFooter) renderCurrentFooter = undefined;
+          getExtensionStatuses = () => EMPTY_EXTENSION_STATUSES;
+        },
+        invalidate(): void {},
+        render(width: number): string[] {
+          const data = collectStatuslineData(ctx, pi, footerData, eventWidgets.values, {
+            config,
+            requestRender: () => tui.requestRender(),
+            textVerbosity: liveTextVerbosity,
+          });
+          const lines = renderStatuslines(widgetStore, data, width, {
+            getExtensionStatuses,
+            theme,
+            requestRender: () => tui.requestRender(),
+          });
+          if (lines.length === 0) return [];
+
+          const statuses = visibleExtensionStatusRowEntries(
+            footerData.getExtensionStatuses(),
+            config.extensionStatusRow.hiddenKeys,
+            STATUS_KEY,
+          ).map((entry) => entry.value);
+          const renderedLines = lines.map((line) => truncateToWidth(line, width, "…"));
+          if (statuses.length === 0) return renderedLines;
+          return [
+            ...renderedLines,
+            truncateToWidth(theme.fg("dim", statuses.join(" ")), width, "…"),
+          ];
+        },
+      };
+    });
+  }
+
+  function replaceConfig(next: StatuslineConfig): void {
+    config = next;
+    widgetStore = WidgetStore.fromConfig(config);
+  }
+
+  async function setConfig(
+    next: StatuslineConfig,
+    ctx: ExtensionContext | ExtensionCommandContext,
+  ): Promise<void> {
+    replaceConfig(next);
+    await saveConfig(config);
+    apply(ctx);
+  }
+
+  pi.events.on(UPDATE_EVENT_WIDGET_EVENT, (payload: unknown) => {
+    const changed = eventWidgets.update(payload);
+    if (changed) renderCurrentFooter?.();
+  });
+
+  // pi has no verbosity accessor; capture the real value from the actual provider
+  // request payload. Passive — the footer picks it up on its next render rather than
+  // forcing one. Only the openai-codex-responses payload carries text.verbosity.
+  //
+  // Handlers run in extension load order and the payload is chained forward, so we
+  // observe it as of our own position in that chain (we return undefined and never
+  // mutate it). A custom provider that bakes verbosity into the body is always seen;
+  // a later-loaded extension that rewrites text.verbosity in its own
+  // before_provider_request handler is the one case we'd miss.
+  pi.on("before_provider_request", (event) => {
+    const verbosity = readTextVerbosity(event.payload);
+    if (verbosity !== undefined) liveTextVerbosity = verbosity;
+  });
+
+  pi.registerCommand("footer", {
+    description: "Configure the pi statusline/footer",
+    handler: async (args, ctx) => {
+      const handled = await handleArgs(args, ctx, config, async (next) => setConfig(next, ctx));
+      if (handled) return;
+
+      const previewData = collectStatuslineData(
+        ctx,
+        pi,
+        {
+          getGitBranch: () => "main",
+        },
+        eventWidgets.values,
+        {
+          collectGit: true,
+          git: await loadGitInfo(pi, ctx.cwd, "main"),
+          textVerbosity: liveTextVerbosity,
+        },
+      );
+      const result = await openStatuslineConfigUi(
+        ctx,
+        config,
+        previewData,
+        (updated) => {
+          replaceConfig(updated);
+          apply(ctx);
+        },
+        async (updated) => setConfig(updated, ctx),
+        getExtensionStatuses,
+      );
+      replaceConfig(result.config);
+      apply(ctx);
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    replaceConfig(await loadConfig());
+    apply(ctx);
+  });
+
+  pi.on("model_select", async (_event, ctx) => {
+    // A new model selection invalidates the captured verbosity; fall back to the
+    // provider default until the next request reveals the real value.
+    liveTextVerbosity = undefined;
+    apply(ctx);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    ctx.ui.setFooter(undefined);
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  });
+}
+
+function collectStatuslineData(
+  ctx: ExtensionContext | ExtensionCommandContext,
+  pi: ExtensionAPI,
+  footerData: FooterDataLike,
+  eventWidgets: ReadonlyMap<string, string>,
+  options: {
+    config?: StatuslineConfig;
+    collectGit?: boolean;
+    requestRender?: () => void;
+    git?: GitInfo;
+    textVerbosity?: string | undefined;
+  } = {},
+): StatuslineData {
+  const contextUsage = ctx.getContextUsage();
+  const collectGit =
+    options.collectGit ?? (options.config ? hasEnabledGitWidgets(options.config) : true);
+  return {
+    model: ctx.model?.id,
+    provider: ctx.model?.provider,
+    sessionName: pi.getSessionName(),
+    sessionId: ctx.sessionManager.getSessionId(),
+    thinkingLevel: ctx.model?.reasoning ? pi.getThinkingLevel() : undefined,
+    textVerbosity: getTextVerbosity(ctx.model, options.textVerbosity),
+    git:
+      options.git ??
+      (collectGit
+        ? getGitInfo(pi, ctx.cwd, footerData.getGitBranch(), options.requestRender ?? (() => {}))
+        : EMPTY_GIT_INFO),
+    cwd: ctx.cwd,
+    activeToolCount: pi.getActiveTools().length,
+    usingSubscription: ctx.model ? ctx.modelRegistry.isUsingOAuth(ctx.model) : false,
+    contextTokens: contextUsage?.tokens ?? undefined,
+    contextMaxTokens: contextUsage?.contextWindow,
+    metrics: collectSessionMetrics(ctx.sessionManager.getBranch()),
+    turnMetrics: collectTurnMetrics(ctx.sessionManager.getEntries()),
+    eventWidgets,
+  };
+}
+
+async function handleArgs(
+  args: string,
+  ctx: ExtensionCommandContext,
+  currentConfig: StatuslineConfig,
+  setConfig: (config: StatuslineConfig) => Promise<void>,
+): Promise<boolean> {
+  const [command, value] = args.trim().split(/\s+/, 2);
+  if (!command) return false;
+
+  if (command === "on" || command === "enable") {
+    await setConfig({ ...currentConfig, enabled: true });
+    ctx.ui.notify("pi-footer enabled", "info");
+    return true;
+  }
+  if (command === "off" || command === "disable") {
+    await setConfig({ ...currentConfig, enabled: false });
+    ctx.ui.notify("pi-footer disabled", "info");
+    return true;
+  }
+  if (command === "reset") {
+    await setConfig(cloneConfig(DEFAULT_CONFIG));
+    ctx.ui.notify("pi-footer reset to defaults", "info");
+    return true;
+  }
+  if (command === "preset" && isPreset(value)) {
+    await setConfig(configWithPreset(currentConfig, value));
+    ctx.ui.notify(`pi-footer preset: ${value}`, "info");
+    return true;
+  }
+
+  ctx.ui.notify(
+    "Usage: /footer [on|off|reset|preset compact|default|powerline|powerline-bright|powerline-blocks|powerline-mono|git-heavy|pi-footer|demo|demo-standard]",
+    "warning",
+  );
+  return true;
+}
+
+function getTextVerbosity(
+  model: ExtensionContext["model"],
+  liveVerbosity: string | undefined,
+): string | undefined {
+  // pi exposes text verbosity only through the OpenAI Codex Responses provider.
+  if (!model || model.api !== "openai-codex-responses") return undefined;
+  // Prefer the value captured from the real request payload; before the first
+  // request (or just after a model switch) fall back to the provider default.
+  return liveVerbosity ?? "low";
+}
+
+function readTextVerbosity(payload: unknown): string | undefined {
+  if (!isRecord(payload)) return undefined;
+  const text = payload.text;
+  if (!isRecord(text)) return undefined;
+  return typeof text.verbosity === "string" ? text.verbosity : undefined;
+}

package/node_modules/pi-footer/src/metrics.ts

@@ -0,0 +1,141 @@
+import { isRecord, type SessionMetrics, type TurnMetrics } from "./types.js";
+
+// Intentionally loose structural projection of the `usage` field on a pi session message entry.
+// Fields stay `unknown` and are validated at runtime (see isRecord usage below) rather than being
+// derived from pi's SDK types — keeps the defensive parsing robust to upstream shape changes.
+interface UsageLike {
+  input?: unknown;
+  output?: unknown;
+  cacheRead?: unknown;
+  cacheWrite?: unknown;
+  totalTokens?: unknown;
+  cost?: {
+    total?: unknown;
+  };
+}
+
+// Intentionally loose structural projection of a pi session message entry (from
+// sessionManager.getBranch()). Same rationale as UsageLike: `unknown` fields, runtime-validated.
+interface MessageLike {
+  role?: unknown;
+  timestamp?: unknown;
+  usage?: unknown;
+}
+
+export function collectSessionMetrics(entries: readonly unknown[]): SessionMetrics {
+  const metrics: SessionMetrics = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    totalTokens: 0,
+    costUsd: 0,
+    userMessages: 0,
+    assistantMessages: 0,
+    toolResults: 0,
+    firstTimestampMs: undefined,
+    lastTimestampMs: undefined,
+    compactions: 0,
+  };
+
+  for (const entry of entries) {
+    const message = getMessage(entry);
+    if (!message) continue;
+
+    const timestampMs = normalizeTimestamp(message.timestamp ?? getEntryTimestamp(entry));
+    if (timestampMs !== undefined) {
+      metrics.firstTimestampMs =
+        metrics.firstTimestampMs === undefined
+          ? timestampMs
+          : Math.min(metrics.firstTimestampMs, timestampMs);
+      metrics.lastTimestampMs =
+        metrics.lastTimestampMs === undefined
+          ? timestampMs
+          : Math.max(metrics.lastTimestampMs, timestampMs);
+    }
+
+    if (message.role === "user") metrics.userMessages += 1;
+    if (message.role === "toolResult") metrics.toolResults += 1;
+    if (message.role === "compactionSummary") metrics.compactions += 1;
+    if (message.role !== "assistant") continue;
+
+    metrics.assistantMessages += 1;
+    const usage = getUsage(message.usage);
+    if (!usage) continue;
+
+    const input = numberOrZero(usage.input);
+    const output = numberOrZero(usage.output);
+    const cacheRead = numberOrZero(usage.cacheRead);
+    const cacheWrite = numberOrZero(usage.cacheWrite);
+
+    metrics.inputTokens += input;
+    metrics.outputTokens += output;
+    metrics.cacheReadTokens += cacheRead;
+    metrics.cacheWriteTokens += cacheWrite;
+    metrics.totalTokens +=
+      numberOrZero(usage.totalTokens) || input + output + cacheRead + cacheWrite;
+    metrics.costUsd += numberOrZero(usage.cost?.total);
+  }
+
+  return metrics;
+}
+
+export function collectTurnMetrics(entries: readonly unknown[]): TurnMetrics {
+  const metrics: TurnMetrics = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    totalTokens: 0,
+    costUsd: 0,
+  };
+
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const message = getMessage(entries[index]);
+    if (message?.role !== "assistant") continue;
+
+    const usage = getUsage(message.usage);
+    if (!usage) continue;
+
+    const input = numberOrZero(usage.input);
+    const output = numberOrZero(usage.output);
+    const cacheRead = numberOrZero(usage.cacheRead);
+    const cacheWrite = numberOrZero(usage.cacheWrite);
+
+    metrics.inputTokens = input;
+    metrics.outputTokens = output;
+    metrics.cacheReadTokens = cacheRead;
+    metrics.cacheWriteTokens = cacheWrite;
+    metrics.totalTokens =
+      numberOrZero(usage.totalTokens) || input + output + cacheRead + cacheWrite;
+    metrics.costUsd = numberOrZero(usage.cost?.total);
+    return metrics;
+  }
+
+  return metrics;
+}
+
+function getMessage(entry: unknown): MessageLike | undefined {
+  if (!isRecord(entry)) return undefined;
+  const message = entry.message;
+  return isRecord(message) ? message : undefined;
+}
+
+function getEntryTimestamp(entry: unknown): unknown {
+  return isRecord(entry) ? entry.timestamp : undefined;
+}
+
+function getUsage(value: unknown): UsageLike | undefined {
+  return isRecord(value) ? (value as UsageLike) : undefined;
+}
+
+function normalizeTimestamp(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "string") return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function numberOrZero(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}