@albizures/pi-footer-status 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @albizures/pi-footer-status
+
+## 0.1.1
+
+### Patch Changes
+
+- 8b46ddd: Replace the scaffolded footer status extension with an always-on default-like Pi footer that adds a Context fill bar.
+- 8b46ddd: Add the initial Pi footer status extension package scaffold.

package/README.md

@@ -0,0 +1,44 @@
+# @albizures/pi-footer-status
+
+A tiny Pi package that replaces Pi's footer with a default-like custom footer and adds a dedicated Context fill bar.
+
+After installation, the package is always on. It is no longer a no-op scaffold, and it does not add slash commands or configuration.
+
+## Behavior
+
+The custom footer keeps the default-like Pi footer information:
+
+- current working directory, git branch, and session name
+- cumulative input/output token usage
+- cache read/write stats and cache hit percentage when available
+- cumulative cost or subscription-backed usage marker when available
+- textual current context percentage on the stats line
+- active model, provider when useful, and thinking level for reasoning models
+
+It mirrors these default-like footer lines, then preserves extension status messages after the Context fill bar.
+
+It inserts one additional Context fill bar line before extension statuses:
+
+```text
+context ████████░░░░░░░░░░░░ 40.0%/128k
+```
+
+The Context fill bar:
+
+- is labeled `context`
+- represents Pi's current context usage, not cumulative token totals
+- uses Pi's public current context usage API
+- is fixed at 20 cells
+- uses `█` for filled cells and `░` for empty cells
+- rounds the fill amount to the nearest cell
+- shows at least one filled cell for any known non-zero usage
+- uses the theme accent color normally, warning above 70%, and error above 90%
+- keeps empty cells dim
+- appends the numeric `percent/contextWindow` suffix on the same line
+- does not include `(auto)` on the bar line
+
+When current context usage is unknown, the footer renders a static placeholder instead of guessing:
+
+```text
+context ░░░░░░░░░░░░░░░░░░░░ ?/128k
+```

