pi-message-sidebar 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.2.0
+
+> Live goal tracking and cmux session context in the status dock.
+
+- Added a goal card to the status dock: when pi-codex-goal is active, the dock shows the objective (two wrapped lines), status glyph, token budget progress, and elapsed time, kept current across goal set/usage/clear entries.
+- Added cmux awareness: inside cmux, the `sess` row shows the workspace title (or ref) and surface ref instead of the session file datetime; outside cmux the previous format is kept.
+- Memoized session usage aggregation and goal reconstruction so dock refreshes stay O(1) for unchanged sessions.
+- Added refresh triggers for `agent_settled` so goal continuation updates surface without a turn boundary.
+- Aligned the header rule with the panel width.
+
+## 1.1.1
+
+> First release published from GitHub Actions with npm trusted publishing (OIDC); no tokens involved.
+
+
 ## 1.1.0
 
 > Pi 0.84.4: transcript overlap during TUI mode switches and narrow-pane width failures are resolved by mode-specific reserved layouts.

package/README.md

@@ -5,6 +5,8 @@ Persistent message history sidebar for [Pi](https://pi.dev).
 ## Features
 
 - Fixed 42-column panel on the right
+- Live goal card: objective, status, token budget, and elapsed time from pi-codex-goal entries
+- cmux session context: workspace title and surface ref replace the session file datetime inside cmux
 - Main transcript and editor render in their own reserved width
 - Native side-by-side layout in fullscreen TUI mode
 - Regular-mode compositor that reserves the same width in scrollback mode
@@ -55,7 +57,9 @@ The sidebar appears automatically in interactive mode when the terminal is at le
 - `index.ts` is the auto-discovered extension entrypoint.
 - `src/layout.ts` reserves a real horizontal region in fullscreen mode and composes an equivalent region in regular mode.
 - `src/sidebar-component.ts` owns message navigation and bounded rendering.
-- `src/status-dock.ts` renders session, model, context, cost, and extension status data.
+- `src/status-dock.ts` renders session, model, context, cost, goal, and extension status data.
+- `src/goal.ts` reconstructs the active pi-codex-goal from session entries.
+- `src/cmux.ts` resolves the cmux workspace title and surface ref once per session.
 - `src/style.ts` provides ANSI-safe row filling and width helpers.
 - `src/constants.ts` owns responsive layout thresholds.
 

package/message-sidebar.ts

@@ -5,6 +5,8 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
 import { isViewportTUI, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { CmuxContext } from "./src/cmux.ts";
+import { resolveCmuxContext } from "./src/cmux.ts";
 import { isSidebarVisible } from "./src/constants.ts";
 import { SidebarLayoutBridge } from "./src/layout.ts";
 import { SidebarComponent, type UserMessage } from "./src/sidebar-component.ts";
@@ -61,6 +63,7 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   let tui: TUI | null = null;
   let cachedContext: ExtensionContext | null = null;
   let footerData: ReadonlyFooterDataProvider | null = null;
+  let cmuxContext: CmuxContext | null = null;
   let refreshQueued = false;
 
   const scheduleRefresh = (ctx: ExtensionContext | null = cachedContext) => {
@@ -91,6 +94,10 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
     if (ctx.mode !== "tui") return;
     cachedContext = ctx;
+    void resolveCmuxContext().then((resolved) => {
+      cmuxContext = resolved;
+      scheduleRefresh(ctx);
+    });
     ctx.ui.setWidget(
       "message-sidebar-layout",
       (currentTui) => {
@@ -100,6 +107,7 @@ export default function messageSidebar(pi: ExtensionAPI): void {
           ctx,
           getFooterData: () => footerData,
           getThinkingLevel: () => pi.getThinkingLevel(),
+          getCmuxContext: () => cmuxContext,
           messages: collectUserMessages(ctx),
         });
         return new SidebarLayoutBridge(currentTui, sidebar);
@@ -116,6 +124,9 @@ export default function messageSidebar(pi: ExtensionAPI): void {
     });
 
     ctx.ui.onTerminalInput((data) => {
+      // Slash commands such as /goal mutate session entries without firing
+      // turn events; a coalesced refresh on any keystroke keeps the dock live.
+      scheduleRefresh();
       if (tui && !isSidebarVisible(tui.terminal.columns) && sidebar?.isFocused()) {
         sidebar.setFocused(false);
         tui.requestRender();
@@ -140,6 +151,7 @@ export default function messageSidebar(pi: ExtensionAPI): void {
     tui = null;
     cachedContext = null;
     footerData = null;
+    cmuxContext = null;
   });
 
   pi.registerShortcut("ctrl+shift+h", {
@@ -155,6 +167,7 @@ export default function messageSidebar(pi: ExtensionAPI): void {
   pi.on("message_end", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("turn_end", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("agent_end", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("agent_settled", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("model_select", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("thinking_level_select", (_event, ctx) => scheduleRefresh(ctx));
   pi.on("session_compact", (_event, ctx) => scheduleRefresh(ctx));

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "pi-message-sidebar",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Persistent responsive message history sidebar for Pi",
-  "keywords": ["pi-package", "pi-extension", "sidebar", "tui"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "sidebar",
+    "tui"
+  ],
   "author": "Francesco Frapporti <effedue@gmail.com>",
   "license": "MIT",
   "type": "module",
@@ -10,9 +15,18 @@
     "type": "git",
     "url": "git+https://github.com/Fornace/pi-message-sidebar.git"
   },
-  "files": ["index.ts", "message-sidebar.ts", "src", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": [
+    "index.ts",
+    "message-sidebar.ts",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "scripts": {
     "test": "node --import tsx --test test/*.test.ts",

package/src/cmux.ts

@@ -0,0 +1,75 @@
+import { execFile } from "node:child_process";
+
+export type CmuxContext = {
+  workspaceTitle: string | null;
+  workspaceRef: string | null;
+  surfaceRef: string | null;
+};
+
+export function runningInCmux(): boolean {
+  return Boolean(process.env.CMUX_WORKSPACE_ID || process.env.CMUX_SURFACE_ID);
+}
+
+function cmuxBin(): string {
+  return process.env.CMUX_PI_CMUX_BIN || "cmux";
+}
+
+function run(args: string[], timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(cmuxBin(), args, { timeout: timeoutMs }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(stdout);
+    });
+  });
+}
+
+async function identifyRefs(): Promise<{ workspaceRef: string | null; surfaceRef: string | null }> {
+  try {
+    const parsed = JSON.parse(await run(["identify"], 3000)) as {
+      caller?: { workspace_ref?: string; surface_ref?: string };
+    };
+    return { workspaceRef: parsed.caller?.workspace_ref ?? null, surfaceRef: parsed.caller?.surface_ref ?? null };
+  } catch {
+    return { workspaceRef: null, surfaceRef: null };
+  }
+}
+
+async function workspaceTitle(): Promise<string | null> {
+  const workspaceId = process.env.CMUX_WORKSPACE_ID;
+  if (!workspaceId) return null;
+  try {
+    const parsed = JSON.parse(await run(["rpc", "workspace.list", "{}"], 3000)) as {
+      workspaces?: { id?: string; custom_title?: string | null; description?: string | null }[];
+    };
+    const match = parsed.workspaces?.find((workspace) => workspace.id === workspaceId);
+    return match?.custom_title ?? match?.description ?? null;
+  } catch {
+    return null;
+  }
+}
+
+let cached: Promise<CmuxContext | null> | null = null;
+
+/**
+ * Resolves the cmux workspace title and surface ref for this session, once.
+ * Returns null when pi runs outside cmux. Lookup failures degrade to null
+ * fields so the sidebar keeps rendering with whatever it has.
+ */
+export function resolveCmuxContext(): Promise<CmuxContext | null> {
+  if (!cached) {
+    if (!runningInCmux()) cached = Promise.resolve(null);
+    else {
+      cached = (async () => {
+        const [refs, title] = await Promise.all([identifyRefs(), workspaceTitle()]);
+        const context: CmuxContext = {
+          workspaceTitle: title,
+          workspaceRef: refs.workspaceRef,
+          surfaceRef: refs.surfaceRef,
+        };
+        if (!context.workspaceTitle && !context.workspaceRef && !context.surfaceRef) return null;
+        return context;
+      })();
+    }
+  }
+  return cached;
+}

package/src/goal.ts

@@ -0,0 +1,76 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type ThreadGoal = {
+  goalId: string;
+  objective: string;
+  status: "active" | "paused" | "budgetLimited" | "complete";
+  tokenBudget: number | null;
+  tokensUsed: number;
+  activeSeconds: number;
+  createdAt: number;
+  updatedAt: number;
+};
+
+type BranchEntry = { type?: string; customType?: string; data?: unknown };
+
+const GOAL_ENTRY_TYPE = "pi-codex-goal";
+
+function isThreadGoal(value: unknown): value is ThreadGoal {
+  const goal = value as ThreadGoal | null;
+  return (
+    !!goal &&
+    typeof goal === "object" &&
+    typeof goal.goalId === "string" &&
+    typeof goal.objective === "string" &&
+    (goal.status === "active" || goal.status === "paused" || goal.status === "budgetLimited" || goal.status === "complete") &&
+    (goal.tokenBudget === null || typeof goal.tokenBudget === "number") &&
+    typeof goal.tokensUsed === "number" &&
+    typeof goal.activeSeconds === "number" &&
+    typeof goal.createdAt === "number" &&
+    typeof goal.updatedAt === "number"
+  );
+}
+
+/**
+ * Reconstructs the current thread goal from pi-codex-goal session entries.
+ * Mirrors reconstructGoal() from pi-codex-goal dist/state.js (schema version 1):
+ * "set" entries replace the goal, "clear" entries drop it, and "usage" entries
+ * advance tokens/time for runtime-usage statuses only.
+ */
+export function readThreadGoal(entries: Iterable<BranchEntry>): ThreadGoal | null {
+  let goal: ThreadGoal | null = null;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== GOAL_ENTRY_TYPE) continue;
+    const data = entry.data as Record<string, unknown> | null;
+    if (!data || typeof data !== "object" || data.version !== 1) continue;
+    if (data.kind === "clear") {
+      goal = null;
+    } else if (data.kind === "set" && isThreadGoal(data.goal)) {
+      goal = { ...(data.goal as ThreadGoal) };
+    } else if (data.kind === "usage" && goal) {
+      const usage = data.usage as { tokensUsed?: number; activeSeconds?: number } | undefined;
+      const updatedAt = data.updatedAt;
+      if (data.goalId !== goal.goalId) continue;
+      if (goal.status !== "active" && goal.status !== "budgetLimited") continue;
+      if (goal.status === "budgetLimited" && data.status === "active") continue;
+      if (typeof updatedAt !== "number" || typeof usage?.tokensUsed !== "number" || typeof usage.activeSeconds !== "number") continue;
+      if (updatedAt < goal.updatedAt || usage.tokensUsed < goal.tokensUsed || usage.activeSeconds < goal.activeSeconds) continue;
+      goal = { ...goal, status: data.status as ThreadGoal["status"], tokensUsed: usage.tokensUsed, activeSeconds: usage.activeSeconds, updatedAt } as ThreadGoal;
+    }
+  }
+  return goal;
+}
+
+type GoalCache = { key: string; goal: ThreadGoal | null };
+let cache: GoalCache | null = null;
+
+/** Cached readThreadGoal over the current session branch. */
+export function readSessionGoal(ctx: ExtensionContext): ThreadGoal | null {
+  const branch = ctx.sessionManager.getBranch();
+  const last = branch.at(-1);
+  const key = `${branch.length}:${last?.id ?? ""}:${last?.timestamp ?? ""}`;
+  if (cache && cache.key === key) return cache.goal;
+  const goal = readThreadGoal(branch);
+  cache = { key, goal };
+  return goal;
+}

package/src/sidebar-component.ts

@@ -7,6 +7,8 @@ import { basename } from "node:path";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { GAP_WINDOW, PINNED_COUNT, SIDEBAR_WIDTH } from "./constants.ts";
+import type { CmuxContext } from "./cmux.ts";
+import { readSessionGoal } from "./goal.ts";
 import { assertLinesFit } from "./layout.ts";
 import { renderStatusDock } from "./status-dock.ts";
 import {
@@ -36,6 +38,7 @@ type SidebarOptions = {
   ctx: ExtensionContext;
   getFooterData: () => ReadonlyFooterDataProvider | null;
   getThinkingLevel: () => string;
+  getCmuxContext: () => CmuxContext | null;
   messages: UserMessage[];
 };
 
@@ -118,6 +121,7 @@ export class SidebarComponent {
       this.options.getFooterData(),
       this.options.getThinkingLevel(),
       this.focused,
+      this.options.getCmuxContext,
     );
     while (lines.length < targetHeight - dock.length) lines.push(fillRow(" ", safeWidth, BG));
     const bodyLimit = Math.max(0, targetHeight - dock.length);
@@ -136,7 +140,7 @@ export class SidebarComponent {
   private renderHeader(width: number): string[] {
     const icon = this.focused ? `${FG_ACC}●${RST}` : `${FG_DIM}○${RST}`;
     const mode = this.focused ? `${FG_ACC}●${RST} ${FG_MID}focused${RST}` : `${FG_DIM}passive${RST}`;
-    const separator = `${FG_DIM}${"─".repeat(Math.max(0, width - 4))}${RST}`;
+    const separator = `${FG_DIM}${"─".repeat(Math.max(0, width - 2))}${RST}`;
     return [
       fillRow(" ", width, BG_HDR),
       fillRow(` ${icon} ${BOLD}${FG_BRIGHT}Messages${RST}${FG_DIM} ${this.messages.length}${RST}  ${mode}`, width, BG_HDR),
@@ -197,6 +201,8 @@ export class SidebarComponent {
   private signature(width: number, height: number): string {
     const usage = this.options.ctx.getContextUsage?.();
     const statuses = this.options.getFooterData()?.getExtensionStatuses();
+    const goal = readSessionGoal(this.options.ctx);
+    const cmux = this.options.getCmuxContext();
     return JSON.stringify({
       width,
       height,
@@ -206,6 +212,8 @@ export class SidebarComponent {
       thinking: this.options.getThinkingLevel(),
       usage,
       statuses: statuses ? [...statuses.entries()] : [],
+      goal: goal ? `${goal.goalId}:${goal.status}:${goal.tokensUsed}:${goal.activeSeconds}:${goal.updatedAt}` : null,
+      cmux: cmux ? `${cmux.workspaceTitle}:${cmux.surfaceRef}` : null,
     });
   }
 

package/src/status-dock.ts

@@ -4,22 +4,31 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { basename } from "node:path";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { readSessionGoal, type ThreadGoal } from "./goal.ts";
+import type { CmuxContext } from "./cmux.ts";
 import {
   BG,
   BG_CARD,
   BG_HDR,
+  FG_ACC,
   FG_BRIGHT,
   FG_DIM,
+  FG_ERR,
   FG_FAINT,
   FG_INFO,
   FG_MID,
+  FG_NORM,
+  FG_OK,
+  FG_WARN,
   RST,
   contextColor,
   fillRow,
   formatCwd,
+  formatDuration,
   formatTokens,
   progressBar,
   sanitizeStatusText,
+  wrapText,
 } from "./style.ts";
 
 type Usage = {
@@ -33,7 +42,14 @@ type Usage = {
   contextWindow: number;
 };
 
+let usageCache: { key: string; usage: Usage } | null = null;
+
 function computeUsage(ctx: ExtensionContext): Usage {
+  const entries = ctx.sessionManager.getEntries();
+  const last = entries.at(-1);
+  const key = `${entries.length}:${last?.id ?? ""}`;
+  if (usageCache && usageCache.key === key) return usageCache.usage;
+
   let input = 0;
   let output = 0;
   let cacheRead = 0;
@@ -41,7 +57,7 @@ function computeUsage(ctx: ExtensionContext): Usage {
   let cost = 0;
   let latestCacheHitRate: number | undefined;
 
-  for (const entry of ctx.sessionManager.getEntries()) {
+  for (const entry of entries) {
     if (entry.type !== "message" || entry.message.role !== "assistant") continue;
     const usage = (entry.message as any).usage ?? {};
     input += usage.input ?? 0;
@@ -54,7 +70,7 @@ function computeUsage(ctx: ExtensionContext): Usage {
   }
 
   const context = ctx.getContextUsage?.();
-  return {
+  const usage = {
     input,
     output,
     cacheRead,
@@ -64,6 +80,8 @@ function computeUsage(ctx: ExtensionContext): Usage {
     contextPercent: context?.percent ?? null,
     contextWindow: context?.contextWindow ?? ctx.model?.contextWindow ?? 0,
   };
+  usageCache = { key, usage };
+  return usage;
 }
 
 function dockHeader(width: number, title: string): string {
@@ -80,15 +98,76 @@ function dockRow(width: number, label: string, value: string): string {
   return fillRow(`${pad}${FG_FAINT}${label.padEnd(labelWidth)}${RST} ${clipped}`, width, BG_CARD);
 }
 
+function goalStatusGlyph(goal: ThreadGoal): { icon: string; color: string; label: string } {
+  switch (goal.status) {
+    case "active": return { icon: "◉", color: FG_ACC, label: "active" };
+    case "paused": return { icon: "○", color: FG_DIM, label: "paused" };
+    case "budgetLimited": return { icon: "▲", color: FG_WARN, label: "budget" };
+    case "complete": return { icon: "✓", color: FG_OK, label: "done" };
+  }
+}
+
+function renderGoalCard(width: number, goal: ThreadGoal): string[] {
+  const glyph = goalStatusGlyph(goal);
+  const rows = [dockHeader(width, "goal")];
+
+  const indent = "   ";
+  const wrapped = wrapText(goal.objective, Math.max(1, width - 4));
+  const shown = wrapped.slice(0, 2);
+  rows.push(fillRow(` ${glyph.color}${glyph.icon}${RST} ${shown[0] ? `${FG_BRIGHT}${shown[0]}${RST}` : ""}`, width, BG_CARD));
+  if (shown[1]) rows.push(fillRow(`${indent}${FG_NORM}${shown[1]}${RST}`, width, BG_CARD));
+  if (wrapped.length > 2) rows.push(fillRow(`${indent}${FG_FAINT}…+${wrapped.length - 2} lines${RST}`, width, BG_CARD));
+
+  const budget = goal.tokenBudget
+    ? `${formatTokens(goal.tokensUsed)}/${formatTokens(goal.tokenBudget)}`
+    : `${formatTokens(goal.tokensUsed)}/∞`;
+  const percent = goal.tokenBudget ? (goal.tokensUsed / goal.tokenBudget) * 100 : null;
+  const overBudget = percent !== null && percent > 100;
+  const budgetColor = overBudget ? FG_ERR : glyph.color;
+  rows.push(fillRow(
+    ` ${budgetColor}${budget}${RST} ${progressBar(percent)} ${glyph.color}${glyph.label}${RST} ${FG_FAINT}·${RST} ${FG_MID}${formatDuration(goal.activeSeconds)}${RST}`,
+    width,
+    BG_CARD,
+  ));
+  return rows;
+}
+
+function renderSessRow(width: number, ctx: ExtensionContext, cmux: CmuxContext | null): string {
+  const sessionId = ctx.sessionManager.getSessionId();
+  const shortId = sessionId.replace(/-/g, "").slice(-8);
+  let value: string;
+  if (cmux) {
+    const surfacePart = cmux.surfaceRef ? ` ${FG_FAINT}·${RST} ${FG_FAINT}${cmux.surfaceRef}${RST}` : "";
+    const budget = width - 7 - visibleWidth(surfacePart);
+    const name = cmux.workspaceTitle
+      ? truncateToWidth(cmux.workspaceTitle, budget, "…")
+      : cmux.workspaceRef ?? "";
+    value = `${FG_BRIGHT}${name}${RST}${surfacePart}`;
+  } else {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    value = [
+      `${FG_INFO}#${shortId}${RST}`,
+      sessionFile ? `${FG_FAINT}${basename(sessionFile)}${RST}` : undefined,
+    ].filter(Boolean).join(` ${FG_FAINT}·${RST} `);
+  }
+  return dockRow(width, "sess", value);
+}
+
 export function renderStatusDock(
   width: number,
   ctx: ExtensionContext,
   footerData: ReadonlyFooterDataProvider | null,
   thinkingLevel: string,
   focused: boolean,
+  getCmuxContext: () => CmuxContext | null,
 ): string[] {
   const usage = computeUsage(ctx);
-  const rows = [fillRow(" ", width, BG), dockHeader(width, "runtime")];
+  const goal = readSessionGoal(ctx);
+  const rows: string[] = [];
+
+  if (goal) rows.push(...renderGoalCard(width, goal));
+
+  rows.push(fillRow(" ", width, BG), dockHeader(width, "runtime"));
   const branch = footerData?.getGitBranch();
   const sessionName = ctx.sessionManager.getSessionName();
   const workspace = [
@@ -97,14 +176,7 @@ export function renderStatusDock(
     sessionName ? `${FG_MID}${sessionName}${RST}` : undefined,
   ].filter(Boolean).join(` ${FG_FAINT}•${RST} `);
   rows.push(dockRow(width, "cwd", workspace));
-
-  const sessionId = ctx.sessionManager.getSessionId();
-  const sessionFile = ctx.sessionManager.getSessionFile();
-  const shortId = sessionId.replace(/-/g, "").slice(-8);
-  rows.push(dockRow(width, "sess", [
-    `${FG_INFO}#${shortId}${RST}`,
-    sessionFile ? `${FG_FAINT}${basename(sessionFile)}${RST}` : undefined,
-  ].filter(Boolean).join(` ${FG_FAINT}•${RST} `)));
+  rows.push(renderSessRow(width, ctx, getCmuxContext()));
 
   const model = ctx.model;
   if (model) {

package/src/style.ts

@@ -38,6 +38,15 @@ export function formatTime(timestamp: string): string {
   return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
 }
 
+export function formatDuration(totalSeconds: number): string {
+  const minutes = Math.floor(totalSeconds / 60);
+  if (minutes < 1) return "<1m";
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest ? `${hours}h ${String(rest).padStart(2, "0")}m` : `${hours}h`;
+}
+
 export function sanitizeStatusText(text: string): string {
   return text.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim();
 }