@leo-alvarenga/pi-zen-frame 0.11.0

package/extensions/components/token-count.ts

@@ -0,0 +1,55 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+import type { SegmentDef } from "./types";
+
+function trimFixed1(n: number): string {
+  const t = n.toFixed(1);
+  return t.endsWith(".0") ? t.slice(0, -2) : t;
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${trimFixed1(n / 1_000_000)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(0)}k`;
+
+  return `${n}`;
+}
+
+function formatWindow(n: number): string {
+  if (n >= 1_000_000) return `${trimFixed1(n / 1_000_000)}M`;
+  return `${(n / 1_000).toFixed(0)}k`;
+}
+
+/** Bottom-left: context window usage (percent + used/window tokens). */
+export const tokenCountSegment: SegmentDef = {
+  id: "token-count",
+  slot: "topRight",
+  enabled: (_d, cfg) => cfg.showContext !== false,
+  render: (d, { border, theme, icons, segColor }) => {
+    const c = d.context;
+    if (!c) return "";
+
+    const pct = c.percent === null ? "?" : `${Math.round(c.percent)}%`;
+    let color: ThemeColor = "muted";
+
+    if (c.percent !== null) {
+      if (c.percent >= 80) {
+        color = "error";
+      } else if (c.percent >= 50) {
+        color = "warning";
+      } else {
+        color = "success";
+      }
+    }
+
+    const used = c.tokens === null ? "?" : formatTokens(c.tokens);
+
+    return (
+      theme.fg(segColor("context", color), ` ${icons.context} ctx ${pct} `) +
+      border("·") +
+      theme.fg(
+        segColor("context", color),
+        ` ${used}/${formatWindow(c.window)} `,
+      )
+    );
+  },
+};

package/extensions/components/types.ts

@@ -0,0 +1,106 @@
+/**
+ * THE COMPONENT CONTRACT.
+ *
+ * A "component" here is a small, isolated piece of the editor frame: Model,
+ * Reasoning, spinner, token count, cwd, agent mode, ... Each lives
+ * in its own file, exports a `SegmentDef`, and is registered in registry.ts.
+ *
+ * Adding a new component = 1 new file + 1 line in the registry. The frame
+ * does all width math, joining and truncation — a segment never sees widths.
+ */
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+
+import type {
+  FrameColors,
+  FrameIcons,
+  FrameSettings,
+  SpinnerPhase,
+} from "../config/types";
+
+/** Where in the frame border a segment renders. */
+export type Slot = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+
+export type AgentConfig = {
+  name: string;
+  icon?: string;
+  color?: ThemeColor;
+};
+
+export type AgentState = {
+  currentAgent: string;
+  currentAgentLabel: string;
+  currentAgentConfig: AgentConfig;
+};
+
+/** Agent-mode state surfaced by pi-agent-manager. */
+export type AgentMode = {
+  name: string;
+  icon?: string;
+  color?: ThemeColor;
+} | null;
+
+/** Live snapshot of everything a segment may want. Rebuilt on every paint. */
+export interface FrameData {
+  cwd: string;
+  gitDirty: number;
+  spinnerFrame: string;
+  accentColor: ThemeColor;
+  gitBranch: string | undefined;
+  modelName: string | undefined;
+  spinnerPhase: SpinnerPhase | null;
+  thinkingLevel: string | undefined;
+
+  /** Master mute: when true, every segment except agentMode renders muted. */
+  zenMode: boolean;
+
+  /** To render the agent mode (from @leo-alvarenga/pi-agent-manager) segment, if any */
+  agentMode: AgentMode;
+
+  context: {
+    window: number;
+    tokens: number | null;
+    percent: number | null;
+  } | null;
+}
+
+/** Data + rendering helpers handed to every segment. */
+export interface SegmentContext {
+  theme: Theme;
+  icons: FrameIcons;
+  cfg: FrameSettings;
+  border: (str: string) => string;
+
+  /** Resolve a segment's fg: zen-mode mutes everything except agentMode;
+   *  else `frame.colors.<key>` supersedes the segment default. */
+  segColor: (key: keyof FrameColors, fallback: ThemeColor) => ThemeColor;
+}
+
+/** A segment renders an already-ANSI-styled string, or "" to render nothing. */
+export type Segment = (d: FrameData, ctx: SegmentContext) => string;
+
+export interface SegmentDef {
+  id: string;
+  slot: Slot;
+  render: Segment;
+  enabled?: (d: FrameData, cfg: FrameSettings) => boolean;
+
+  /** When enabled, this segment replaces everything else in the slot. */
+  replaces?: (d: FrameData, cfg: FrameSettings) => boolean;
+}
+
+/**
+ * Non-editor state the provider assembles on every render. The editor merges
+ * this with its own live state (mode / count / spinner frame) in render().
+ */
+export interface ExternalData {
+  modelName: string | undefined;
+  thinkingLevel: string | undefined;
+  spinnerPhase: SpinnerPhase | null;
+  context: FrameData["context"];
+  cwd: string;
+  gitBranch: string | undefined;
+  gitDirty: number;
+  agentMode: AgentMode;
+  theme: Theme | undefined;
+  zenMode: boolean;
+}

package/extensions/config/constants.ts

@@ -0,0 +1,279 @@
+import { ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { BannerTip, FrameIcons, Settings, SpinnerPhase } from "./types";
+
+export const CONFIG_FILE_NAME = "pi-zen-frame.json";
+
+/** pi-agent-manager integration (optional — no hard dependency). */
+export const PI_AGENT_MANAGER_AGENT_EVENT = "pi-agent-manager:agent-changed";
+export const PI_AGENT_MANAGER_AGENT_DATA_KEY = "pi-agent-manager-agent";
+
+/** Keybinding id users bind in keybindings.json to toggle zen mode. */
+export const ZEN_MODE_SHORTCUT_ID = "piZenFrame.zenMode";
+/** Default key when the user hasn't bound one (override or disable via
+ *  keybindings.json; `[]` disables the shortcut, `/zen_mode` still works). */
+export const ZEN_MODE_DEFAULT_KEY = "ctrl+shift+z";
+
+/** Spinner animation frames per phase (pi-editor-shell style). */
+export const SPINNER_FRAMES: Record<SpinnerPhase, string[]> = {
+  idle: ["⠃", "⠞", "⡵", "⠿", "⢹", "⠄"],
+  outputting: ["⠋", "⠙", "⠸", "⠴", "⠦", "⠇", "⠏"],
+  thinking: ["󰌶", "󰌶", "󰌶", "󰌶", "󰌵", "󰌵", "󰌵", "󰌵"],
+  toolcall: ["●", "●", "●", "●", "○", "○", "○", "○"],
+  exec: ["⠂", "⠅", "⠍", "⠟", "⠿", "⠽", "⠿", "⠟", "⠍", "⠅", "⠂"],
+
+  // Sample ["░", "▒", "▓", "█", "▓", "▒"],
+};
+
+/** Nerd Font defaults (override any subset via `frame.icons`). */
+export const DEFAULT_ICONS: FrameIcons = {
+  model: "󰣖",
+  folder: " ",
+  context: "",
+  gitDirty: "",
+  thinking: "󰌶",
+  gitBranch: "",
+};
+
+/** Thinking level → theme token, mirroring pi's own border-color mapping. */
+export const THINKING_TOKEN: Record<string, string> = {
+  off: "thinkingOff",
+  minimal: "thinkingMinimal",
+  low: "thinkingLow",
+  medium: "thinkingMedium",
+  high: "thinkingHigh",
+  xhigh: "thinkingXhigh",
+  max: "thinkingMax",
+};
+
+/** Rotating messages for the working loader (single-word verbs; some silly, some plausible). */
+export const WORKING_MESSAGES: string[] = [
+  "Exploring",
+  "Tinkering",
+  "Searching",
+  "Polishing",
+  "Herding",
+  "Consulting",
+  "Chasing",
+  "Rearranging",
+  "Sharpening",
+  "Reticulating",
+  "Warming",
+  "Feeding",
+  "Whispering",
+  "Counting",
+  "Dusting",
+  "Tightening",
+  "Watering",
+  "Aligning",
+  "Reading",
+  "Charging",
+  "Summoning",
+  "Calibrating",
+  "Sorting",
+  "Debating",
+  "Brewing",
+  "Stargazing",
+  "Walking",
+  "Folding",
+  "Rounding",
+  "Cooking",
+  "Crunching",
+  "Cogitating",
+  "Analyzing",
+  "Architecting",
+  "Assembling",
+  "Building",
+  "Calculating",
+  "Compiling",
+  "Composing",
+  "Crafting",
+  "Decoding",
+  "Designing",
+  "Drafting",
+  "Editing",
+  "Evaluating",
+  "Experimenting",
+  "Explaining",
+  "Extracting",
+  "Generating",
+  "Integrating",
+  "Iterating",
+  "Juggling",
+  "Mapping",
+  "Measuring",
+  "Merging",
+  "Modeling",
+  "Navigating",
+  "Optimizing",
+  "Organizing",
+  "Parsing",
+  "Planning",
+  "Pondering",
+  "Processing",
+  "Refactoring",
+  "Refining",
+  "Rendering",
+  "Resolving",
+  "Reviewing",
+  "Scanning",
+  "Sifting",
+  "Simulating",
+  "Streamlining",
+  "Structuring",
+  "Synthesizing",
+  "Testing",
+  "Tracing",
+  "Translating",
+  "Triaging",
+  "Unraveling",
+  "Validating",
+  "Verifying",
+  "Wrangling",
+];
+
+export const HEADER_TIPS: BannerTip[] = [
+  {
+    type: "Tip",
+    text: "Press Ctrl + G inside Pi's input box to open your default system $EDITOR (e.g., Neovim) for writing long, complex prompts",
+  },
+  {
+    type: "Did You Know?",
+    text: "Model reasoning quality degrades as the context window fills up. Use /compact or start fresh sessions once context exceeds 50–60%",
+  },
+  {
+    type: "Workflow",
+    text: "Isolate planning from execution: use a read-only profile for architectural planning and switch to full permissions only when building",
+  },
+  {
+    type: "Did You Know?",
+    text: "Modern models like Claude 3.5 and 3.7 process boundaries in XML tags (<context>, <rules>, <code_diff>) significantly better than raw Markdown dividers",
+  },
+  {
+    type: "Tip",
+    text: "Always truncate or filter large log outputs before handing them to an agent—a 10,000-line stack trace will immediately saturate your token cache",
+  },
+  {
+    type: "Tip",
+    text: "Export global environment variables (like $EDITOR and $VISUAL) in ~/.bashenv (or your shell's env file) so background subshells and GUI-spawned processes inherit them cleanly",
+  },
+  {
+    type: "Did You Know?",
+    text: "Smooth 80ms Braille sequences (⠋, ⠙, ⠹, ⠸) or quadrant block meters give immediate visual feedback without consuming much screen real estate",
+  },
+  {
+    type: "Prompting",
+    text: "Tell models what TO DO instead of what NOT to do—negative constraints like 'don't use markdown' are frequently ignored compared to positive instructions",
+  },
+  {
+    type: "Workflow",
+    text: "Use fuzzy file references by typing `@` in Pi's input box to quickly anchor specific codebase files directly into the prompt context",
+  },
+  {
+    type: "Tip",
+    text: "Place heavy longform context or data files near the top of your prompt and put your actual instructions or questions at the very end for better accuracy",
+  },
+  {
+    type: "Did You Know?",
+    text: "Pi saves session history as a tree. You can use `/tree` or `/fork` to branch off a previous point in a conversation to test an alternative approach",
+  },
+  {
+    type: "Prompting",
+    text: "Define specific output formats (e.g., JSON schemas or concise bullet points) upfront to prevent models from generating unnecessary verbose prose",
+  },
+];
+
+export const DEFAULT_SETTINGS: Settings = {
+  zenMode: false,
+  accentColor: "accent",
+
+  header: {
+    enable: false,
+    logoColor: "text",
+    accentColor: "accent",
+
+    heading: "Welcome back!",
+    subheading:
+      "Ready for your next session? Terminal warm, context clean, tools ready to execute",
+
+    logo: ["█████████  ", "███   ███  ", "██████     ", "███     ███"],
+  },
+
+  workingMessage: {
+    enable: true,
+    intervalMs: 3000,
+    messages: WORKING_MESSAGES,
+  },
+
+  frame: {
+    icons: {},
+    paddingX: 1,
+    enable: true,
+    minWidth: 20,
+    marginTop: 0,
+    showCwd: true,
+    paddingTop: 1,
+    marginBottom: 0,
+    showModel: true,
+    paddingBottom: 1,
+    showSpinner: false,
+    showContext: true,
+    showThinking: true,
+    showAgentMode: true,
+    borderColor: "text",
+
+    colors: {},
+    // ponytail: colors were dormant (nothing read them); now wired — keep
+    // defaults unset so segments keep their natural colors and zen-mode is
+    // the mute switch.
+  },
+};
+
+export const THEME_COLORS: Record<ThemeColor, true> = {
+  accent: true,
+  border: true,
+  borderAccent: true,
+  borderMuted: true,
+  success: true,
+  error: true,
+  warning: true,
+  muted: true,
+  dim: true,
+  text: true,
+  searchMatchText: true,
+  thinkingText: true,
+  userMessageText: true,
+  customMessageText: true,
+  customMessageLabel: true,
+  toolTitle: true,
+  toolOutput: true,
+  mdHeading: true,
+  mdLink: true,
+  mdLinkUrl: true,
+  mdCode: true,
+  mdCodeBlock: true,
+  mdCodeBlockBorder: true,
+  mdQuote: true,
+  mdQuoteBorder: true,
+  mdHr: true,
+  mdListBullet: true,
+  toolDiffAdded: true,
+  toolDiffRemoved: true,
+  toolDiffContext: true,
+  syntaxComment: true,
+  syntaxKeyword: true,
+  syntaxFunction: true,
+  syntaxVariable: true,
+  syntaxString: true,
+  syntaxNumber: true,
+  syntaxType: true,
+  syntaxOperator: true,
+  syntaxPunctuation: true,
+  thinkingOff: true,
+  thinkingMinimal: true,
+  thinkingLow: true,
+  thinkingMedium: true,
+  thinkingHigh: true,
+  thinkingXhigh: true,
+  thinkingMax: true,
+  bashMode: true,
+};

package/extensions/config/settings.ts

@@ -0,0 +1,150 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import {
+  CONFIG_FILE_NAME,
+  DEFAULT_SETTINGS,
+  WORKING_MESSAGES,
+} from "./constants";
+import { Settings, FrameColors } from "./types";
+import { isThemeColor } from "../utils";
+
+function getResolvedSettingsFilePath(): string {
+  return join(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+function loadSettingsFile(): Promise<string> {
+  return readFile(getResolvedSettingsFilePath(), "utf8");
+}
+
+/** Validate a raw (possibly malformed) config against the schema shapes. */
+function normalize(raw: unknown): Settings {
+  if (!raw || typeof raw !== "object") return DEFAULT_SETTINGS;
+
+  const num = (v: unknown, fallback: number): number =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0
+      ? Math.floor(v)
+      : fallback;
+
+  const bool = (v: unknown, fallback: boolean | undefined): boolean =>
+    typeof v === "boolean" ? v : (fallback ?? true);
+
+  const str = (v: unknown, fallback: string): string =>
+    typeof v === "string" ? v : fallback;
+
+  const d = DEFAULT_SETTINGS;
+  const r = raw as Record<string, unknown>;
+
+  const out: Settings = {
+    ...DEFAULT_SETTINGS,
+    frame: { ...DEFAULT_SETTINGS.frame },
+    zenMode: bool(r.zenMode, d.zenMode ?? true),
+  };
+
+  if (typeof r.frame === "object" && r.frame) {
+    const f = r.frame as Record<string, unknown>;
+
+    out.frame = {
+      enable: bool(f.enable, d.frame?.enable),
+      minWidth: num(f.minWidth, d.frame?.minWidth ?? 20),
+      paddingTop: num(f.paddingTop, d.frame?.paddingTop ?? 1),
+      paddingBottom: num(f.paddingBottom, d.frame?.paddingBottom ?? 1),
+      paddingX: num(f.paddingX, d.frame?.paddingX ?? 1),
+      marginTop: num(f.marginTop, d.frame?.marginTop ?? 0),
+      marginBottom: num(f.marginBottom, d.frame?.marginBottom ?? 0),
+      showModel: bool(f.showModel, d.frame?.showModel),
+      showThinking: bool(f.showThinking, d.frame?.showThinking),
+      showContext: bool(f.showContext, d.frame?.showContext),
+      showCwd: bool(f.showCwd, d.frame?.showCwd),
+      showAgentMode: bool(f.showAgentMode, d.frame?.showAgentMode),
+      showSpinner: bool(f.showSpinner, d.frame?.showSpinner),
+      icons:
+        typeof f.icons === "object" && f.icons
+          ? { ...d.frame?.icons, ...(f.icons as Record<string, unknown>) }
+          : d.frame?.icons,
+      borderColor:
+        typeof f.borderColor === "string" &&
+        (isThemeColor(f.borderColor) || f.borderColor === "agentMode")
+          ? f.borderColor
+          : (d.frame?.borderColor ?? "border"),
+
+      colors:
+        typeof f.colors === "object" && f.colors
+          ? (Object.fromEntries(
+              Object.entries(f.colors as Record<string, unknown>).filter(
+                ([, v]) => typeof v === "string" && isThemeColor(v),
+              ),
+            ) as Partial<FrameColors>)
+          : d.frame?.colors,
+
+      prefix:
+        typeof f.prefix === "string" ? f.prefix : (d.frame?.prefix ?? "❯"),
+
+      prefixColor:
+        typeof f.prefixColor === "string" &&
+        (f.prefixColor === "agentMode" ||
+          f.prefixColor === "frameBorder" ||
+          isThemeColor(f.prefixColor))
+          ? f.prefixColor
+          : d.frame?.prefixColor, // unset → text
+    };
+  }
+
+  if (typeof r.header === "object" && r.header) {
+    const h = r.header as Record<string, unknown>;
+
+    out.header = {
+      enable: bool(h.enable, d.header?.enable),
+      heading: str(h.heading, d.header?.heading ?? ""),
+      subheading: str(h.subheading, d.header?.subheading ?? ""),
+      logoColor:
+        typeof h.logoColor === "string" && isThemeColor(h.logoColor)
+          ? h.logoColor
+          : (d.header?.logoColor ?? "accent"),
+      accentColor:
+        typeof h.accentColor === "string" && isThemeColor(h.accentColor)
+          ? h.accentColor
+          : (d.header?.accentColor ?? "accent"),
+      logo:
+        Array.isArray(h.logo) && h.logo.every((x) => typeof x === "string")
+          ? (h.logo as string[])
+          : (d.header?.logo ?? []),
+    };
+  }
+
+  if (typeof r.accentColor === "string" && isThemeColor(r.accentColor)) {
+    out.accentColor = r.accentColor || d.accentColor;
+  }
+
+  if (typeof r.workingMessage === "object" && r.workingMessage) {
+    const wm = r.workingMessage as Record<string, unknown>;
+
+    out.workingMessage = {
+      enable:
+        typeof wm.enable === "boolean"
+          ? wm.enable
+          : (d.workingMessage?.enable ?? true),
+      intervalMs: num(wm.intervalMs, d.workingMessage?.intervalMs ?? 3000),
+      messages:
+        Array.isArray(wm.messages) &&
+        wm.messages.length > 0 &&
+        wm.messages.every((m) => typeof m === "string")
+          ? (wm.messages as string[])
+          : (d.workingMessage?.messages ??
+            (wm?.enable === true ? WORKING_MESSAGES : [])),
+    };
+  }
+
+  return out;
+}
+
+export async function loadSettings(): Promise<Settings> {
+  try {
+    const raw = JSON.parse(await loadSettingsFile()) as unknown;
+    return normalize(raw);
+  } catch {
+    return DEFAULT_SETTINGS;
+  }
+}

package/extensions/config/types.ts

@@ -0,0 +1,115 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** Streaming phase used to drive the status-animation spinner. */
+export type SpinnerPhase =
+  "thinking" | "outputting" | "toolcall" | "exec" | "idle";
+
+export interface BannerTip {
+  type: "Tip" | "Did You Know?" | "Workflow" | "Prompting";
+  text: string;
+}
+
+export interface FrameColors {
+  border: ThemeColor;
+  background: ThemeColor;
+  cwd: ThemeColor;
+  model: ThemeColor;
+  context: ThemeColor;
+  thinking: ThemeColor;
+  agentMode: ThemeColor;
+}
+
+/** Nerd-font / glyph icons shown in the frame border. Each is overridable. */
+export interface FrameIcons {
+  folder: string;
+  model: string;
+  context: string;
+  thinking: string;
+  gitDirty: string;
+  gitBranch: string;
+}
+
+/**
+ * ``frame`` — the rounded-corner shell look. Padding values are plain
+ * numbers (>= 0): paddingTop/paddingBottom are blank lines shown *inside*
+ * the box above/below the content.
+ */
+export interface FrameSettings {
+  enable?: boolean;
+
+  /** Below this terminal width the frame is skipped entirely (passthrough) */
+  minWidth?: number;
+
+  /** Blank lines inside the box above the content. Default 1. */
+  paddingTop?: number;
+
+  /** Blank lines inside the box below the content. Default 1. */
+  paddingBottom?: number;
+
+  /** Horizontal inner padding for the content rows. Default 1. */
+  paddingX?: number;
+
+  /** Blank rows OUTSIDE the box, above its top border. Default 0. */
+  marginTop?: number;
+
+  /** Blank rows OUTSIDE the box, below its bottom border. Default 0. */
+  marginBottom?: number;
+
+  showCwd?: boolean;
+  showModel?: boolean;
+  showContext?: boolean;
+  showThinking?: boolean;
+  showAgentMode?: boolean;
+
+  /** Show the status-animation spinner segment while streaming. Default false. */
+  showSpinner?: boolean;
+
+  icons?: Partial<FrameIcons>;
+  colors?: Partial<FrameColors>;
+
+  /** ThemeColor used as the fg for all editor border characters; If set to `"agentMode"`, will follow the current Agent color. Default "border". */
+  borderColor?: ThemeColor | "agentMode";
+
+  /** Text shown before the editor content. Default "❯". */
+  prefix?: string;
+
+  /** ThemeColor used as the fg for the prefix text; If set to `"agentMode"`, will follow the current Agent color;
+   * If set to `"frameBorder"`, will follow the border color. Default: text color. */
+  prefixColor?: "agentMode" | "frameBorder" | ThemeColor;
+}
+
+/** `header` — the top-line header, which can show a logo or other text */
+export interface HeaderSettings {
+  logo: string[];
+  enable: boolean;
+  heading: string;
+  subheading: string;
+  logoColor: ThemeColor;
+  accentColor: ThemeColor;
+}
+
+/** `workingMessage` — rotating messages in pi's built-in working loader. */
+export interface WorkingMessageSettings {
+  /** Toggle the rotating messages. Default true. */
+  enable?: boolean;
+
+  /** How often (ms) the message is replaced. Default 3000. */
+  intervalMs?: number;
+
+  /** Custom message pool; replaces the default 30. */
+  messages?: string[];
+}
+
+export interface Settings {
+  frame?: FrameSettings;
+  header?: HeaderSettings;
+  workingMessage?: WorkingMessageSettings;
+
+  /** Master mute: every segment except agent-mode renders muted.
+   *  Default true. Toggle at runtime with `/zen_mode` or the `piZenFrame.zenMode`
+   *  keybinding (default `ctrl+shift+z`). */
+  zenMode?: boolean;
+
+  /** Accent color for the frame border and other highlights; Defaults to 'accent' */
+  accentColor?: ThemeColor;
+}