@bugabinga/pi-ext-ghost 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 - 2026-05-21
+
+- a40a427 prepare extensions for npm release
+- 133cb7d chore(pi): migrate extensions to earendil packages
+- db7b1c5 Update agent and terminal configs
+- 5ca1296 Rework Pi agent extensions
+- b045a6b fix(pi/mux): cooldown exhausted keys on provider usage-limit errors
+- b87a61a feat(pi): monorepo workspace — all extensions are proper packages
+- 5fbf178 pi(ext): add remaining extensions (angel, animations, code-actions, files-widget, ghost, git-safe, neko, prune, web, etc.)
+

package/README.md

@@ -0,0 +1,11 @@
+# ghost
+
+Background ghost agent helper for Pi.
+
+Runs a secondary Pi agent session for background analysis and coordination.
+
+## Demo
+
+<!-- demo:advisor_suite:start -->
+![Advisor suite](assets/advisor_suite.gif)
+<!-- demo:advisor_suite:end -->

package/__tests__/config.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultConfig, loadGhostConfig, normalizeGhostConfig } from "../config.ts";
+
+describe("normalizeGhostConfig", () => {
+  it("uses strict defaults for empty config", () => {
+    expect(normalizeGhostConfig()).toEqual(defaultConfig);
+  });
+
+  it("lets project config override global config field by field", () => {
+    const config = normalizeGhostConfig(
+      {
+        model: { provider: "anthropic", id: "global-model" },
+        overlay: {
+          anchor: "top-left",
+          width: "50%",
+          maxHeight: "40%",
+          margin: { top: 1, bottom: 2, left: 3, right: 4 },
+        },
+      },
+      {
+        model: { id: "project-model" },
+        overlay: { width: "90%", margin: { bottom: 9 } },
+      },
+    );
+
+    expect(config).toEqual({
+      model: { provider: "anthropic", id: "project-model" },
+      overlay: {
+        anchor: "top-left",
+        width: "90%",
+        maxHeight: "40%",
+        margin: { top: 1, bottom: 9, left: 3, right: 4 },
+      },
+    });
+  });
+
+  it("rejects invalid anchors, sizes, margins, and model values", () => {
+    const config = normalizeGhostConfig(
+      {
+        model: { provider: "", id: 42 },
+        overlay: {
+          anchor: "bottom",
+          width: "wide",
+          maxHeight: "0%",
+          margin: { top: -1, bottom: Number.NaN, left: "2", right: Infinity },
+        },
+      },
+      {},
+    );
+
+    expect(config).toEqual(defaultConfig);
+  });
+
+  it("accepts every real pi overlay anchor", () => {
+    for (const anchor of [
+      "center",
+      "top-left",
+      "top-center",
+      "top-right",
+      "right-center",
+      "bottom-right",
+      "bottom-center",
+      "bottom-left",
+      "left-center",
+    ]) {
+      expect(normalizeGhostConfig({}, { overlay: { anchor } }).overlay.anchor).toBe(anchor);
+    }
+  });
+
+  it("accepts numeric and percentage sizes only", () => {
+    expect(normalizeGhostConfig({}, { overlay: { width: 72, maxHeight: "33.5%" } }).overlay)
+      .toMatchObject({ width: 72, maxHeight: "33.5%" });
+    expect(normalizeGhostConfig({}, { overlay: { width: 0, maxHeight: -1 } }).overlay)
+      .toMatchObject({
+        width: defaultConfig.overlay.width,
+        maxHeight: defaultConfig.overlay.maxHeight,
+      });
+  });
+
+  it("ignores deleted legacy junk without shaping config", () => {
+    const config = normalizeGhostConfig(
+      {},
+      { documents: ["x"], interval: 10, behavior: { hideOnClose: false } },
+    );
+    expect(config).toEqual(defaultConfig);
+  });
+});
+
+describe("loadGhostConfig", () => {
+  it("reports invalid project JSON instead of silently swallowing it", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "ghost-config-"));
+    const piDir = join(cwd, ".pi");
+    const errors: string[] = [];
+
+    mkdirSync(piDir);
+    writeFileSync(join(piDir, "ghost.json"), "{ nope", "utf-8");
+
+    try {
+      const config = loadGhostConfig(cwd, (error) => errors.push(`${error.path}: ${error.message}`));
+      expect(config).toEqual(defaultConfig);
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toContain("ghost.json");
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+});

