pi-signal-footer 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-signal-footer contributors
+
+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,84 @@
+# pi-signal-footer
+
+English | [简体中文](README.zh-CN.md)
+
+```text
+agent-demo · fix-context-bar │ opencode-go › ◎ deepseek-v4-flash-0731 │ ✦ max │ ⎇ main    ⎔ 12% [━━──────────────────] 36k/300k
+↓ 213 ↑ 32k │ ↻ 5.1M (97%) ✎ 137k │ $0.087 │ ◷ 2h25m · 1轮 · 45 tok/s    ⇄ MCP 1/1 · LSP typescript
+```
+
+A status footer for [Pi Coding Agent](https://github.com/earendil-works/pi-mono), replacing the built-in one.
+
+The first line shows the project path, session name, provider and model, thinking level, and git branch. Model icons are matched by model family, and paths under the home directory are abbreviated to `~`. The context bar takes whatever width is left and shows the percentage plus used and window tokens: warning color at 50%, error color at 75%, `?` while usage is unknown.
+
+The second line shows input and output tokens, cache read with hit ratio, cache write, accumulated cost, session time and turns, and the streaming rate of the last response. MCP and LSP statuses written by other extensions are rendered in the same style; unrecognized text passes through unchanged.
+
+On narrower terminals the two lines split into three and then six, and fields that no longer fit are truncated. All colors come from the active Pi theme. Icons are plain-text glyphs one column wide, without emoji variants.
+
+## Install
+
+### npm
+
+```sh
+pi install npm:pi-signal-footer
+```
+
+Tracks the latest release and updates with `pi update --extensions`. To pin a version, use `pi install npm:pi-signal-footer@0.2.1`.
+
+### Git
+
+```sh
+pi install git:github.com/chengzhi-c/pi-signal-footer@v0.2.1
+```
+
+Stays on the tag; to upgrade, rerun the command with the new tag.
+
+### Local path
+
+```sh
+pi install ./pi-signal-footer
+```
+
+Loads a directory from disk, for development and testing.
+
+Requires Pi Coding Agent ≥ 0.84 and Node.js ≥ 22.19.0.
+
+## Configure
+
+Field visibility is a single `CONFIG` object at the top of `index.ts`:
+
+```ts
+export const CONFIG = {
+  showProject: true,      // full project path (parent dirs dimmed, home abbreviated to ~)
+  showSessionName: true,  // session name, when set
+  showDuration: true,     // active time span
+  showTurns: true,        // assistant turns
+  showSpeed: true,        // streaming tok/s of the last response
+  showBranch: true,       // git branch
+  showCacheRatio: true,   // cache hit ratio
+};
+```
+
+## Commands
+
+```text
+/signal-footer legend   show the metric legend above the editor
+/signal-footer hide     hide the legend
+/signal-footer off      switch back to the native footer (this session)
+/signal-footer on       re-enable this footer (this session)
+```
+
+## Development
+
+```sh
+npm test
+npm run typecheck
+npm run check
+npm run pack:check
+```
+
+`npm run check` runs the tests and the TypeScript check; `npm run pack:check` previews the files that ship in the package. The TypeScript check skips declarations inside the Pi SDK dependency tree and checks the extension source itself strictly.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,84 @@
+# pi-signal-footer
+
+[English](README.md) | 简体中文
+
+```text
+agent-demo · fix-context-bar │ opencode-go › ◎ deepseek-v4-flash-0731 │ ✦ max │ ⎇ main    ⎔ 12% [━━──────────────────] 36k/300k
+↓ 213 ↑ 32k │ ↻ 5.1M (97%) ✎ 137k │ $0.087 │ ◷ 2h25m · 1轮 · 45 tok/s    ⇄ MCP 1/1 · LSP typescript
+```
+
+为 [Pi Coding Agent](https://github.com/earendil-works/pi-mono) 提供的状态栏，替代内置 footer。
+
+第一行显示项目路径、会话名、provider 和模型、思考等级、Git 分支。模型图标按模型家族匹配，主目录下的路径缩写为 `~`。上下文占用条用掉行内剩余宽度，显示百分比与已用/窗口 token：占用 ≥50% 变警告色，≥75% 变错误色，未知时显示 `?`。
+
+第二行显示输入/输出 token、缓存读与命中率、缓存写、累计成本、会话时长与轮次，以及最近一次响应的流式速率。其他扩展写入的 MCP、LSP 状态按同一套样式渲染，识别不了的文案原样显示。
+
+终端变窄时两行先拆成三行、再拆成六行，放不下的字段截断显示。颜色全部取自当前 Pi 主题，图标是实测宽度为 1 的纯文本字形。
+
+## 安装
+
+### npm
+
+```sh
+pi install npm:pi-signal-footer
+```
+
+不带版本号，随 `pi update --extensions` 自动更新。固定版本用 `pi install npm:pi-signal-footer@0.2.1`。
+
+### Git
+
+```sh
+pi install git:github.com/chengzhi-c/pi-signal-footer@v0.2.1
+```
+
+固定在 tag 上；升级时用新 tag 重新执行这条命令。
+
+### 本地路径
+
+```sh
+pi install ./pi-signal-footer
+```
+
+加载磁盘上的目录，适合开发调试。
+
+需要 Pi Coding Agent ≥ 0.84 和 Node.js ≥ 22.19.0。
+
+## 配置
+
+字段显隐由 `index.ts` 顶部的 `CONFIG` 对象控制：
+
+```ts
+export const CONFIG = {
+  showProject: true,      // 完整项目路径（上级目录弱化，主目录缩写为 ~）
+  showSessionName: true,  // 会话名（设置后显示）
+  showDuration: true,     // 活跃时间跨度
+  showTurns: true,        // 交互轮次
+  showSpeed: true,        // 最近一次响应的流式 tok/s
+  showBranch: true,       // Git 分支
+  showCacheRatio: true,   // 缓存命中率
+};
+```
+
+## 命令
+
+```text
+/signal-footer legend   在编辑器上方显示指标图例
+/signal-footer hide     隐藏图例
+/signal-footer off      临时切回原生状态栏（本会话）
+/signal-footer on       重新启用本状态栏（本会话）
+```
+
+## 开发
+
+```sh
+npm test
+npm run typecheck
+npm run check
+npm run pack:check
+```
+
+`npm run check` 跑测试套件和 TypeScript 检查，`npm run pack:check` 预览将随包发布的文件。TypeScript 检查跳过 Pi SDK 依赖树内的声明，扩展源码本身按严格模式检查。
+
+## 许可证
+
+[MIT](LICENSE)

package/format.ts

@@ -0,0 +1,166 @@
+export const LEGEND_LINES = [
+  "指标与符号图例",
+  "↓ 输入: 本会话送往模型的请求 token；↑ 输出: 模型生成的 token。",
+  "↻ 缓存读: 已复用的提示词缓存 token 及命中率；✎ 缓存写: 新写入缓存的 token。",
+  "费用($): 会话累计估算成本；⎔: 提示词上下文占用比例与窗口 token（已用/上限）。",
+  "模型: 图标 provider › model（图标按模型家族匹配）；✦ 推理: 思考等级；⎇ 分支: 当前 Git 分支。",
+  "⇄ MCP: 已连接/启用的 MCP 服务器数（未满黄色、全未连灰色：懒连接的服务器首次使用前不在线属正常）；LSP: 活动中的语言服务器，✗ 标记失败，无活动不显示。",
+  "项目: 当前完整路径（上级目录弱化、主目录缩写为 ~；含会话名，若已设置）；◷: 会话活跃跨度、交互轮次与最近一次响应的流式速率（tok/s）。",
+  "关闭图例: /signal-footer hide",
+];
+
+export type ProjectPathParts = { parent: string; name: string };
+export type ContextBarParts = { fill: string; track: string; unknown: boolean };
+export type LspChip = { failed: boolean; names: string };
+export type McpStatus = { connected: number; enabled: number };
+
+/**
+ * 图标按「provider/model」子串匹配模型家族。子串匹配是有意的（gpt4、chatgpt-*、
+ * o1-pro 等真实变体依赖它）；OpenAI 宽匹配组放在所有命名家族之后，避免他牌
+ * -o1/-o3 后缀模型误挂 OpenAI 图标。
+ */
+export function getModelIcon(modelId = "", provider = ""): string {
+  const combined = `${provider}/${modelId}`.toLowerCase();
+  if (combined.includes("grok") || combined.includes("xai")) return "𝕏";
+  if (combined.includes("glm") || combined.includes("zhipu") || combined.includes("chatglm")) return "𝐙";
+  if (combined.includes("claude") || combined.includes("anthropic")) return "✻";
+  if (combined.includes("gemini") || combined.includes("gemma") || combined.includes("google")) return "✧";
+  if (combined.includes("deepseek") || combined.includes("deep-seek")) return "◎";
+  if (combined.includes("qwen") || combined.includes("qwq") || combined.includes("tongyi")) return "𝐐";
+  if (combined.includes("llama") || combined.includes("meta")) return "𝕃";
+  if (combined.includes("mistral") || combined.includes("codestral") || combined.includes("mixtral")) return "𝐌";
+  if (combined.includes("kimi") || combined.includes("moonshot")) return "𝐊";
+  if (combined.includes("doubao") || combined.includes("bytedance")) return "𝐃";
+  if (combined.includes("yi-") || combined.includes("01-ai") || combined.includes("lingyi")) return "①";
+  if (combined.includes("minimax") || combined.includes("abab")) return "⬡";
+  if (combined.includes("gpt") || combined.includes("o1") || combined.includes("o3") || combined.includes("openai") || combined.includes("chatgpt")) return "⬢";
+  if (combined.includes("ollama") || combined.includes("local")) return "⌂";
+  return "◈";
+}
+
+/** token 数压缩为稳定后缀：999 → "999"，1250 → "1.3k"，32_000 → "32k"，5_100_000 → "5.1M"。 */
+export function formatTokens(count: number): string {
+  const value = Number.isFinite(count) && count > 0 ? count : 0;
+
+  if (value < 1_000) return Math.round(value).toString();
+  if (value < 10_000) return `${(value / 1_000).toFixed(1)}k`;
+  if (value < 1_000_000) return `${Math.round(value / 1_000)}k`;
+  if (value < 10_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  return `${Math.round(value / 1_000_000)}M`;
+}
+
+export function formatCost(cost: number): string {
+  const value = Number.isFinite(cost) && cost > 0 ? cost : 0;
+  return `$${value.toFixed(3)}`;
+}
+
+export function formatCacheHitRatio(read: number, write: number): string {
+  const r = Number.isFinite(read) && read > 0 ? read : 0;
+  const w = Number.isFinite(write) && write > 0 ? write : 0;
+  const total = r + w;
+  if (total === 0) return "0%";
+  return `${Math.round((r / total) * 100)}%`;
+}
+
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "0m";
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/** 最近一次响应的生成速率：输出 token ÷ 首 token 到响应结束的墙钟时间。 */
+export function formatSpeed(tokens: number, ms: number): string {
+  if (!Number.isFinite(tokens) || !Number.isFinite(ms) || tokens <= 0 || ms <= 0) return "";
+  return `${Math.round(tokens / (ms / 1000))} tok/s`;
+}
+
+/** 项目槽位：完整路径，主目录缩写为 ~。返回弱化的上级目录与加粗的末级目录名。 */
+export function splitProjectPath(cwd = "", home = ""): ProjectPathParts {
+  const normalize = (p: unknown): string => String(p ?? "").replace(/[\\/]+$/, "");
+  const c = normalize(cwd);
+  const h = normalize(home);
+  if (!c) return { parent: "", name: "" };
+
+  let display = c;
+  const windowsPath = /^[A-Za-z]:[\\/]/.test(c) || /^[A-Za-z]:[\\/]/.test(h);
+  const comparableCwd = windowsPath ? c.toLowerCase() : c;
+  const comparableHome = windowsPath ? h.toLowerCase() : h;
+  if (h && comparableCwd === comparableHome) return { parent: "", name: "~" };
+  if (h && comparableCwd.startsWith(comparableHome) && (c[h.length] === "\\" || c[h.length] === "/")) {
+    display = `~${c.slice(h.length)}`;
+  }
+
+  const parts = display.split(/[\\/]/).filter(Boolean);
+  const name = parts[parts.length - 1] ?? "";
+  const root = /^[\\/]/.test(display) ? "/" : "";
+  const parent = parts.slice(0, -1).join("/");
+  return { parent: `${root}${parent ? `${parent}/` : ""}`, name };
+}
+
+const CONTEXT_BAR_FILLED = "━";
+const CONTEXT_BAR_EMPTY = "─";
+
+export function normalizeContextPercent(percent: unknown): number | undefined {
+  if (typeof percent !== "number" || !Number.isFinite(percent)) return undefined;
+  return Math.min(100, Math.max(0, percent));
+}
+
+export function formatContext(tokens: number | null | undefined, contextWindow: number | null | undefined): string {
+  const used = typeof tokens === "number" && Number.isFinite(tokens) && tokens >= 0 ? Math.round(tokens) : undefined;
+  const window = typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0
+    ? contextWindow
+    : undefined;
+
+  return `${used === undefined ? "?" : formatTokens(used)}/${window === undefined ? "?" : formatTokens(window)}`;
+}
+
+/** 唯一的填充数学：返回已填充/剩余轨道字符串，供着色组装与纯文本输出共用。 */
+export function contextBarParts(percent: unknown, width: number): ContextBarParts {
+  const length = Number.isInteger(width) && width > 0 ? width : 1;
+  const normalizedPercent = normalizeContextPercent(percent);
+
+  if (normalizedPercent === undefined) return { fill: "", track: "?".repeat(length), unknown: true };
+
+  const filled = normalizedPercent === 0
+    ? 0
+    : Math.max(1, Math.round((normalizedPercent / 100) * length));
+  return { fill: CONTEXT_BAR_FILLED.repeat(filled), track: CONTEXT_BAR_EMPTY.repeat(length - filled), unknown: false };
+}
+
+export function sanitizeStatusText(text: unknown): string {
+  if (typeof text !== "string") return "";
+  return text.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim();
+}
+
+/** 外部插件写入的状态自带 ANSI 着色，解析前先剥掉。 */
+export function stripAnsi(text: unknown): string {
+  return String(text ?? "").replace(/\u001B\[[0-9;]*m/g, "");
+}
+
+/** 识别 pi-mcp-adapter 状态：compact "MCP 1/2" 或 full "🔌 MCP: N servers enabled (M connected)"。 */
+export function parseMcpStatus(text: unknown): McpStatus | undefined {
+  const raw = stripAnsi(sanitizeStatusText(text));
+  const compact = raw.match(/^MCP (\d+)\/(\d+)$/);
+  if (compact) return { connected: Number(compact[1]), enabled: Number(compact[2]) };
+  const full = raw.match(/^(?:🔌 )?MCP: (\d+) servers? enabled(?: \((\d+) connected\))?(?: \((\d+) disabled\))?$/);
+  if (full) return { connected: full[2] !== undefined ? Number(full[2]) : 0, enabled: Number(full[1]) };
+  return undefined;
+}
+
+/**
+ * 识别 pi-lens 的 LSP 状态段："LSP Active: a, b" / "LSP Failed: x" / "LSP Inactive"，
+ * Active 与 Failed 可能以 " · " 合并在同一条状态里。Inactive 返回空数组（无活动不显示）。
+ */
+export function parseLspStatus(text: unknown): LspChip[] | undefined {
+  const raw = stripAnsi(sanitizeStatusText(text));
+  if (raw === "LSP Inactive") return [];
+  const chips: LspChip[] = [];
+  for (const segment of raw.split(" · ")) {
+    const match = segment.trim().match(/^LSP (Active|Failed): (.+)$/);
+    if (!match) return undefined;
+    chips.push({ failed: match[1] === "Failed", names: match[2].trim() });
+  }
+  return chips;
+}

package/index.ts

@@ -0,0 +1,465 @@
+import type { ExtensionAPI, ExtensionContext, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import {
+  LEGEND_LINES,
+  formatCacheHitRatio,
+  formatContext,
+  formatCost,
+  formatDuration,
+  formatSpeed,
+  formatTokens,
+  getModelIcon,
+  parseMcpStatus,
+  parseLspStatus,
+  sanitizeStatusText,
+  contextBarParts,
+  normalizeContextPercent,
+  splitProjectPath,
+} from "./format.ts";
+
+/** 字段开关：改这里即可定制 footer，无需动渲染逻辑。 */
+export const CONFIG = {
+  showProject: true,      // 项目路径（上级目录弱化，主目录缩写为 ~）
+  showSessionName: true,  // 会话名（仅在 /session name 设置后出现）
+  showDuration: true,     // 会话活跃跨度（首条消息 → 最新消息）
+  showTurns: true,        // 交互轮次（assistant 消息数）
+  showSpeed: true,        // 流式生成速率（tok/s，最近一次响应）
+  showBranch: true,       // git 分支
+  showCacheRatio: true,   // 缓存命中率
+};
+
+const LEGEND_WIDGET_KEY = "pi-signal-footer-legend";
+const WIDE_LAYOUT_WIDTH = 112;
+const MEDIUM_LAYOUT_WIDTH = 76;
+const MIN_CONTEXT_BAR = 3;
+const MAX_CONTEXT_BAR = 20;
+const CONTEXT_WARNING_PERCENT = 50;
+const CONTEXT_ERROR_PERCENT = 75;
+
+type ContextColor = "accent" | "warning" | "error" | "muted";
+
+type UsageLike = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: { total?: number };
+};
+
+type UsageTotals = Required<Omit<UsageLike, "cost">> & { cost: number };
+
+type SessionStats = { firstTs: number; lastTs: number; turns: number };
+type SessionEntries = ReturnType<ExtensionContext["sessionManager"]["getEntries"]>;
+type SessionEntry = SessionEntries[number];
+
+// 流式速率计时：message_start 记请求时刻，首个 message_update 记首 token 时刻
+// （剔除 TTFT/排队），message_end 用精确 usage.output 收口。
+const streamState: { timing: { tRequest: number; tFirst: number } | null; lastRate: string } = {
+  timing: null,
+  lastRate: "",
+};
+
+function resetStreamState(): void {
+  streamState.timing = null;
+  streamState.lastRate = "";
+}
+
+function createUsageTotals(): UsageTotals {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}
+
+function addUsage(totals: UsageTotals, usage: UsageLike | undefined): void {
+  if (!usage) return;
+
+  const finiteNonNegative = (value: unknown): number =>
+    typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+
+  totals.input += finiteNonNegative(usage.input);
+  totals.output += finiteNonNegative(usage.output);
+  totals.cacheRead += finiteNonNegative(usage.cacheRead);
+  totals.cacheWrite += finiteNonNegative(usage.cacheWrite);
+  totals.cost += finiteNonNegative(usage.cost?.total);
+}
+
+function entryUsage(entry: SessionEntry | undefined): UsageLike | undefined {
+  if (!entry) return undefined;
+  if (entry.type === "message") {
+    if (entry.message.role !== "assistant" && entry.message.role !== "toolResult") return undefined;
+    return (entry.message as { usage?: UsageLike }).usage;
+  }
+  if (entry.type === "branch_summary" || entry.type === "compaction") {
+    return entry.usage as UsageLike | undefined;
+  }
+  return undefined;
+}
+
+// 求和口径与 pi 官方一致（core/getUsageCostBreakdown 同样四类全加）：assistant/toolResult/
+// branch_summary/compaction 的 usage 都是各次请求的增量，其中 branch_summary、compaction
+// 记录的是摘要生成那次 LLM 调用自身的 usage，直接累加不会重复计数。
+function computeUsageTotals(entries: SessionEntries): UsageTotals {
+  const totals = createUsageTotals();
+
+  for (const entry of entries) {
+    addUsage(totals, entryUsage(entry));
+  }
+
+  return totals;
+}
+
+function computeSessionStats(entries: SessionEntries): SessionStats {
+  const stats: SessionStats = { firstTs: Number.NaN, lastTs: Number.NaN, turns: 0 };
+
+  for (const entry of entries) {
+    const ts = Date.parse((entry as { timestamp?: string }).timestamp ?? "");
+    if (Number.isFinite(ts)) {
+      stats.firstTs = Number.isNaN(stats.firstTs) ? ts : Math.min(stats.firstTs, ts);
+      stats.lastTs = Number.isNaN(stats.lastTs) ? ts : Math.max(stats.lastTs, ts);
+    }
+    if (entry.type === "message" && entry.message.role === "assistant") stats.turns++;
+  }
+
+  return stats;
+}
+
+function usageSignature(usage: UsageLike | undefined): string {
+  if (!usage) return "";
+  return [usage.input, usage.output, usage.cacheRead, usage.cacheWrite, usage.cost?.total]
+    .map((value) => (Number.isFinite(value) ? value : ""))
+    .join(",");
+}
+
+/**
+ * Session entries can be updated in place while a response is finalized. Include
+ * the leaf fields used by the footer so those updates invalidate derived totals
+ * without scanning the entire session on every render. In-place edits to
+ * non-final entries are not detected; totals catch up on the next append.
+ */
+function entrySignature(entry: SessionEntry | undefined): string {
+  if (!entry) return "";
+  const timestamp = (entry as { timestamp?: string }).timestamp ?? "";
+  const role = entry.type === "message" ? entry.message.role : "";
+  return `${entry.type}|${timestamp}|${role}|${usageSignature(entryUsage(entry))}`;
+}
+
+function entriesCacheKey(entries: SessionEntries): string {
+  return `${entries.length}|${entrySignature(entries.at(-1))}`;
+}
+
+// 色彩语义（全部取自 pi 主题，随 dark/light 切换）：
+// 图标/分隔/轨道 = muted·dim，数值 = text，身份（provider/模型）= accent·text，
+// 钱 = warning，上下文 = 阈值变色（accent → warning → error）。
+
+function contextColor(percent: number | undefined): ContextColor {
+  if (percent === undefined) return "muted";
+  if (percent >= CONTEXT_ERROR_PERCENT) return "error";
+  if (percent >= CONTEXT_WARNING_PERCENT) return "warning";
+  return "accent";
+}
+
+/**
+ * 上下文字段自适应宽度：budget 是本行分给它的列数。
+ * 降级阶梯（信息价值排序）：条只是装饰，先丢；百分比与数值最后丢。
+ */
+function contextField(ctx: ExtensionContext, theme: Theme, budget: number): string {
+  const usage = ctx.getContextUsage();
+  const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+  const percent = normalizeContextPercent(usage?.percent);
+  const icon = theme.fg("muted", "⎔");
+
+  if (percent === undefined) {
+    return `${icon} ${theme.fg("muted", formatContext(undefined, contextWindow))}`;
+  }
+
+  const color = contextColor(percent);
+  const colorFn = (t: string) => theme.fg(color, t);
+  const head = `${icon} ${colorFn(`${Math.min(100, Math.round(percent))}%`)}`;
+  const numbers = colorFn(formatContext(usage?.tokens, contextWindow));
+  // 预算扣除：head、numbers，加上前后两个空格与条自身的一对方括号
+  const barWidth = Math.min(MAX_CONTEXT_BAR, budget - visibleWidth(head) - visibleWidth(numbers) - 4);
+
+  if (barWidth < MIN_CONTEXT_BAR) return `${head} ${numbers}`;
+  const { fill, track } = contextBarParts(percent, barWidth);
+  const bar = `${theme.fg("muted", "[")}${colorFn(fill)}${theme.fg("dim", track)}${theme.fg("muted", "]")}`;
+  return `${head} ${bar} ${numbers}`;
+}
+
+function modelField(ctx: ExtensionContext, theme: Theme, footerData: ReadonlyFooterDataProvider): string {
+  const provider = ctx.model?.provider?.trim() ?? "";
+  const model = ctx.model?.id ?? "no-model";
+  const modelIcon = getModelIcon(model, provider);
+  const pipe = theme.fg("muted", " │ ");
+
+  const separator = theme.fg("muted", "›");
+  const modelText = `${theme.fg("accent", modelIcon)} ${theme.fg("text", model)}`;
+
+  let modelSection = modelText;
+  if (provider) {
+    modelSection = `${theme.fg("accent", provider)} ${separator} ${modelText}`;
+  }
+
+  const parts = [modelSection];
+
+  if (ctx.model?.reasoning) {
+    const level = ctx.thinkingLevel ?? "off";
+    if (level !== "off") {
+      parts.push(`${theme.fg("muted", "✦")} ${theme.getThinkingBorderColor(level)(level)}`);
+    }
+  }
+
+  const branch = footerData.getGitBranch();
+  if (CONFIG.showBranch && branch) {
+    parts.push(theme.fg("muted", `⎇ ${branch}`));
+  }
+
+  return parts.join(pipe);
+}
+
+/**
+ * 扩展状态槽（右下角）：识别 pi-mcp-adapter / pi-lens 的已知文案后按本插件色板重排，
+ * 未知文案原样放行（保留源插件着色），对方改版时只会退化为原文而不会崩。
+ */
+function statusField(footerData: ReadonlyFooterDataProvider, theme: Theme): string | undefined {
+  const entries = Array.from(footerData.getExtensionStatuses().entries())
+    .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+
+  const chips: string[] = [];
+  for (const [, text] of entries) {
+    const clean = sanitizeStatusText(text);
+    if (!clean) continue;
+
+    const mcp = parseMcpStatus(clean);
+    if (mcp) {
+      if (mcp.enabled > 0) {
+        // 懒连接服务器闲置时 0 连接属正常，全未连用中性灰而不是故障红
+        const color = mcp.connected === 0 ? "muted" : mcp.connected < mcp.enabled ? "warning" : "text";
+        chips.push(`${theme.fg("muted", "⇄ MCP")} ${theme.fg(color, `${mcp.connected}/${mcp.enabled}`)}`);
+      }
+      continue;
+    }
+
+    const lsp = parseLspStatus(clean);
+    if (lsp) {
+      for (const chip of lsp) {
+        chips.push(
+          chip.failed
+            ? theme.fg("error", `LSP ✗ ${chip.names}`)
+            : `${theme.fg("muted", "LSP")} ${theme.fg("text", chip.names)}`,
+        );
+      }
+      continue;
+    }
+
+    chips.push(clean);
+  }
+
+  if (chips.length === 0) return undefined;
+  return chips.join(theme.fg("dim", " · "));
+}
+
+function truncate(value: string, width: number, theme: Theme): string {
+  return truncateToWidth(value, Math.max(1, width), theme.fg("dim", "..."));
+}
+
+/**
+ * 一行放 left + right：宽裕时右对齐；紧张时被保留的一侧整块不动，另一侧截断。
+ * 默认保留 right（数据块），protectLeft 用于身份字段（模型）优先的场景。
+ */
+function fitLine(left: string, right: string, width: number, theme: Theme, keepRight = true): string {
+  const kept = keepRight ? right : left;
+  const shrunk = keepRight ? left : right;
+  const gap = width - visibleWidth(left) - visibleWidth(right);
+
+  if (gap >= 2) return keepRight ? `${shrunk}${" ".repeat(gap)}${kept}` : `${kept}${" ".repeat(gap)}${shrunk}`;
+
+  const shrunkBudget = width - visibleWidth(kept) - 2;
+  if (shrunkBudget >= 1) {
+    return keepRight
+      ? `${truncate(shrunk, shrunkBudget, theme)}  ${kept}`
+      : `${kept}  ${truncate(shrunk, shrunkBudget, theme)}`;
+  }
+  return truncate(kept, width, theme);
+}
+
+function renderFooter(
+  ctx: ExtensionContext,
+  footerData: ReadonlyFooterDataProvider,
+  theme: Theme,
+  width: number,
+  totals: UsageTotals,
+  session: SessionStats,
+): string[] {
+  const pipe = theme.fg("muted", " │ ");
+
+  const input = `${theme.fg("muted", "↓")} ${theme.fg("text", formatTokens(totals.input))}`;
+  const output = `${theme.fg("muted", "↑")} ${theme.fg("text", formatTokens(totals.output))}`;
+
+  const hitRatio = CONFIG.showCacheRatio && totals.cacheWrite > 0 && totals.cacheRead > 0
+    ? formatCacheHitRatio(totals.cacheRead, totals.cacheWrite)
+    : undefined;
+  const cacheReadNum = `${theme.fg("text", formatTokens(totals.cacheRead))}${hitRatio ? theme.fg("muted", ` (${hitRatio})`) : ""}`;
+  const cacheRead = `${theme.fg("muted", "↻")} ${cacheReadNum}`;
+  const cacheWrite = `${theme.fg("muted", "✎")} ${theme.fg("text", formatTokens(totals.cacheWrite))}`;
+  const cost = theme.fg("warning", formatCost(totals.cost));
+  const model = modelField(ctx, theme, footerData);
+  const statuses = statusField(footerData, theme);
+
+  const timeParts: string[] = [];
+  if (CONFIG.showDuration && Number.isFinite(session.firstTs) && Number.isFinite(session.lastTs)) {
+    timeParts.push(theme.fg("text", formatDuration(session.lastTs - session.firstTs)));
+  }
+  if (CONFIG.showTurns && session.turns > 0) {
+    timeParts.push(theme.fg("text", `${session.turns}轮`));
+  }
+  if (CONFIG.showSpeed && streamState.lastRate) {
+    timeParts.push(theme.fg("text", streamState.lastRate));
+  }
+  const timeGroup = timeParts.length > 0
+    ? `${theme.fg("muted", "◷")} ${timeParts.join(theme.fg("muted", " · "))}`
+    : "";
+
+  const trafficGroup = `${input} ${output}`;
+  const cacheGroup = `${cacheRead} ${cacheWrite}`;
+  const stats = [trafficGroup, cacheGroup, cost, timeGroup].filter(Boolean).join(pipe);
+
+  // 项目槽位：完整路径——上级目录弱化、末级目录加粗、主目录缩写为 ~（可选链防旧版 pi 缺方法）
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  const { parent, name } = splitProjectPath(ctx.sessionManager.getCwd?.() ?? "", home);
+  const sessionName = name && CONFIG.showSessionName ? ctx.sessionManager.getSessionName?.() : undefined;
+  let projectSection = "";
+  if (CONFIG.showProject && name) {
+    projectSection = `${parent ? theme.fg("muted", parent) : ""}${theme.bold(theme.fg("text", name))}`;
+    if (sessionName) projectSection += theme.fg("muted", ` · ${sessionName}`);
+  }
+  let identityLeft = model;
+  if (projectSection) {
+    identityLeft = `${projectSection} ${pipe} ${model}`;
+  }
+
+  if (width >= WIDE_LAYOUT_WIDTH) {
+    const line1Right = contextField(ctx, theme, width - visibleWidth(identityLeft) - 2);
+    const line1 = fitLine(identityLeft, line1Right, width, theme, true);
+    const line2 = statuses ? fitLine(stats, statuses, width, theme, false) : truncate(stats, width, theme);
+    return [line1, line2];
+  }
+
+  if (width >= MEDIUM_LAYOUT_WIDTH) {
+    const line1Right = contextField(ctx, theme, width - visibleWidth(identityLeft) - 2);
+    const line1 = fitLine(identityLeft, line1Right, width, theme, true);
+    const line2 = truncate(stats, width, theme);
+    return [
+      line1,
+      line2,
+      ...(statuses ? [truncate(statuses, width, theme)] : []),
+    ];
+  }
+
+  return [
+    truncate(identityLeft, width, theme),
+    truncate(contextField(ctx, theme, width), width, theme),
+    truncate(trafficGroup, width, theme),
+    truncate(cacheGroup, width, theme),
+    truncate([cost, timeGroup].filter(Boolean).join(pipe), width, theme),
+    ...(statuses ? [truncate(statuses, width, theme)] : []),
+  ];
+}
+
+function installFooter(ctx: ExtensionContext): void {
+  let cachedEntryKey = "";
+  let cachedTotals = createUsageTotals();
+  let cachedSession: SessionStats = { firstTs: Number.NaN, lastTs: Number.NaN, turns: 0 };
+
+  ctx.ui.setFooter((tui, theme, footerData) => {
+    const unsubscribe = footerData.onBranchChange(() => tui.requestRender());
+
+    return {
+      dispose: unsubscribe,
+      invalidate() {},
+      render(width: number): string[] {
+        const entries = ctx.sessionManager.getEntries();
+        const key = entriesCacheKey(entries);
+        if (key !== cachedEntryKey) {
+          cachedTotals = computeUsageTotals(entries);
+          cachedSession = computeSessionStats(entries);
+          cachedEntryKey = key;
+        }
+        return renderFooter(ctx, footerData, theme, width, cachedTotals, cachedSession);
+      },
+    };
+  });
+}
+
+function showLegend(ctx: ExtensionContext): void {
+  ctx.ui.setWidget(LEGEND_WIDGET_KEY, LEGEND_LINES, { placement: "aboveEditor" });
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.on("message_start", (event) => {
+    if (event.message.role !== "assistant") return;
+    streamState.timing = { tRequest: Date.now(), tFirst: 0 };
+    streamState.lastRate = "";
+  });
+
+  pi.on("message_update", (event) => {
+    if (event.message.role !== "assistant") return;
+    if (streamState.timing && !streamState.timing.tFirst) streamState.timing.tFirst = Date.now();
+  });
+
+  pi.on("message_end", (event) => {
+    if (!streamState.timing || event.message.role !== "assistant") return;
+    const usage = (event.message as { usage?: { output?: number } }).usage;
+    const start = streamState.timing.tFirst || streamState.timing.tRequest;
+    const ms = Date.now() - start;
+    streamState.timing = null;
+    if (usage?.output && ms > 0) streamState.lastRate = formatSpeed(usage.output, ms);
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    resetStreamState();
+    installFooter(ctx);
+  });
+
+  // resources_discover 到来时 ctx 可能已刷新，重建 footer 是安全的：
+  // pi 的 setExtensionFooter 会先 dispose 旧组件（含 onBranchChange 退订）。
+  pi.on("resources_discover", async (_event, ctx) => {
+    installFooter(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    resetStreamState();
+    ctx.ui.setWidget(LEGEND_WIDGET_KEY, undefined);
+    ctx.ui.setFooter(undefined);
+  });
+
+  pi.registerCommand("signal-footer", {
+    description: "Show the status legend or control the readable footer",
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase();
+
+      if (action === "" || action === "legend" || action === "help") {
+        showLegend(ctx);
+        return;
+      }
+
+      if (action === "hide") {
+        ctx.ui.setWidget(LEGEND_WIDGET_KEY, undefined);
+        return;
+      }
+
+      if (action === "off") {
+        ctx.ui.setWidget(LEGEND_WIDGET_KEY, undefined);
+        ctx.ui.setFooter(undefined);
+        ctx.ui.notify("本会话已临时切回 Pi 原生状态栏。", "info");
+        return;
+      }
+
+      if (action === "on") {
+        installFooter(ctx);
+        ctx.ui.notify("本会话已启用可读状态栏。", "info");
+        return;
+      }
+
+      ctx.ui.notify("用法: /signal-footer [legend|hide|off|on]", "warning");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pi-signal-footer",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "A readable, responsive two-line status footer for Pi Coding Agent: model identity, token/cache/cost stats, adaptive context bar, session time and extension statuses.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chengzhi-c/pi-signal-footer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chengzhi-c/pi-signal-footer/issues"
+  },
+  "homepage": "https://github.com/chengzhi-c/pi-signal-footer#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "format.ts",
+    "index.ts"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "footer",
+    "statusline",
+    "tui"
+  ],
+  "scripts": {
+    "test": "tsx --test test/format.test.mjs test/index.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run test && npm run typecheck",
+    "pack:check": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^26.4.0",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2"
+  }
+}