@sentiolabs/pi-scriptable-statusline 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial package skeleton for `@sentiolabs/pi-scriptable-statusline`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentio Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# `@sentiolabs/pi-scriptable-statusline`
+
+Scriptable footer and statusline UI package for Pi.
+
+## What it does
+
+`@sentiolabs/pi-scriptable-statusline` owns Pi's footer with `ctx.ui.setFooter()` and can render scriptable widgets above or below the editor with `ctx.ui.setWidget()`.
+
+This package is for users who want to customize the whole footer/statusline experience with code instead of selecting from fixed presets.
+
+> **Footer ownership:** this package replaces Pi's footer. Disable other footer replacement packages such as `pi-powerline-footer` when using it. Status entries from non-footer extensions are still available through `input.extensionStatuses`.
+
+## Installation
+
+```bash
+pi install npm:@sentiolabs/pi-scriptable-statusline
+```
+
+For local development from this monorepo:
+
+```bash
+pi -e ./packages/pi-scriptable-statusline
+```
+
+## Quick start
+
+```text
+/statusline init
+/statusline doctor
+```
+
+Edit:
+
+```text
+~/.pi/agent/scriptable-statusline/render.ts
+```
+
+## Renderer API
+
+```typescript
+import type { StatuslineRenderer } from "@sentiolabs/pi-scriptable-statusline";
+
+const render: StatuslineRenderer = async (input) => ({
+  footer: [
+    `${input.model.label} · ${input.repo.name} · ${input.git.branch ?? "no-git"}`,
+    `ctx ${input.context.percent ?? "?"}% · ${input.tokens.totalLabel} · ${input.cost.totalLabel}`,
+  ],
+  widgets: {
+    belowEditor: input.extensionStatuses.length
+      ? [`statuses: ${input.extensionStatuses.map((status) => status.text).join(" · ")}`]
+      : [],
+  },
+});
+
+export default render;
+```
+
+## Commands
+
+- `/statusline init` creates the global renderer if missing.
+- `/statusline reload` clears the renderer cache and rerenders.
+- `/statusline doctor` prints renderer diagnostics.
+- `/statusline disable` clears footer/widgets for the current session.
+- `/statusline enable` re-registers footer/widgets for the current session.
+
+## Natural-language setup
+
+Use `/statusline <request>` to delegate your layout request to the `statusline-setup` workflow.
+
+Example request:
+
+```text
+/statusline show context on the first footer line, daily and weekly limits on the second line, and model/repo/branch below the editor.
+```
+
+## Development
+
+```bash
+npm test --workspace @sentiolabs/pi-scriptable-statusline
+npm run pack:dry-run --workspace @sentiolabs/pi-scriptable-statusline
+```

package/extensions/render-cache.ts