package/__tests__/overlay-harness.ts

@@ -0,0 +1,148 @@
+import { expect } from "bun:test";
+import { initTheme, type AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { TUI } from "@earendil-works/pi-tui";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { GhostOverlayComponent } from "../overlay.ts";
+
+initTheme("dark", false);
+
+type Theme = ExtensionCommandContext["ui"]["theme"];
+type MessageStartEvent = Extract<AgentSessionEvent, { type: "message_start" }>;
+type MessageUpdateEvent = Extract<AgentSessionEvent, { type: "message_update" }>;
+type MessageEndEvent = Extract<AgentSessionEvent, { type: "message_end" }>;
+type ToolStartEvent = Extract<AgentSessionEvent, { type: "tool_execution_start" }>;
+type ToolUpdateEvent = Extract<AgentSessionEvent, { type: "tool_execution_update" }>;
+type ToolEndEvent = Extract<AgentSessionEvent, { type: "tool_execution_end" }>;
+
+export interface OverlayHarness {
+  overlay: GhostOverlayComponent;
+  submitted: string[];
+  hiddenCount(): number;
+  closedCount(): number;
+}
+
+export const plainTheme = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+  italic: (text: string) => text,
+  underline: (text: string) => text,
+  inverse: (text: string) => text,
+  strikethrough: (text: string) => text,
+  getFgAnsi: () => "",
+  getBgAnsi: () => "",
+  getColorMode: () => "truecolor",
+  getThinkingBorderColor: () => (text: string) => text,
+  getBashModeBorderColor: () => (text: string) => text,
+} as Theme;
+
+export function createOverlay(rows = 30, columns = 100, maxHeight: `${number}%` | number = "55%"): OverlayHarness {
+  const submitted: string[] = [];
+  let hidden = 0;
+  let closed = 0;
+
+  const overlay = new GhostOverlayComponent({
+    tui: minimalTui(rows, columns),
+    theme: plainTheme,
+    sessionCwd: `${process.env.HOME ?? "/home/me"}/repo/with/a/very/very/very/long/path`,
+    modelLabel: "provider/some-ridiculously-long-model-name-that-must-never-break-render-width",
+    maxHeight,
+    margin: { top: 0, bottom: 1 },
+    onSubmitMessage: (text) => submitted.push(text),
+    onHideOverlay: () => { hidden++; },
+    onCloseOverlay: () => { closed++; },
+  });
+
+  return {
+    overlay,
+    submitted,
+    hiddenCount: () => hidden,
+    closedCount: () => closed,
+  };
+}
+
+export function expectLinesFit(lines: string[], width: number): void {
+  for (const line of lines) expect(visibleWidth(line)).toBeLessThanOrEqual(width);
+}
+
+export function assistantMessage(text: string): AssistantMessage {
+  return {
+    role: "assistant",
+    content: [{ type: "text", text }],
+    api: "test",
+    provider: "test",
+    model: "test",
+    usage: emptyUsage(),
+    stopReason: "stop",
+    timestamp: 0,
+  };
+}
+
+export function userStart(text: string): MessageStartEvent {
+  return {
+    type: "message_start",
+    message: { role: "user", content: [{ type: "text", text }], timestamp: 0 },
+  } as MessageStartEvent;
+}
+
+export function assistantStart(text: string): MessageStartEvent {
+  return { type: "message_start", message: assistantMessage(text) } as MessageStartEvent;
+}
+
+export function assistantUpdate(text: string): MessageUpdateEvent {
+  return { type: "message_update", message: assistantMessage(text) } as MessageUpdateEvent;
+}
+
+export function assistantEnd(text: string): MessageEndEvent {
+  return { type: "message_end", message: assistantMessage(text) } as MessageEndEvent;
+}
+
+export function toolStart(args: unknown = {}): ToolStartEvent {
+  return {
+    type: "tool_execution_start",
+    toolCallId: "tool-1",
+    toolName: "ghost_tool",
+    args,
+  } as ToolStartEvent;
+}
+
+export function toolUpdate(text: string): ToolUpdateEvent {
+  return {
+    type: "tool_execution_update",
+    toolCallId: "tool-1",
+    toolName: "ghost_tool",
+    args: {},
+    partialResult: { content: [{ type: "text", text }] },
+  } as ToolUpdateEvent;
+}
+
+export function toolEnd(text: string): ToolEndEvent {
+  return {
+    type: "tool_execution_end",
+    toolCallId: "tool-1",
+    toolName: "ghost_tool",
+    args: {},
+    result: { content: [{ type: "text", text }] },
+    isError: false,
+  } as ToolEndEvent;
+}
+
+function minimalTui(rows: number, columns: number): TUI {
+  return {
+    terminal: { rows, columns },
+    requestRender: () => {},
+  } as TUI;
+}
+
+function emptyUsage(): AssistantMessage["usage"] {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}

