pi-footer-manager 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# pi-footer-manager
+
+One footer, many extensions: build flexible Pi footers from reusable fragments with configurable layout and built-in fragments instead of competing `setFooter()` calls.
+
+`pi-footer-manager` lets one extension own `ctx.ui.setFooter(...)` while built-in and custom fragments are arranged through a shared API, with flexible rows, regions, widths, alignment, and redraw/invalidation flow.
+
+![pi-footer-manager screenshot](./assets/pi-footer-manager.png)
+
+## Included extensions
+
+- `footer-manager/index.ts` — cooperative footer owner
+- `fragments/footer-timer-fragment.ts` — example fragment showing elapsed work time
+- `fragments/quota-footer-fragment.ts` — richer quota usage display for supported providers
+- `fragments/quota-footer-fragment-text.ts` — text-focused quota usage display
+- `fragments/context-gauge-text-fragment.ts` — text version of context usage
+
+## How configuration works
+
+Layout is configured under `footerManager.layout` in Pi settings.
+
+- `separator` controls how fragments are joined inside a region
+- `rows` is an array of footer rows
+- each row has `regions`
+- each region can set:
+  - `width`: fraction like `0.35` or `"auto"`
+  - `align`: `"left"`, `"center"`, or `"right"`
+  - `fragments`: fragment ids to render in that region
+
+Project settings override global settings.
+
+## Example: simple two-region footer
+
+```json
+{
+  "footerManager": {
+    "layout": {
+      "separator": " > ",
+      "rows": [
+        {
+          "regions": [
+            { "width": 0.65, "align": "left", "fragments": ["cwd.full", "git.branch", "context.gauge"] },
+            { "width": 0.35, "align": "right", "fragments": ["model.name", "thinking.level", "statuses"] }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+## Example: mostly automatic sizing
+
+```json
+{
+  "footerManager": {
+    "layout": {
+      "rows": [
+        {
+          "regions": [
+            { "align": "left", "fragments": ["cwd.full", "git.branch"] },
+            { "width": 0.35, "align": "right", "fragments": ["model.name", "statuses"] }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+In mixed layouts, fixed fractional regions are allocated first and the remaining width goes to `"auto"` regions.
+
+## Example: multi-row footer
+
+```json
+{
+  "footerManager": {
+    "layout": {
+      "rows": [
+        {
+          "regions": [
+            { "align": "left", "fragments": ["cwd.full", "git.branch"] },
+            { "align": "right", "fragments": ["model.name", "thinking.level"] }
+          ]
+        },
+        {
+          "regions": [
+            { "align": "left", "fragments": ["context.gauge.text", "quota.current.text", "timer.work"] }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+## Widths and overflow
+
+Think of each row as a fixed-width bar split into regions:
+
+```text
+[ left region                              ][       right region ]
+```
+
+For this layout:
+
+```json
+{
+  "regions": [
+    { "align": "left", "fragments": ["cwd.full", "git.branch"] },
+    { "width": 0.35, "align": "right", "fragments": ["model.name", "statuses"] }
+  ]
+}
+```
+
+The row behaves roughly like this:
+
+```text
+[ cwd.full > git.branch                    ][ model.name > statuses ]
+```
+
+Rules of thumb:
+
+- fixed fractional regions get their width first
+- `"auto"` regions get the remaining space
+- if content does not fit, fragments are dropped before the final visible fragment is truncated
+- left- and center-aligned regions drop fragments from the right
+- right-aligned regions drop fragments from the left
+
+Multi-row layouts behave like stacked bars:
+
+```text
+row 1: [ cwd.full > git.branch           ][ model.name > statuses ]
+row 2: [ context.gauge.text > timer.work                         ]
+```
+
+## Built-in fragments
+
+Main built-ins provided by `footer-manager` include:
+
+- `cwd.full` — full path of the current working directory
+- `git.branch` — current Git branch for the active working tree
+- `model.name` — active model name
+- `model.cost` — input/output token pricing for the active model
+- `model.cacheCost` — cached token read/write pricing for the active model
+- `cache.hit` — cache hit rate summary
+- `cache.hit_counts` — cache hit rate with read/write token counts
+- `thinking.level` — current reasoning/thinking level
+- `context.gauge` — graphical context usage indicator
+- `cost.total` — total accumulated session cost
+- `statuses` — status items contributed through Pi status APIs
+
+The included fragment extensions add examples like:
+
+- `timer.work` — elapsed time for the current agent run
+- `context.gauge.text` — text version of context usage
+- `quota.current` — quota usage summary for supported providers
+- `quota.current.text` — text-focused quota usage summary
+
+## Custom fragments
+
+Other extensions should register fragments instead of calling `ctx.ui.setFooter(...)` directly.
+
+See detailed fragment API docs and examples in:
+
+- [`footer-manager/README.md`](./footer-manager/README.md)
+
+## Check
+
+```bash
+npm run check
+```
+
+## Publish dry run
+
+```bash
+npm run release:check
+```

package/footer-manager/README.md

@@ -0,0 +1,125 @@
+# footer-manager
+
+`footer-manager` is the cooperative owner of Pi footer rendering.
+
+It calls `ctx.ui.setFooter(...)` once, while other extensions contribute footer fragments through a shared registration API instead of competing to replace the whole footer. Pi cannot enforce this yet, so disable conflicting extensions that also call `ctx.ui.setFooter(...)` directly.
+
+## Register a fragment
+
+```ts
+import {
+  FOOTER_MANAGER_REGISTER_FRAGMENT,
+  type FooterFragmentRegistration,
+} from "./footer-manager/types";
+
+export default function (pi) {
+  pi.on("session_start", async () => {
+    const fragment: FooterFragmentRegistration = {
+      id: "my-extension.timer",
+      label: "Timer",
+      component: (env) => ({
+        render() {
+          return env.theme.fg("accent", "12m");
+        },
+        dispose() {},
+      }),
+    };
+    pi.events.emit(FOOTER_MANAGER_REGISTER_FRAGMENT, fragment);
+  });
+}
+```
+
+Fragment factories and `render()` are synchronous. Do async work inside the fragment, cache state locally, then call `env.invalidate()` when the rendered output should refresh. Use `env.separator` when a fragment needs to join multiple internal values with the current layout separator.
+
+## Invalidate / redraw
+
+```ts
+env.invalidate();
+// or
+pi.events.emit("footer-manager:invalidate", { id: "my-extension.timer" });
+```
+
+Invalidations are coalesced and the manager owns `tui.requestRender()`.
+
+## Layout configuration
+
+Settings live under `footerManager.layout`.
+
+- `separator` controls how fragments are joined inside a region
+- `rows` is an array of footer rows
+- each row has `regions`
+- each region can set:
+  - `width`: a fraction like `0.35` or `"auto"`
+  - `align`: `"left"`, `"center"`, or `"right"`
+  - `fragments`: fragment ids to render in that region
+
+Example:
+
+```json
+{
+  "footerManager": {
+    "layout": {
+      "separator": " > ",
+      "rows": [
+        {
+          "regions": [
+            { "width": 0.65, "align": "left", "fragments": ["cwd.full", "git.branch", "context.gauge"] },
+            { "width": 0.35, "align": "right", "fragments": ["model.name", "thinking.level", "statuses"] }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Project settings override global settings. If project `footerManager` exists but is invalid, the default layout is used; global `footerManager` is not merged as fallback.
+
+## Widths and overflow
+
+Widths are optional and default to `"auto"`.
+
+- fractional regions get their width first
+- `"auto"` regions get the remaining width
+- if content does not fit, fragments are dropped before the last visible fragment is truncated
+- left- and center-aligned regions drop fragments from the right
+- right-aligned regions drop fragments from the left
+
+Mixed example:
+
+```json
+{
+  "regions": [
+    { "align": "left", "fragments": ["cwd.full", "git.branch"] },
+    { "width": 0.35, "align": "right", "fragments": ["model.name", "statuses"] }
+  ]
+}
+```
+
+This behaves roughly like:
+
+```text
+[ cwd.full > git.branch                    ][ model.name > statuses ]
+```
+
+For rows without auto regions, widths should sum to `1`. Positive non-`1` sums are normalized with a warning. Invalid rows, invalid regions, or zero-width fully fixed rows fall back to the built-in default layout.
+
+## Built-in fragments
+
+- `cwd.full` — full path of the current working directory
+- `git.branch` — current Git branch for the active working tree
+- `model.name` — active model name
+- `model.cost` — input/output token pricing for the active model
+- `model.cacheCost` — cached token read/write pricing for the active model
+- `cache.hit` — cache hit rate summary
+- `cache.hit_counts` — cache hit rate with read/write token counts
+- `thinking.level` — current reasoning/thinking level
+- `context.gauge` — graphical context usage indicator
+- `cost.total` — total accumulated session cost
+- `statuses` — status items contributed through Pi status APIs
+
+`statuses` preserves compatibility with extensions using `ctx.ui.setStatus(...)` by joining status values in insertion order with the layout separator.
+
+## Example extension
+
+`../fragments/footer-timer-fragment.ts` registers `timer.work` through the event bus and demonstrates cached state plus `env.invalidate()`. Add `"timer.work"` to a layout region to show it.

package/footer-manager/built-ins.ts

@@ -0,0 +1,144 @@
+import { buildSessionContext, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import type { FooterFragmentRegistration, FooterRenderEnv } from "./types.js";
+
+export type BuiltInFragmentsOptions = {
+  getSeparator: () => string;
+};
+
+function formatTokens(tokens: number): string {
+  if (!Number.isFinite(tokens) || tokens <= 0) return "0";
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}k`;
+  return `${Math.round(tokens)}`;
+}
+
+function formatCost(cost: number): string {
+  if (!Number.isFinite(cost) || cost <= 0) return "$0.000";
+  if (cost < 0.01) return `$${cost.toFixed(4)}`;
+  if (cost < 1) return `$${cost.toFixed(3)}`;
+  return `$${cost.toFixed(2)}`;
+}
+
+function formatModelRate(rate: unknown): string {
+  const value = Number(rate) || 0;
+  if (value === 0) return "0";
+  if (Math.abs(value) < 0.01) return value.toFixed(4).replace(/0+$/, "").replace(/\.$/, "");
+  return value.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function collapseHome(cwd: string): string {
+  const home = homedir();
+  return home && (cwd === home || cwd.startsWith(home + "/")) ? `~${cwd.slice(home.length)}` : cwd;
+}
+
+function compactModel(ctx: ExtensionContext): string {
+  const model = ctx.model;
+  const id = typeof model?.id === "string" ? model.id : "no-model";
+  const provider = typeof model?.provider === "string" ? model.provider : undefined;
+  const base = id.split("/").filter(Boolean).pop() || id;
+  if (!provider) return base;
+  return id.toLowerCase().includes(provider.toLowerCase()) ? base : `${provider}/${base}`;
+}
+
+function renderModelCost(ctx: ExtensionContext): string {
+  const cost = ctx.model?.cost;
+  if (!cost) return "";
+  return `↑$${formatModelRate(cost.input)} ↓$${formatModelRate(cost.output)}`;
+}
+
+function renderModelCacheCost(ctx: ExtensionContext): string {
+  const cost = ctx.model?.cost;
+  if (!cost) return "";
+  const read = Number(cost.cacheRead) || 0;
+  const write = Number(cost.cacheWrite) || 0;
+  if (read === 0 && write === 0) return "";
+  return `R${formatModelRate(read)} W${formatModelRate(write)}`;
+}
+
+function getBranchAssistantUsage(ctx: ExtensionContext): { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number } {
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  try {
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if ((entry as any).type !== "message") continue;
+      const message = (entry as any).message;
+      if (message?.role !== "assistant") continue;
+      const usage = message.usage;
+      totals.input += Number(usage?.input) || 0;
+      totals.output += Number(usage?.output) || 0;
+      totals.cacheRead += Number(usage?.cacheRead) || 0;
+      totals.cacheWrite += Number(usage?.cacheWrite) || 0;
+      totals.cost += Number(usage?.cost?.total) || 0;
+    }
+  } catch {}
+  return totals;
+}
+
+function getCacheHit(ctx: ExtensionContext): { hitPercent: number; cacheRead: number; cacheWrite: number } | undefined {
+  const { input, cacheRead, cacheWrite } = getBranchAssistantUsage(ctx);
+  if (cacheRead === 0 && cacheWrite === 0) return undefined;
+  const denominator = input + cacheRead;
+  const hitPercent = denominator > 0 ? Math.round((cacheRead / denominator) * 100) : 0;
+  return { hitPercent, cacheRead, cacheWrite };
+}
+
+function renderCacheHit(ctx: ExtensionContext): string {
+  const cache = getCacheHit(ctx);
+  return cache ? `cache ${cache.hitPercent}%` : "";
+}
+
+function renderCacheHitCounts(ctx: ExtensionContext): string {
+  const cache = getCacheHit(ctx);
+  return cache ? `cache ${cache.hitPercent}% R${formatTokens(cache.cacheRead)}/W${formatTokens(cache.cacheWrite)}` : "";
+}
+
+function getThinkingLevel(ctx: ExtensionContext): string {
+  try {
+    const context = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
+    return context.thinkingLevel || "off";
+  } catch {
+    return "off";
+  }
+}
+
+function getContextInfo(ctx: ExtensionContext): { percentage: number; used?: number; total?: number } {
+  try {
+    const contextWindow = Number(ctx.model?.contextWindow) || 0;
+    if (contextWindow <= 0) return { percentage: 0 };
+    const context = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
+    const lastAssistant = [...context.messages].reverse().find((m: any) => m.role === "assistant" && m.stopReason !== "aborted") as any;
+    const usage = lastAssistant?.usage;
+    if (!usage) return { percentage: 0, used: 0, total: contextWindow };
+    const used = (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+    return { percentage: (used / contextWindow) * 100, used, total: contextWindow };
+  } catch {
+    return { percentage: 0 };
+  }
+}
+
+function renderContextGauge(ctx: ExtensionContext, theme: Theme): string {
+  const { percentage, used, total } = getContextInfo(ctx);
+  const width = 8;
+  const clamped = Math.max(0, Math.min(100, percentage));
+  const filled = Math.round((clamped / 100) * width);
+  const color = clamped >= 90 ? "error" : clamped >= 70 ? "warning" : clamped >= 50 ? "accent" : "success";
+  const bar = theme.fg(color, "━".repeat(filled)) + theme.fg("dim", "─".repeat(width - filled));
+  const counts = used !== undefined && total ? ` ${formatTokens(used)}/${formatTokens(total)}` : "";
+  return `${theme.fg("dim", "ctx ")}${bar} ${theme.fg("dim", `${Math.round(clamped)}%${counts}`)}`;
+}
+
+export function createBuiltInFragments(options: BuiltInFragmentsOptions): FooterFragmentRegistration[] {
+  return [
+    { id: "cwd.full", label: "CWD", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("accent", collapseHome(ctx.cwd || process.cwd())) }) },
+    { id: "git.branch", label: "Git branch", component: ({ footerData, theme }: FooterRenderEnv) => ({ render: () => { const branch = footerData.getGitBranch(); return branch ? theme.fg("success", branch) : ""; } }) },
+    { id: "model.name", label: "Model", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("muted", compactModel(ctx)) }) },
+    { id: "model.cost", label: "Model cost", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("dim", renderModelCost(ctx)) }) },
+    { id: "model.cacheCost", label: "Model cache cost", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("dim", renderModelCacheCost(ctx)) }) },
+    { id: "cache.hit", label: "Cache hit", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("dim", renderCacheHit(ctx)) }) },
+    { id: "cache.hit_counts", label: "Cache hit with counts", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("dim", renderCacheHitCounts(ctx)) }) },
+    { id: "thinking.level", label: "Thinking", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("accent", getThinkingLevel(ctx)) }) },
+    { id: "context.gauge", label: "Context", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => renderContextGauge(ctx, theme) }) },
+    { id: "cost.total", label: "Total cost", component: ({ ctx, theme }: FooterRenderEnv) => ({ render: () => theme.fg("dim", formatCost(getBranchAssistantUsage(ctx).cost)) }) },
+    { id: "statuses", label: "Statuses", component: ({ footerData, theme }: FooterRenderEnv) => ({ render: () => Array.from(footerData.getExtensionStatuses().values()).filter(Boolean).join(theme.fg("dim", options.getSeparator())) }) },
+  ];
+}