package/extensions/index.test.ts

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { renderContextFillBar, renderFooter } from "./index.ts";
+
+const identityTheme = {
+  fg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+};
+
+const taggedTheme = {
+  fg: (color: string, text: string) => `<${color}>${text}</${color}>`,
+  bold: (text: string) => `<bold>${text}</bold>`,
+};
+
+function assistantEntry(usage: Partial<any>) {
+  return {
+    type: "message",
+    message: {
+      role: "assistant",
+      usage: {
+        input: 1200,
+        output: 345,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: { total: 0 },
+        ...usage,
+      },
+    },
+  } as any;
+}
+
+function baseState(overrides: Record<string, unknown> = {}) {
+  return {
+    cwd: "/home/alice/work/repo",
+    home: "/home/alice",
+    sessionName: "named-session",
+    gitBranch: "main",
+    extensionStatuses: new Map<string, string>(),
+    availableProviderCount: 1,
+    model: { id: "gpt-test", provider: "openai", contextWindow: 128000, reasoning: true },
+    thinkingLevel: "medium",
+    contextUsage: { tokens: 51200, contextWindow: 128000, percent: 40 },
+    entries: [assistantEntry({ cacheRead: 100, cacheWrite: 50, cost: { total: 0.0123 } })],
+    ...overrides,
+  } as any;
+}
+
+test("renderFooter preserves default-like footer lines and inserts the Context fill bar before sorted extension statuses", () => {
+  const lines = renderFooter(
+    baseState({ extensionStatuses: new Map([["z-last", "second"], ["a-first", "first"]]) }),
+    identityTheme,
+    120,
+  );
+
+  assert.equal(lines.length, 4);
+  assert.equal(lines[0], "~/work/repo (main) • named-session");
+  assert.match(lines[1], /↑1\.2k ↓345 R100 W50 CH7\.4% \$0\.012 40\.0%\/128k \(auto\)\s+gpt-test • medium/);
+  assert.equal(lines[2], "context ████████░░░░░░░░░░░░ 40.0%/128k");
+  assert.equal(lines[3], "first second");
+});
+
+test("renderContextFillBar uses fixed 20-cell known-usage bars with required rounding behavior", () => {
+  const cases = [
+    { percent: 0, expected: "░░░░░░░░░░░░░░░░░░░░ 0.0%/100k" },
+    { percent: 1, expected: "█░░░░░░░░░░░░░░░░░░░ 1.0%/100k" },
+    { percent: 40, expected: "████████░░░░░░░░░░░░ 40.0%/100k" },
+    { percent: 99.6, expected: "████████████████████ 99.6%/100k" },
+  ];
+
+  for (const { percent, expected } of cases) {
+    assert.equal(renderContextFillBar({ percent, contextWindow: 100000 }, identityTheme, 120), `context ${expected}`);
+  }
+});
+
+test("renderContextFillBar applies severity colors at the same thresholds as Pi context text", () => {
+  const normal = renderContextFillBar({ percent: 40, contextWindow: 100000 }, taggedTheme, 200);
+  assert.match(normal, /<accent>█/);
+  assert.match(normal, /<dim>░/);
+  assert.match(normal, /<accent>40\.0%\/100k<\/accent>/);
+
+  const warning = renderContextFillBar({ percent: 70.1, contextWindow: 100000 }, taggedTheme, 200);
+  assert.match(warning, /<warning>█/);
+  assert.match(warning, /<dim>░/);
+  assert.match(warning, /<warning>70\.1%\/100k<\/warning>/);
+
+  assert.match(renderContextFillBar({ percent: 90.1, contextWindow: 100000 }, taggedTheme, 200), /<error>█/);
+  assert.match(renderContextFillBar({ percent: 90.1, contextWindow: 100000 }, taggedTheme, 200), /<error>90\.1%\/100k<\/error>/);
+});
+
+test("renderContextFillBar renders unknown usage as a static dim placeholder with ? percentage", () => {
+  const line = renderContextFillBar({ percent: null, contextWindow: 200000 }, identityTheme, 120);
+
+  assert.equal(line, "context ░░░░░░░░░░░░░░░░░░░░ ?/200k");
+
+  const styledLine = renderContextFillBar({ percent: undefined, contextWindow: 200000 }, taggedTheme, 200);
+  assert.match(styledLine, /<dim>░░░░░░░░░░░░░░░░░░░░<\/dim>/);
+  assert.match(styledLine, /\?\/200k/);
+  assert.doesNotMatch(styledLine, /<accent>|<warning>|<error>/);
+});
+
+test("renderFooter renders unknown Context fill bar line without auto-compaction text", () => {
+  const lines = renderFooter(baseState({ contextUsage: { tokens: 0, contextWindow: 128000, percent: null } }), identityTheme, 120);
+
+  assert.equal(lines[2], "context ░░░░░░░░░░░░░░░░░░░░ ?/128k");
+  assert.doesNotMatch(lines[2], /auto/);
+});
+
+test("renderFooter truncates all rendered lines to terminal width", () => {
+  const lines = renderFooter(
+    baseState({
+      cwd: "/home/alice/a/very/long/path/to/a/repository",
+      sessionName: "a very long session name",
+      extensionStatuses: new Map([["status", "a very long extension status that must be truncated"]]),
+    }),
+    identityTheme,
+    24,
+  );
+
+  assert.ok(lines.length >= 4);
+  for (const line of lines) {
+    assert.ok(visibleWidth(line) <= 24, `${line} exceeded width`);
+  }
+});

package/extensions/index.ts