package/__tests__/overlay-render.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "bun:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { extractMessageText, fitLine, formatGhostCwd } from "../overlay.ts";
+import {
+  assistantEnd,
+  assistantMessage,
+  assistantStart,
+  assistantUpdate,
+  createOverlay,
+  expectLinesFit,
+  toolEnd,
+  toolStart,
+  toolUpdate,
+  userStart,
+} from "./overlay-harness.ts";
+
+describe("fitLine", () => {
+  it("truncates and pads to exact visible width", () => {
+    expect(visibleWidth(fitLine("abcdef", 3))).toBe(3);
+    expect(visibleWidth(fitLine("x", 3))).toBe(3);
+    expect(fitLine("x", 0)).toBe("");
+  });
+});
+
+describe("GhostOverlayComponent rendering", () => {
+  it("never emits a line wider than render(width), including brutal tiny widths", () => {
+    for (let rows = 1; rows <= 24; rows++) {
+      for (let width = 0; width <= 120; width++) {
+        const { overlay } = createOverlay(rows, width);
+        overlay.setStatus("status ".repeat(80));
+        const lines = overlay.render(width);
+        expectLinesFit(lines, width);
+        expect(lines.length).toBeLessThanOrEqual(Math.max(1, rows));
+      }
+    }
+  });
+
+  it("keeps all lines fitted after long transcript, tool, status, and input churn", () => {
+    const { overlay } = createOverlay(18, 60);
+    overlay.setStatus("S".repeat(500));
+
+    for (let i = 0; i < 30; i++) {
+      overlay.handleSessionEvent(userStart(`user ${i} ${"u".repeat(120)}`));
+      overlay.handleSessionEvent(assistantStart(`assistant ${i} ${"a".repeat(120)}`));
+      overlay.handleSessionEvent(assistantUpdate(`assistant update ${i} ${"b".repeat(120)}`));
+      overlay.handleSessionEvent(assistantEnd(`assistant end ${i} ${"c".repeat(120)}`));
+    }
+
+    overlay.handleSessionEvent(toolStart({ huge: "x".repeat(200) }));
+    overlay.handleSessionEvent(toolUpdate("partial".repeat(80)));
+    overlay.handleSessionEvent(toolEnd("done".repeat(80)));
+
+    for (const width of [4, 5, 8, 13, 20, 40, 80]) {
+      expectLinesFit(overlay.render(width), width);
+    }
+  });
+
+  it("invalidates transcript cache on assistant streaming updates", () => {
+    const { overlay } = createOverlay(24, 90);
+
+    overlay.handleSessionEvent(assistantStart("first token"));
+    expect(overlay.render(90).join("\n")).toContain("first token");
+
+    overlay.handleSessionEvent(assistantUpdate("second token"));
+    const rendered = overlay.render(90).join("\n");
+
+    expect(rendered).toContain("second token");
+    expect(rendered).not.toContain("first token");
+  });
+
+  it("invalidates transcript cache on partial tool output", () => {
+    const { overlay } = createOverlay(24, 90);
+
+    overlay.handleSessionEvent(toolStart());
+    expect(overlay.render(90).join("\n")).toContain("ghost_tool");
+
+    overlay.handleSessionEvent(toolUpdate("partial-output-visible"));
+    expect(overlay.render(90).join("\n")).toContain("partial-output-visible");
+  });
+
+  it("does not emit shell prompt OSC markers inside overlay transcript", () => {
+    const { overlay } = createOverlay(24, 90);
+
+    overlay.handleSessionEvent(userStart("hi"));
+    overlay.handleSessionEvent(assistantStart("hello"));
+
+    expect(overlay.render(90).join("\n")).not.toContain("\x1b]133;");
+  });
+
+  it("replays events captured while overlay was hidden", () => {
+    const first = createOverlay(24, 90).overlay;
+    const events = [
+      userStart("hidden question"),
+      assistantStart(""),
+      assistantUpdate("hidden partial"),
+      assistantUpdate("hidden final"),
+    ];
+
+    first.loadEvents(events);
+    expect(first.render(90).join("\n")).toContain("hidden final");
+
+    const reopened = createOverlay(24, 90).overlay;
+    reopened.loadEvents(events);
+    const rendered = reopened.render(90).join("\n");
+    expect(rendered).toContain("hidden question");
+    expect(rendered).toContain("hidden final");
+    expect(rendered).not.toContain("hidden partial");
+  });
+
+  it("hydrates prior session messages when reopened", () => {
+    const { overlay } = createOverlay(24, 90);
+
+    overlay.loadMessages([
+      { role: "user", content: [{ type: "text", text: "previous question" }] },
+      assistantMessage("partial prior answer"),
+    ], true);
+
+    expect(overlay.render(90).join("\n")).toContain("previous question");
+    expect(overlay.render(90).join("\n")).toContain("partial prior answer");
+
+    overlay.handleSessionEvent(assistantUpdate("continued prior answer"));
+    const rendered = overlay.render(90).join("\n");
+    expect(rendered).toContain("continued prior answer");
+    expect(rendered).not.toContain("partial prior answer");
+  });
+
+  it("submits trimmed input, hides on ctrl+s, closes on escape", () => {
+    const harness = createOverlay(20, 80);
+
+    for (const char of "  hello ghost  ") harness.overlay.handleInput(char);
+    harness.overlay.handleInput("\r");
+    harness.overlay.handleInput("\x13");
+    harness.overlay.handleInput("\x1b");
+
+    expect(harness.submitted).toEqual(["hello ghost"]);
+    expect(harness.hiddenCount()).toBe(1);
+    expect(harness.closedCount()).toBe(1);
+  });
+});
+
+describe("message/cwd helpers", () => {
+  it("extracts only text content", () => {
+    expect(extractMessageText({
+      content: [
+        { type: "image" },
+        { type: "text", text: "  a  " },
+        { type: "text", text: "b" },
+      ],
+    })).toBe("a  \nb");
+  });
+
+  it("formats home cwd compactly", () => {
+    const home = process.env.HOME;
+    if (!home) return;
+
+    expect(formatGhostCwd(home)).toBe("~");
+    expect(formatGhostCwd(`${home}/repo`)).toBe("~/repo");
+  });
+});