@@ -0,0 +1,111 @@
+import type { StatuslineSurface } from "../index.d.ts";
+import { normalizeRenderResult, type NormalizedStatuslineRenderResult } from "./render-result.ts";
+
+export interface RenderCacheOptions {
+  loadRenderer: () => Promise<any>;
+  buildInput: (surface: StatuslineSurface, width: number, context?: unknown) => any;
+  requestRender: () => void;
+  fallbackLines?: (surface: StatuslineSurface) => string[];
+}
+
+interface RenderCacheEntry {
+  lines: string[];
+  stale: boolean;
+  generation: number;
+  pending?: Promise<void>;
+  lastError?: Error;
+  lastRenderTime?: number;
+}
+
+function cacheKey(surface: StatuslineSurface, width: number): string {
+  return `${surface}:${width}`;
+}
+
+function errorValue(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function linesForSurface(result: NormalizedStatuslineRenderResult, surface: StatuslineSurface): string[] {
+  if (surface === "footer") return result.footer;
+  if (surface === "aboveEditor") return result.widgets.aboveEditor;
+  return result.widgets.belowEditor;
+}
+
+export function createRenderCache(options: RenderCacheOptions) {
+  const entries = new Map<string, RenderCacheEntry>();
+  let generation = 0;
+  let lastError: Error | undefined;
+  let lastRenderTime: number | undefined;
+
+  function fallback(surface: StatuslineSurface): string[] {
+    return [...(options.fallbackLines?.(surface) ?? [])];
+  }
+
+  function refresh(key: string, entry: RenderCacheEntry, surface: StatuslineSurface, width: number, context?: unknown) {
+    if (entry.pending) return;
+
+    const refreshGeneration = generation;
+    entry.pending = Promise.resolve()
+      .then(async () => {
+        const renderer = await options.loadRenderer();
+        const input = options.buildInput(surface, width, context);
+        const result = await renderer(input);
+        const normalized = normalizeRenderResult(result, surface);
+        const renderedLines = linesForSurface(normalized, surface);
+
+        if (refreshGeneration !== generation) {
+          entry.stale = true;
+          return;
+        }
+
+        entry.lines = [...renderedLines];
+        entry.stale = false;
+        entry.generation = refreshGeneration;
+        entry.lastError = undefined;
+        entry.lastRenderTime = Date.now();
+        lastError = undefined;
+        lastRenderTime = entry.lastRenderTime;
+        entries.set(key, entry);
+      })
+      .catch((error) => {
+        const normalizedError = errorValue(error);
+        entry.lastError = normalizedError;
+        entry.stale = refreshGeneration !== generation;
+        lastError = normalizedError;
+      })
+      .finally(() => {
+        entry.pending = undefined;
+        options.requestRender();
+      });
+  }
+
+  return {
+    render(surface: StatuslineSurface, width: number, context?: unknown): string[] {
+      const key = cacheKey(surface, width);
+      let entry = entries.get(key);
+
+      if (!entry) {
+        entry = { lines: fallback(surface), stale: true, generation };
+        entries.set(key, entry);
+      }
+
+      if (entry.stale) {
+        refresh(key, entry, surface, width, context);
+      }
+
+      return [...entry.lines];
+    },
+    invalidate() {
+      generation += 1;
+      for (const entry of entries.values()) {
+        entry.stale = true;
+      }
+    },
+    getLastError(): Error | undefined {
+      return lastError;
+    },
+    getLastRenderTime(): number | undefined {
+      return lastRenderTime;
+    },
+  };
+}

package/extensions/render-result.ts

@@ -0,0 +1,67 @@
+import type { StatuslineRenderResult, StatuslineRendererResult, StatuslineSurface } from "../index.d.ts";
+
+export interface NormalizedStatuslineRenderResult {
+  footer: string[];
+  widgets: {
+    aboveEditor: string[];
+    belowEditor: string[];
+  };
+  status?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeLines(value: unknown, path: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${path} must be an array of strings`);
+  }
+  return value.map((line, index) => {
+    if (typeof line !== "string") {
+      throw new Error(`${path}[${index}] must be a string`);
+    }
+    return line;
+  });
+}
+
+export function normalizeRenderResult(
+  result: StatuslineRendererResult,
+  surface: StatuslineSurface,
+): NormalizedStatuslineRenderResult {
+  if (Array.isArray(result)) {
+    const lines = normalizeLines(result, "result");
+    return {
+      footer: surface === "footer" ? lines : [],
+      widgets: {
+        aboveEditor: surface === "aboveEditor" ? lines : [],
+        belowEditor: surface === "belowEditor" ? lines : [],
+      },
+    };
+  }
+
+  if (!isRecord(result)) {
+    throw new Error("Renderer must return an array of strings or an object");
+  }
+
+  const widgets = isRecord(result.widgets) ? result.widgets : {};
+  const normalized: NormalizedStatuslineRenderResult = {
+    footer: normalizeLines(result.footer, "result.footer"),
+    widgets: {
+      aboveEditor: normalizeLines(widgets.aboveEditor, "result.widgets.aboveEditor"),
+      belowEditor: normalizeLines(widgets.belowEditor, "result.widgets.belowEditor"),
+    },
+  };
+
+  if (result.status !== undefined) {
+    if (typeof result.status !== "string") {
+      throw new Error("result.status must be a string when provided");
+    }
+    normalized.status = result.status;
+  }
+
+  return normalized;
+}
+
+export type { StatuslineRenderResult, StatuslineRendererResult, StatuslineSurface };

package/extensions/renderer-loader.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+import type { StatuslineRenderer } from "../index.d.ts";
+
+export type ImportModule = (specifier: string) => Promise<{ default?: unknown }>;
+
+export interface RendererLoaderOptions {
+  rendererPath?: string;
+  homeDir?: string;
+  importModule?: ImportModule;
+  now?: () => number;
+}
+
+export function defaultRendererPath(homeDir = homedir()): string {
+  return `${homeDir}/.pi/agent/scriptable-statusline/render.ts`;
+}
+
+export function createRendererLoader(options: RendererLoaderOptions = {}) {
+  const rendererPath = options.rendererPath ?? defaultRendererPath(options.homeDir);
+  const importModule = options.importModule ?? ((specifier) => import(specifier));
+  const now = options.now ?? Date.now;
+  let version = `${now()}-0`;
+  let invalidations = 0;
+  let cached: Promise<StatuslineRenderer> | undefined;
+
+  return {
+    rendererPath,
+    invalidate() {
+      invalidations += 1;
+      version = `${now()}-${invalidations}`;
+      cached = undefined;
+    },
+    async load(): Promise<StatuslineRenderer> {
+      if (!existsSync(rendererPath)) {
+        throw new Error(`Renderer file not found: ${rendererPath}`);
+      }
+
+      cached ??= importModule(`${pathToFileURL(rendererPath).href}?v=${version}`).then((module) => {
+        if (typeof module.default !== "function") {
+          throw new Error("Statusline renderer default export must be a function");
+        }
+        return module.default as StatuslineRenderer;
+      });
+
+      return cached;
+    },
+  };
+}

package/extensions/snapshot.ts

@@ -0,0 +1,196 @@
+import { basename } from "node:path";
+import { visibleWidth, truncateToWidth } from "@mariozechner/pi-tui";
+import type { StatuslineRenderInput, StatuslineSurface } from "../index.d.ts";
+
+export interface SnapshotOptions {
+  surface: StatuslineSurface;
+  width: number;
+  ctx: any;
+  footerData?: { getGitBranch?: () => string | null; getExtensionStatuses?: () => ReadonlyMap<string, string> };
+  turn: number;
+  repoRoot?: string | null;
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function callOptional<T>(fn: unknown): T | undefined {
+  if (typeof fn !== "function") return undefined;
+  try {
+    return fn() as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function recordNumber(record: unknown, keys: string[]): number | undefined {
+  if (!isRecord(record)) return undefined;
+  for (const key of keys) {
+    const value = numberValue(record[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function recordString(record: unknown, keys: string[]): string | undefined {
+  if (!isRecord(record)) return undefined;
+  for (const key of keys) {
+    const value = stringValue(record[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+export function formatCount(value: number): string {
+  if (value < 1000) return String(value);
+  if (value < 1_000_000) return `${(value / 1000).toFixed(value < 10_000 ? 1 : 0)}k`;
+  return `${(value / 1_000_000).toFixed(value < 10_000_000 ? 1 : 0)}M`;
+}
+
+function formatCost(value: number): string {
+  return `$${value.toFixed(3)}`;
+}
+
+function modelSnapshot(ctx: any) {
+  const model = ctx?.model;
+  if (typeof model === "string") {
+    return { provider: null, id: model, label: model };
+  }
+
+  const provider = recordString(model, ["provider", "providerId"]);
+  const id = recordString(model, ["id", "model", "modelId", "name"]);
+  const label = recordString(model, ["label", "displayName", "name", "id", "model", "modelId"]) ?? "unknown";
+  return { provider: provider ?? null, id: id ?? null, label };
+}
+
+function contextSnapshot(ctx: any) {
+  const usage = callOptional<unknown>(ctx?.getContextUsage?.bind?.(ctx)) ?? ctx?.contextUsage;
+  const tokens = recordNumber(usage, ["tokens", "used", "current"]) ?? 0;
+  const window = recordNumber(usage, ["window", "contextWindow", "limit", "max"]) ?? 0;
+  const explicitPercent = recordNumber(usage, ["percent", "percentage"]);
+  const percent = explicitPercent ?? (window > 0 ? Math.round((tokens / window) * 100) : null);
+
+  return { tokens, window, percent };
+}
+
+function aggregateUsageFromSession(ctx: any): { input: number; output: number; cost: number } | null {
+  const entries = callOptional<unknown>(ctx?.sessionManager?.getBranch?.bind?.(ctx?.sessionManager));
+  if (!Array.isArray(entries)) return null;
+
+  let input = 0;
+  let output = 0;
+  let cost = 0;
+  let found = false;
+
+  for (const entry of entries) {
+    if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message) || entry.message.role !== "assistant") {
+      continue;
+    }
+
+    const usage = isRecord(entry.message.usage) ? entry.message.usage : {};
+    input += recordNumber(usage, ["input", "inputTokens", "prompt", "promptTokens"]) ?? 0;
+    output += recordNumber(usage, ["output", "outputTokens", "completion", "completionTokens"]) ?? 0;
+    cost += recordNumber(usage.cost, ["total", "totalUsd", "usd"]) ?? 0;
+    found = true;
+  }
+
+  return found ? { input, output, cost } : null;
+}
+
+function tokenSnapshot(ctx: any) {
+  const fromSession = aggregateUsageFromSession(ctx);
+  if (fromSession) {
+    const total = fromSession.input + fromSession.output;
+    return { input: fromSession.input, output: fromSession.output, total, totalLabel: formatCount(total) };
+  }
+
+  const source = ctx?.tokens ?? ctx?.tokenUsage ?? ctx?.usage;
+  const input = recordNumber(source, ["input", "inputTokens", "prompt", "promptTokens"]) ?? 0;
+  const output = recordNumber(source, ["output", "outputTokens", "completion", "completionTokens"]) ?? 0;
+  const total = recordNumber(source, ["total", "totalTokens"]) ?? input + output;
+
+  return { input, output, total, totalLabel: formatCount(total) };
+}
+
+function costSnapshot(ctx: any) {
+  const fromSession = aggregateUsageFromSession(ctx);
+  if (fromSession) {
+    return { total: fromSession.cost, totalLabel: formatCost(fromSession.cost) };
+  }
+
+  const source = ctx?.cost ?? ctx?.costs;
+  const total = recordNumber(source, ["total", "totalUsd", "usd"]) ?? 0;
+  const totalLabel = recordString(source, ["totalLabel", "label"]) ?? formatCost(total);
+
+  return { total, totalLabel };
+}
+
+function extensionStatuses(footerData: SnapshotOptions["footerData"]) {
+  const statuses = callOptional<ReadonlyMap<string, string>>(footerData?.getExtensionStatuses?.bind?.(footerData));
+  if (!statuses) return [];
+
+  return Array.from(statuses.entries()).map(([key, text]) => ({ key, text }));
+}
+
+function sessionId(ctx: any): string | null {
+  return (
+    stringValue(ctx?.sessionId) ??
+    recordString(ctx?.session, ["id"]) ??
+    callOptional<string>(ctx?.sessionManager?.getSessionFile?.bind?.(ctx?.sessionManager)) ??
+    null
+  );
+}
+
+export function buildStatuslineSnapshot(options: SnapshotOptions): StatuslineRenderInput {
+  const ctx = options.ctx ?? {};
+  const cwd = stringValue(ctx.cwd) ?? process.cwd();
+  const repoRoot = options.repoRoot ?? null;
+  const repoName = basename(repoRoot ?? cwd) || basename(cwd) || cwd;
+  const footerBranch = callOptional<string | null>(options.footerData?.getGitBranch?.bind?.(options.footerData));
+  const themeSource = ctx.theme ?? ctx.ui?.theme;
+
+  return {
+    surface: options.surface,
+    width: options.width,
+    cwd,
+    model: modelSnapshot(ctx),
+    repo: { name: repoName, root: repoRoot },
+    git: { branch: footerBranch ?? null },
+    context: contextSnapshot(ctx),
+    tokens: tokenSnapshot(ctx),
+    cost: costSnapshot(ctx),
+    limits: { daily: null, weekly: null, source: null },
+    extensionStatuses: extensionStatuses(options.footerData),
+    session: { id: sessionId(ctx), turn: options.turn },
+    theme: {
+      fg: (color: string, text: string) => {
+        if (typeof themeSource?.fg === "function") return themeSource.fg(color, text);
+        return text;
+      },
+      bg: (color: string, text: string) => {
+        if (typeof themeSource?.bg === "function") return themeSource.bg(color, text);
+        return text;
+      },
+    },
+    utils: {
+      visibleWidth,
+      truncate: truncateToWidth,
+    },
+  };
+}

package/extensions/statusline.ts

@@ -0,0 +1,388 @@
+import { copyFileSync, existsSync, mkdirSync, watch } from "node:fs";
+import { dirname } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { createRenderCache } from "./render-cache.ts";
+import { createRendererLoader, defaultRendererPath } from "./renderer-loader.ts";
+import { buildStatuslineSnapshot } from "./snapshot.ts";
+
+const ABOVE_WIDGET_KEY = "scriptable-statusline-above";
+const BELOW_WIDGET_KEY = "scriptable-statusline-below";
+
+const DEFAULT_TEMPLATE = new URL("../templates/default-render.ts", import.meta.url);
+
+type FooterDataLike = {
+  getGitBranch?: () => string | null;
+  getExtensionStatuses?: () => ReadonlyMap<string, string>;
+  onBranchChange?: (callback: () => void) => (() => void) | void;
+};
+
+type TuiLike = { requestRender?: () => void };
+
+interface StatuslineCommandRuntime {
+  rendererPath?: string;
+  templatePath?: string | URL;
+  loader?: { rendererPath?: string; invalidate: () => void };
+  cache?: { invalidate: () => void; getLastError?: () => Error | undefined; getLastRenderTime?: () => number | undefined };
+  enable?: (ctx: ExtensionContext) => void;
+  disable?: (ctx: ExtensionContext) => void;
+  requestRender?: () => void;
+  isEnabled?: () => boolean;
+  onInit?: () => void;
+}
+
+interface StatuslineControllerOptions {
+  cache: {
+    render: (surface: "footer" | "aboveEditor" | "belowEditor", width: number, context?: unknown) => string[];
+    invalidate?: () => void;
+  };
+  onEnable?: (ctx: ExtensionContext) => void;
+  setFooterDataContext: (context: { footerData?: FooterDataLike } | undefined) => void;
+  getFooterDataContext: () => { footerData?: FooterDataLike } | undefined;
+  requestRender: () => void;
+  registerTui: (tui: TuiLike | undefined) => void;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function numericWidth(value: unknown, fallback = 80): number {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+  }
+  if (isRecord(value)) {
+    const width = numericWidth(value.width, 0);
+    if (width > 0) return width;
+    const columns = numericWidth(value.columns, 0);
+    if (columns > 0) return columns;
+  }
+  return fallback;
+}
+
+function isFooterData(value: unknown): value is FooterDataLike {
+  return isRecord(value) && (typeof value.getGitBranch === "function" || typeof value.getExtensionStatuses === "function");
+}
+
+function footerContext(first: unknown, second: unknown): { footerData?: FooterDataLike } | undefined {
+  if (isFooterData(second)) return { footerData: second };
+  if (isFooterData(first)) return { footerData: first };
+  if (isRecord(first) && isFooterData(first.footerData)) return { footerData: first.footerData };
+  if (isRecord(second) && isFooterData(second.footerData)) return { footerData: second.footerData };
+  return undefined;
+}
+
+function renderWidth(first: unknown, second?: unknown): number {
+  const firstWidth = numericWidth(first, 0);
+  if (firstWidth > 0) return firstWidth;
+  const secondWidth = numericWidth(second, 0);
+  if (secondWidth > 0) return secondWidth;
+  return 80;
+}
+
+function notify(ctx: ExtensionContext | undefined, message: string, level: "info" | "warning" | "error" = "info") {
+  if (!ctx || ctx.hasUI === false) return;
+  ctx.ui.notify(message, level);
+}
+
+function commandAction(args: string): string {
+  return args.trim().split(/\s+/, 1)[0]?.toLowerCase() || "doctor";
+}
+
+function isOperationalStatuslineCommand(args: string): boolean {
+  const action = commandAction(args);
+  return action === "init" || action === "reload" || action === "doctor" || action === "disable" || action === "enable";
+}
+
+function delegationMessage(request: string): string {
+  return `Use the statusline-setup skill to configure @sentiolabs/pi-scriptable-statusline for this request: ${request}`;
+}
+
+function clearStatuslineUi(ctx: ExtensionContext | undefined) {
+  if (!ctx) return;
+  ctx.ui.setFooter(undefined);
+  ctx.ui.setWidget(ABOVE_WIDGET_KEY, undefined);
+  ctx.ui.setWidget(BELOW_WIDGET_KEY, undefined);
+}
+
+function initializeRenderer(rendererPath: string, templatePath: string | URL = DEFAULT_TEMPLATE): string {
+  if (existsSync(rendererPath)) return `Statusline renderer already exists: ${rendererPath}`;
+
+  mkdirSync(dirname(rendererPath), { recursive: true });
+  copyFileSync(templatePath, rendererPath);
+  return `Created statusline renderer: ${rendererPath}`;
+}
+
+export function runStatuslineCommand(args: string, ctx: ExtensionContext, runtime: StatuslineCommandRuntime = {}): string {
+  const action = commandAction(args);
+  const rendererPath = runtime.rendererPath ?? runtime.loader?.rendererPath ?? defaultRendererPath();
+
+  if (action === "init") {
+    const message = initializeRenderer(rendererPath, runtime.templatePath);
+    runtime.loader?.invalidate();
+    runtime.cache?.invalidate();
+    runtime.requestRender?.();
+    runtime.onInit?.();
+    return message;
+  }
+
+  if (action === "reload") {
+    runtime.loader?.invalidate();
+    runtime.cache?.invalidate();
+    runtime.requestRender?.();
+    return "Statusline renderer reloaded.";
+  }
+
+  if (action === "disable") {
+    if (runtime.disable) runtime.disable(ctx);
+    else clearStatuslineUi(ctx);
+    return "Statusline disabled.";
+  }
+
+  if (action === "enable") {
+    runtime.enable?.(ctx);
+    runtime.requestRender?.();
+    return "Statusline enabled.";
+  }
+
+  if (action === "doctor") {
+    const lastError = runtime.cache?.getLastError?.();
+    const lastRenderTime = runtime.cache?.getLastRenderTime?.();
+    return [
+      "Statusline doctor",
+      `enabled: ${runtime.isEnabled?.() ?? true}`,
+      `renderer: ${rendererPath}`,
+      `rendererExists: ${existsSync(rendererPath)}`,
+      `lastRenderTime: ${lastRenderTime === undefined ? "never" : new Date(lastRenderTime).toISOString()}`,
+      `lastError: ${lastError?.message ?? "none"}`,
+    ].join("\n");
+  }
+
+  return "Usage: /statusline init|reload|doctor|disable|enable";
+}
+
+function statusSignature(footerData?: FooterDataLike): string {
+  if (!footerData) return "none";
+  const branch = typeof footerData.getGitBranch === "function" ? footerData.getGitBranch() ?? "" : "";
+  const statuses = typeof footerData.getExtensionStatuses === "function" ? footerData.getExtensionStatuses() : undefined;
+  const statusParts = statuses ? Array.from(statuses.entries()).map(([key, text]) => `${key}:${text}`) : [];
+  return `${branch}|${statusParts.join("|")}`;
+}
+
+function createStatuslineController(options: StatuslineControllerOptions) {
+  let footerUnsubscribe: (() => void) | undefined;
+  let footerSignature = "none";
+
+  function resetFooterSubscription() {
+    footerUnsubscribe?.();
+    footerUnsubscribe = undefined;
+  }
+
+  return {
+    enable(ctx: ExtensionContext) {
+      options.onEnable?.(ctx);
+      const ui = ctx.ui;
+
+      ui.setFooter((tui?: TuiLike, _theme?: unknown, footerData?: unknown) => {
+        options.registerTui(tui);
+        const context = footerContext(footerData, undefined);
+        options.setFooterDataContext(context);
+        const currentFooterData = context?.footerData;
+        footerSignature = statusSignature(currentFooterData);
+
+        resetFooterSubscription();
+        if (currentFooterData && typeof currentFooterData.onBranchChange === "function") {
+          const unsub = currentFooterData.onBranchChange(() => {
+            options.cache.invalidate?.();
+            options.requestRender();
+          });
+          if (typeof unsub === "function") footerUnsubscribe = unsub;
+        }
+
+        return {
+          dispose() {
+            resetFooterSubscription();
+          },
+          invalidate() {
+            options.cache.invalidate?.();
+          },
+          render(width: number) {
+            const nextSignature = statusSignature(currentFooterData);
+            if (nextSignature !== footerSignature) {
+              footerSignature = nextSignature;
+              options.cache.invalidate?.();
+            }
+            return options.cache.render("footer", renderWidth(width), context);
+          },
+        };
+      });
+      ui.setWidget(ABOVE_WIDGET_KEY, (tui?: TuiLike) => {
+        options.registerTui(tui);
+        return {
+          invalidate() {
+            options.cache.invalidate?.();
+          },
+          render(width: number) {
+            return options.cache.render("aboveEditor", renderWidth(width), options.getFooterDataContext());
+          },
+        };
+      });
+      ui.setWidget(
+        BELOW_WIDGET_KEY,
+        (tui?: TuiLike) => {
+          options.registerTui(tui);
+          return {
+            invalidate() {
+              options.cache.invalidate?.();
+            },
+            render(width: number) {
+              return options.cache.render("belowEditor", renderWidth(width), options.getFooterDataContext());
+            },
+          };
+        },
+        { placement: "belowEditor" },
+      );
+    },
+    disable(ctx: ExtensionContext) {
+      resetFooterSubscription();
+      options.setFooterDataContext(undefined);
+      clearStatuslineUi(ctx);
+    },
+  };
+}
+
+function findGitRoot(cwd: string | undefined): string | null {
+  if (!cwd) return null;
+
+  let current = cwd;
+  while (true) {
+    if (existsSync(`${current}/.git`)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export default function statuslineExtension(pi: ExtensionAPI) {
+  let enabled = true;
+  let turn = 0;
+  let currentCtx: ExtensionContext | undefined;
+  let repoRoot: string | null = null;
+  let watcher: ReturnType<typeof watch> | undefined;
+  let lastFooterContext: { footerData?: FooterDataLike } | undefined;
+  const tuiHandles = new Set<TuiLike>();
+
+  const requestRender = () => {
+    for (const tui of tuiHandles) {
+      tui.requestRender?.();
+    }
+  };
+
+  const loader = createRendererLoader();
+  const cache = createRenderCache({
+    loadRenderer: () => loader.load(),
+    buildInput: (surface, width, context) => {
+      const data = isRecord(context) ? context.footerData : undefined;
+      return buildStatuslineSnapshot({
+        surface,
+        width,
+        ctx: currentCtx ?? {},
+        footerData: isFooterData(data) ? data : undefined,
+        turn,
+        repoRoot,
+      });
+    },
+    requestRender,
+    fallbackLines: (surface) => (surface === "footer" ? ["statusline loading..."] : []),
+  });
+
+  const controller = createStatuslineController({
+    cache,
+    onEnable(ctx) {
+      currentCtx = ctx;
+      repoRoot = findGitRoot(ctx?.cwd);
+    },
+    setFooterDataContext(context) {
+      lastFooterContext = context;
+    },
+    getFooterDataContext() {
+      return lastFooterContext;
+    },
+    requestRender,
+    registerTui(tui) {
+      if (tui) tuiHandles.add(tui);
+    },
+  });
+
+  function restartWatcher() {
+    watcher?.close();
+    watcher = undefined;
+    if (!existsSync(loader.rendererPath)) return;
+
+    try {
+      watcher = watch(loader.rendererPath, { persistent: false }, () => {
+        loader.invalidate();
+        cache.invalidate();
+        requestRender();
+      });
+    } catch {
+      watcher = undefined;
+    }
+  }
+
+  pi.on("turn_start", () => {
+    turn += 1;
+    cache.invalidate();
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    currentCtx = ctx;
+    repoRoot = findGitRoot(ctx?.cwd);
+    if (enabled) controller.enable(ctx);
+    restartWatcher();
+  });
+
+  pi.registerCommand("statusline", {
+    description: "Manage the scriptable statusline renderer",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      currentCtx = ctx;
+      repoRoot = findGitRoot(ctx?.cwd);
+
+      const trimmedArgs = args.trim();
+      if (trimmedArgs.length > 0 && !isOperationalStatuslineCommand(trimmedArgs)) {
+        const deliverAs = ctx.isIdle() === false ? "followUp" : undefined;
+        pi.sendUserMessage(delegationMessage(trimmedArgs), deliverAs ? { deliverAs } : undefined);
+        notify(ctx, "Delegating to statusline-setup for your requested layout.", "info");
+        return;
+      }
+
+      const message = runStatuslineCommand(args, ctx, {
+        rendererPath: loader.rendererPath,
+        loader,
+        cache,
+        enable: (commandCtx) => {
+          enabled = true;
+          controller.enable(commandCtx);
+        },
+        disable: (commandCtx) => {
+          enabled = false;
+          controller.disable(commandCtx);
+        },
+        requestRender,
+        isEnabled: () => enabled,
+        onInit: restartWatcher,
+      });
+
+      notify(ctx, message, "info");
+    },
+  });
+
+  pi.on("session_shutdown", () => {
+    watcher?.close();
+    watcher = undefined;
+    lastFooterContext = undefined;
+    tuiHandles.clear();
+    if (currentCtx) controller.disable(currentCtx);
+  });
+}

package/index.d.ts

@@ -0,0 +1,102 @@
+export type StatuslineSurface = "footer" | "aboveEditor" | "belowEditor";
+
+export interface StatuslineTheme {
+  fg(color: string, text: string): string;
+  bg?(color: string, text: string): string;
+}
+
+export interface StatuslineUtils {
+  visibleWidth(text: string): number;
+  truncate(text: string, width: number, ellipsis?: string): string;
+}
+
+export interface StatuslineModelSnapshot {
+  provider: string | null;
+  id: string | null;
+  label: string;
+}
+
+export interface StatuslineRepoSnapshot {
+  name: string;
+  root: string | null;
+}
+
+export interface StatuslineGitSnapshot {
+  branch: string | null;
+}
+
+export interface StatuslineContextSnapshot {
+  tokens: number;
+  window: number;
+  percent: number | null;
+}
+
+export interface StatuslineTokenSnapshot {
+  input: number;
+  output: number;
+  total: number;
+  totalLabel: string;
+}
+
+export interface StatuslineCostSnapshot {
+  total: number;
+  totalLabel: string;
+}
+
+export interface StatuslineLimitWindowSnapshot {
+  used: number | null;
+  limit: number | null;
+  percent: number | null;
+  resetAt: string | null;
+  label: string;
+}
+
+export interface StatuslineLimitSnapshot {
+  daily: StatuslineLimitWindowSnapshot | null;
+  weekly: StatuslineLimitWindowSnapshot | null;
+  source: string | null;
+}
+
+export interface StatuslineExtensionStatusSnapshot {
+  key: string;
+  text: string;
+}
+
+export interface StatuslineSessionSnapshot {
+  id: string | null;
+  turn: number;
+}
+
+export interface StatuslineRenderInput {
+  surface: StatuslineSurface;
+  width: number;
+  cwd: string;
+  model: StatuslineModelSnapshot;
+  repo: StatuslineRepoSnapshot;
+  git: StatuslineGitSnapshot;
+  context: StatuslineContextSnapshot;
+  tokens: StatuslineTokenSnapshot;
+  cost: StatuslineCostSnapshot;
+  limits: StatuslineLimitSnapshot;
+  extensionStatuses: readonly StatuslineExtensionStatusSnapshot[];
+  session: StatuslineSessionSnapshot;
+  theme: StatuslineTheme;
+  utils: StatuslineUtils;
+}
+
+export interface StatuslineWidgetRenderResult {
+  aboveEditor?: readonly string[];
+  belowEditor?: readonly string[];
+}
+
+export interface StatuslineRenderResult {
+  footer?: readonly string[];
+  widgets?: StatuslineWidgetRenderResult;
+  status?: string;
+}
+
+export type StatuslineRendererResult = StatuslineRenderResult | readonly string[];
+
+export type StatuslineRenderer = (
+  input: StatuslineRenderInput,
+) => StatuslineRendererResult | Promise<StatuslineRendererResult>;

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@sentiolabs/pi-scriptable-statusline",
+  "version": "0.1.0",
+  "description": "Scriptable footer and statusline UI package for Pi.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-skill",
+    "statusline",
+    "footer",
+    "widgets"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Sentio Labs",
+    "url": "https://github.com/sentiolabs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/SentioLabs/pi-nexus.git",
+    "directory": "packages/pi-scriptable-statusline"
+  },
+  "homepage": "https://github.com/SentioLabs/pi-nexus/tree/main/packages/pi-scriptable-statusline#readme",
+  "bugs": {
+    "url": "https://github.com/SentioLabs/pi-nexus/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.mjs && npm run typecheck",
+    "typecheck": "tsc -p tsconfig.json",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:dry-run"
+  },
+  "files": [
+    "extensions/",
+    "skills/",
+    "prompts/",
+    "templates/",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0",
+    "@types/node": "^24.12.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    },
+    "@mariozechner/pi-tui": {
+      "optional": true
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/statusline.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts/*.md"
+    ]
+  }
+}

package/prompts/statusline.md

@@ -0,0 +1,5 @@
+---
+description: Use the statusline-setup skill to customize @sentiolabs/pi-scriptable-statusline.
+---
+
+Use the `statusline-setup` skill to configure `@sentiolabs/pi-scriptable-statusline` for this user's requested layout.

package/skills/statusline-setup/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: statusline-setup
+description: Configure the scriptable Pi statusline renderer. Use when the user wants to customize Pi's footer, statusline, model/context display, git/repo display, provider limit display, or above/below-editor status widgets through @sentiolabs/pi-scriptable-statusline.
+license: MIT
+---
+
+# Statusline Setup
+
+Configure `@sentiolabs/pi-scriptable-statusline` by creating or editing the user's renderer at `~/.pi/agent/scriptable-statusline/render.ts`.
+
+## Rules
+
+- Treat `~/.pi/agent/scriptable-statusline/render.ts` as user-owned code.
+- Read the existing renderer before editing it.
+- Preserve custom helper functions and comments when practical.
+- Ask a concise clarifying question only when the desired layout is ambiguous.
+- Prefer simple JS/TS code over a generated framework.
+- Use `import type { StatuslineRenderer } from "@sentiolabs/pi-scriptable-statusline";` for type hints.
+- Return footer lines through `footer`, above-editor lines through `widgets.aboveEditor`, and below-editor lines through `widgets.belowEditor`.
+- If the user wants this package to own the footer, remind them to disable other footer replacement packages such as `pi-powerline-footer`.
+- After editing, tell the user to run `/statusline reload` if the extension does not reload automatically.
+
+## Renderer template
+
+```typescript
+import type { StatuslineRenderer } from "@sentiolabs/pi-scriptable-statusline";
+
+const render: StatuslineRenderer = async (input) => ({
+  footer: [
+    `${input.model.label} · ${input.repo.name} · ${input.git.branch ?? "no-git"}`,
+    `ctx ${input.context.percent ?? "?"}% · ${input.tokens.totalLabel} · ${input.cost.totalLabel}`,
+  ],
+  widgets: {
+    belowEditor: input.extensionStatuses.map((status) => status.text),
+  },
+});
+
+export default render;
+```
+
+## Verification
+
+- The renderer exports a default function.
+- The renderer returns strings only.
+- The renderer handles `null` branch, context, and limits values.
+- The renderer does not import project-local files unless the user explicitly asks for project-specific behavior.

package/templates/default-render.ts

@@ -0,0 +1,22 @@
+import type { StatuslineRenderer } from "@sentiolabs/pi-scriptable-statusline";
+
+const render: StatuslineRenderer = async (input) => {
+  const branch = input.git.branch ?? "no-git";
+  const context = input.context.percent === null ? "ctx ?" : `ctx ${input.context.percent}%`;
+  const daily = input.limits.daily?.label ?? "daily ?";
+  const weekly = input.limits.weekly?.label ?? "weekly ?";
+  const statuses = input.extensionStatuses.map((status) => status.text).filter(Boolean);
+
+  return {
+    footer: [
+      `${input.model.label} · ${input.repo.name} · ${branch}`,
+      `${context} · ${input.tokens.totalLabel} · ${input.cost.totalLabel} · ${daily} · ${weekly}`,
+    ],
+    widgets: {
+      belowEditor: statuses.length > 0 ? [`statuses: ${statuses.join(" · ")}`] : [],
+    },
+    status: `${context} · ${input.model.label}`,
+  };
+};
+
+export default render;