@@ -0,0 +1,303 @@
+import type { ContextUsage, ExtensionAPI, ExtensionContext, ReadonlyFooterDataProvider } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+const BAR_WIDTH = 20;
+const WARNING_PERCENT = 70;
+const ERROR_PERCENT = 90;
+
+type ThemeColor = "accent" | "dim" | "error" | "warning";
+
+type FooterTheme = {
+  fg(color: ThemeColor | string, text: string): string;
+  bold(text: string): string;
+};
+
+type FooterModel = {
+  id: string;
+  provider: string;
+  contextWindow: number;
+  reasoning?: boolean;
+};
+
+type FooterState = {
+  cwd: string;
+  sessionName?: string;
+  gitBranch: string | null;
+  extensionStatuses: ReadonlyMap<string, string>;
+  availableProviderCount: number;
+  model?: FooterModel;
+  thinkingLevel?: string;
+  contextUsage?: ContextUsage;
+  entries: ExtensionContext["sessionManager"] extends { getEntries(): infer Entries } ? Entries : never;
+  usingSubscription?: boolean;
+  experimental?: boolean;
+  home?: string;
+  autoCompactEnabled?: boolean;
+};
+
+type FooterUsage = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: { total?: number };
+};
+
+type UsageTotals = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+};
+
+export default function (pi: ExtensionAPI) {
+  let requestRender: (() => void) | undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setFooter((tui, theme, footerData) => {
+      requestRender = () => tui.requestRender();
+      const disposeBranch = footerData.onBranchChange(() => tui.requestRender());
+
+      return {
+        dispose() {
+          disposeBranch();
+          requestRender = undefined;
+        },
+        invalidate() {},
+        render(width: number): string[] {
+          return renderFooter(
+            collectFooterState(ctx, footerData, process.env.HOME || process.env.USERPROFILE),
+            theme,
+            width,
+          );
+        },
+      };
+    });
+  });
+
+  const rerender = () => {
+    requestRender?.();
+  };
+  pi.on("model_select", rerender);
+  pi.on("thinking_level_select", rerender);
+  pi.on("session_info_changed", rerender);
+  pi.on("message_end", rerender);
+  pi.on("agent_settled", rerender);
+  pi.on("session_compact", rerender);
+}
+
+function collectFooterState(
+  ctx: ExtensionContext,
+  footerData: ReadonlyFooterDataProvider,
+  home: string | undefined,
+): FooterState {
+  const model = ctx.model
+    ? {
+        id: ctx.model.id,
+        provider: ctx.model.provider,
+        contextWindow: ctx.model.contextWindow,
+        reasoning: ctx.model.reasoning,
+      }
+    : undefined;
+
+  return {
+    cwd: ctx.sessionManager.getCwd(),
+    sessionName: ctx.sessionManager.getSessionName(),
+    gitBranch: footerData.getGitBranch(),
+    extensionStatuses: footerData.getExtensionStatuses(),
+    availableProviderCount: footerData.getAvailableProviderCount(),
+    model,
+    thinkingLevel: ctx.thinkingLevel,
+    contextUsage: ctx.getContextUsage(),
+    entries: ctx.sessionManager.getEntries(),
+    usingSubscription: ctx.model
+      ? ctx.model.provider === "kimi-coding" || ctx.modelRegistry.isUsingOAuth(ctx.model)
+      : false,
+    experimental: process.env.PI_EXPERIMENTAL === "1",
+    home,
+  };
+}
+
+export function renderFooter(state: FooterState, theme: FooterTheme, width: number): string[] {
+  const usage = getUsageStats(state.entries);
+  const contextUsage = state.contextUsage;
+  const contextWindow = contextUsage?.contextWindow ?? state.model?.contextWindow ?? 0;
+  const contextPercentValue = contextUsage?.percent ?? 0;
+  const contextPercent = contextUsage?.percent !== null && contextUsage?.percent !== undefined
+    ? contextPercentValue.toFixed(1)
+    : "?";
+
+  let pwd = formatCwdForFooter(state.cwd, state.home);
+  if (state.gitBranch) pwd = `${pwd} (${state.gitBranch})`;
+  if (state.sessionName) pwd = `${pwd} • ${state.sessionName}`;
+
+  const statsParts: string[] = [];
+  if (usage.totals.input) statsParts.push(`↑${formatTokens(usage.totals.input)}`);
+  if (usage.totals.output) statsParts.push(`↓${formatTokens(usage.totals.output)}`);
+  if (usage.totals.cacheRead) statsParts.push(`R${formatTokens(usage.totals.cacheRead)}`);
+  if (usage.totals.cacheWrite) statsParts.push(`W${formatTokens(usage.totals.cacheWrite)}`);
+  if ((usage.totals.cacheRead > 0 || usage.totals.cacheWrite > 0) && usage.latestCacheHitRate !== undefined) {
+    statsParts.push(`CH${usage.latestCacheHitRate.toFixed(1)}%`);
+  }
+  if (usage.totals.cost || state.usingSubscription) {
+    statsParts.push(`$${usage.totals.cost.toFixed(3)}${state.usingSubscription ? " (sub)" : ""}`);
+  }
+
+  const autoIndicator = state.autoCompactEnabled === false ? "" : " (auto)";
+  const contextPercentDisplay = contextPercent === "?"
+    ? `?/${formatTokens(contextWindow)}${autoIndicator}`
+    : `${contextPercent}%/${formatTokens(contextWindow)}${autoIndicator}`;
+  statsParts.push(colorByContextSeverity(contextPercentValue, contextPercentDisplay, theme));
+  if (state.experimental) statsParts.push(`${theme.fg("dim", "•")} ${theme.bold(theme.fg("warning", "xp"))}`);
+
+  const statsLine = renderStatsLine(statsParts.join(" "), state, theme, width);
+  const contextBarLine = renderContextFillBar({ percent: contextUsage?.percent, contextWindow }, theme, width);
+
+  const lines = [
+    truncateToWidth(theme.fg("dim", pwd), width, theme.fg("dim", "...")),
+    statsLine,
+    contextBarLine,
+  ];
+
+  const statuses = renderExtensionStatuses(state.extensionStatuses, theme, width);
+  if (statuses) lines.push(statuses);
+  return lines;
+}
+
+function renderStatsLine(statsLeftInput: string, state: FooterState, theme: FooterTheme, width: number): string {
+  let statsLeft = statsLeftInput;
+  let statsLeftWidth = visibleWidth(statsLeft);
+  if (statsLeftWidth > width) {
+    statsLeft = truncateToWidth(statsLeft, width, "...");
+    statsLeftWidth = visibleWidth(statsLeft);
+  }
+
+  const modelName = state.model?.id || "no-model";
+  let rightSideWithoutProvider = modelName;
+  if (state.model?.reasoning) {
+    const thinkingLevel = state.thinkingLevel || "off";
+    rightSideWithoutProvider = thinkingLevel === "off" ? `${modelName} • thinking off` : `${modelName} • ${thinkingLevel}`;
+  }
+
+  let rightSide = rightSideWithoutProvider;
+  if (state.availableProviderCount > 1 && state.model) {
+    rightSide = `(${state.model.provider}) ${rightSideWithoutProvider}`;
+    if (statsLeftWidth + 2 + visibleWidth(rightSide) > width) rightSide = rightSideWithoutProvider;
+  }
+
+  const rightSideWidth = visibleWidth(rightSide);
+  let statsLine: string;
+  if (statsLeftWidth + 2 + rightSideWidth <= width) {
+    statsLine = statsLeft + " ".repeat(width - statsLeftWidth - rightSideWidth) + rightSide;
+  } else {
+    const availableForRight = width - statsLeftWidth - 2;
+    if (availableForRight > 0) {
+      const truncatedRight = truncateToWidth(rightSide, availableForRight, "");
+      statsLine = statsLeft + " ".repeat(Math.max(0, width - statsLeftWidth - visibleWidth(truncatedRight))) + truncatedRight;
+    } else {
+      statsLine = statsLeft;
+    }
+  }
+
+  return theme.fg("dim", statsLeft) + theme.fg("dim", statsLine.slice(statsLeft.length));
+}
+
+export function renderContextFillBar(
+  usage: { percent: number | null | undefined; contextWindow: number },
+  theme: FooterTheme,
+  width: number,
+): string {
+  if (usage.percent === null || usage.percent === undefined) {
+    const placeholder = theme.fg("dim", "░".repeat(BAR_WIDTH));
+    return truncateToWidth(`context ${placeholder} ?/${formatTokens(usage.contextWindow)}`, width, theme.fg("dim", "..."));
+  }
+
+  const clampedPercent = Math.max(0, Math.min(100, usage.percent));
+  let filled = Math.round((clampedPercent / 100) * BAR_WIDTH);
+  if (clampedPercent > 0) filled = Math.max(1, filled);
+  if (clampedPercent >= 99.5) filled = BAR_WIDTH;
+
+  const filledCells = "█".repeat(filled);
+  const emptyCells = "░".repeat(BAR_WIDTH - filled);
+  const severityColor = clampedPercent > ERROR_PERCENT ? "error" : clampedPercent > WARNING_PERCENT ? "warning" : "accent";
+  const numeric = `${usage.percent.toFixed(1)}%/${formatTokens(usage.contextWindow)}`;
+  const line = `context ${theme.fg(severityColor, filledCells)}${theme.fg("dim", emptyCells)} ${theme.fg(severityColor, numeric)}`;
+  return truncateToWidth(line, width, theme.fg("dim", "..."));
+}
+
+function renderExtensionStatuses(statuses: ReadonlyMap<string, string>, theme: FooterTheme, width: number): string | undefined {
+  if (statuses.size === 0) return undefined;
+  const statusLine = Array.from(statuses.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([, text]) => sanitizeStatusText(text))
+    .join(" ");
+  return truncateToWidth(statusLine, width, theme.fg("dim", "..."));
+}
+
+function getUsageStats(entries: FooterState["entries"]): { totals: UsageTotals; latestCacheHitRate?: number } {
+  const totals: UsageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  let latestCacheHitRate: number | undefined;
+
+  for (const entry of entries) {
+    const usage = getEntryUsage(entry);
+    if (!usage) continue;
+    addUsage(totals, usage);
+
+    if (entry.type === "message" && entry.message.role === "assistant") {
+      const cacheRead = usage.cacheRead ?? 0;
+      const promptTokens = (usage.input ?? 0) + cacheRead + (usage.cacheWrite ?? 0);
+      latestCacheHitRate = promptTokens > 0 ? (cacheRead / promptTokens) * 100 : undefined;
+    }
+  }
+
+  return { totals, latestCacheHitRate };
+}
+
+function getEntryUsage(entry: FooterState["entries"][number]): FooterUsage | undefined {
+  if (entry.type === "message") {
+    if (entry.message.role === "assistant") return entry.message.usage;
+    if (entry.message.role === "toolResult") return entry.message.usage;
+  }
+  if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) return entry.usage;
+  return undefined;
+}
+
+function addUsage(totals: UsageTotals, usage: FooterUsage): void {
+  totals.input += usage.input ?? 0;
+  totals.output += usage.output ?? 0;
+  totals.cacheRead += usage.cacheRead ?? 0;
+  totals.cacheWrite += usage.cacheWrite ?? 0;
+  totals.cost += usage.cost?.total ?? 0;
+}
+
+function colorByContextSeverity(percent: number, text: string, theme: FooterTheme): string {
+  if (percent > ERROR_PERCENT) return theme.fg("error", text);
+  if (percent > WARNING_PERCENT) return theme.fg("warning", text);
+  return text;
+}
+
+function sanitizeStatusText(text: string): string {
+  return text.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim();
+}
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+  return `${Math.round(count / 1000000)}M`;
+}
+
+export function formatCwdForFooter(cwd: string, home: string | undefined): string {
+  if (!home) return cwd;
+  const resolvedCwd = resolve(cwd);
+  const resolvedHome = resolve(home);
+  const relativeToHome = relative(resolvedHome, resolvedCwd);
+  const isInsideHome =
+    relativeToHome === "" ||
+    (relativeToHome !== ".." && !relativeToHome.startsWith(`..${sep}`) && !isAbsolute(relativeToHome));
+  if (!isInsideHome) return cwd;
+  return relativeToHome === "" ? "~" : `~${sep}${relativeToHome}`;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@albizures/pi-footer-status",
+  "version": "0.1.1",
+  "description": "Pi package for customizing the footer status area.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "footer",
+    "status"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "^0.82.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}