package/config.ts

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OverlayAnchor, OverlayMargin, SizeValue } from "@earendil-works/pi-tui";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const ANCHORS = new Set<OverlayAnchor>([
+  "center",
+  "top-left",
+  "top-center",
+  "top-right",
+  "right-center",
+  "bottom-right",
+  "bottom-center",
+  "bottom-left",
+  "left-center",
+]);
+
+export interface GhostModelConfig {
+  provider?: string;
+  id?: string;
+}
+
+export interface GhostOverlayConfig {
+  anchor: OverlayAnchor;
+  width: SizeValue;
+  maxHeight: SizeValue;
+  margin: Required<OverlayMargin>;
+}
+
+export interface GhostConfig {
+  model?: GhostModelConfig;
+  overlay: GhostOverlayConfig;
+}
+
+export const defaultConfig: GhostConfig = {
+  overlay: {
+    anchor: "bottom-center",
+    width: "100%",
+    maxHeight: "55%",
+    margin: { top: 0, bottom: 1, left: 0, right: 0 },
+  },
+};
+
+type RawConfig = Record<string, unknown>;
+
+export interface GhostConfigError {
+  path: string;
+  message: string;
+}
+
+interface ProjectConfigResult {
+  config: RawConfig;
+  error?: GhostConfigError;
+}
+
+function readProjectConfig(path: string): ProjectConfigResult {
+  if (!existsSync(path)) return { config: {} };
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return isObject(parsed)
+      ? { config: parsed }
+      : { config: {}, error: { path, message: "root must be an object" } };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { config: {}, error: { path, message } };
+  }
+}
+
+function readGlobalGhostConfig(): RawConfig {
+  const path = join(getAgentDir(), "settings.json");
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return isObject(parsed?.ghost) ? parsed.ghost : {};
+  } catch {
+    return {};
+  }
+}
+
+export function loadGhostConfig(
+  cwd: string,
+  onError?: (error: GhostConfigError) => void,
+): GhostConfig {
+  const global = readGlobalGhostConfig();
+  const project = readProjectConfig(join(cwd, ".pi", "ghost.json"));
+  if (project.error) onError?.(project.error);
+  return normalizeGhostConfig(global, project.config);
+}
+
+export function normalizeGhostConfig(global: RawConfig = {}, project: RawConfig = {}): GhostConfig {
+  const globalOverlay = objectValue(global.overlay);
+  const projectOverlay = objectValue(project.overlay);
+  const model = pickModel(objectValue(global.model), objectValue(project.model));
+  const overlay = {
+    anchor: pickAnchor(projectOverlay.anchor, globalOverlay.anchor, defaultConfig.overlay.anchor),
+    width: pickSize(projectOverlay.width, globalOverlay.width, defaultConfig.overlay.width),
+    maxHeight: pickSize(projectOverlay.maxHeight, globalOverlay.maxHeight, defaultConfig.overlay.maxHeight),
+    margin: pickMargin(objectValue(globalOverlay.margin), objectValue(projectOverlay.margin)),
+  };
+
+  return model ? { model, overlay } : { overlay };
+}
+
+function pickModel(global: RawConfig, project: RawConfig): GhostModelConfig | undefined {
+  const provider = pickString(project.provider, global.provider);
+  const id = pickString(project.id, global.id);
+  return provider || id ? { provider, id } : undefined;
+}
+
+function pickMargin(global: RawConfig, project: RawConfig): Required<OverlayMargin> {
+  const fallback = defaultConfig.overlay.margin;
+  return {
+    top: pickNonNegativeNumber(project.top, global.top, fallback.top),
+    bottom: pickNonNegativeNumber(project.bottom, global.bottom, fallback.bottom),
+    left: pickNonNegativeNumber(project.left, global.left, fallback.left),
+    right: pickNonNegativeNumber(project.right, global.right, fallback.right),
+  };
+}
+
+function pickAnchor(...values: unknown[]): OverlayAnchor {
+  for (const value of values) {
+    if (typeof value === "string" && ANCHORS.has(value as OverlayAnchor)) return value as OverlayAnchor;
+  }
+  return defaultConfig.overlay.anchor;
+}
+
+function pickSize(...values: unknown[]): SizeValue {
+  for (const value of values) {
+    if (isSize(value)) return value;
+  }
+  return defaultConfig.overlay.width;
+}
+
+function pickString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return undefined;
+}
+
+function pickNonNegativeNumber(...values: unknown[]): number {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
+  }
+  return 0;
+}
+
+function objectValue(value: unknown): RawConfig {
+  return isObject(value) ? value : {};
+}
+
+function isObject(value: unknown): value is RawConfig {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSize(value: unknown): value is SizeValue {
+  if (typeof value === "number") return Number.isFinite(value) && value > 0;
+  if (typeof value !== "string") return false;
+
+  const match = /^(\d+(?:\.\d+)?)%$/.exec(value);
+  return match !== null && Number(match[1]) > 0;
+}