pum-agent 0.1.0-beta.3

package/src/explanation-strength.ts

@@ -0,0 +1,47 @@
+import type { InlineExtension } from "@earendil-works/pi-coding-agent";
+
+export const EXPLANATION_STRENGTHS = ["none", "simple", "detailed"] as const;
+export type ExplanationStrength = (typeof EXPLANATION_STRENGTHS)[number];
+
+let currentStrength: ExplanationStrength = "simple";
+
+export const EXPLANATION_PROMPTS: Record<Exclude<ExplanationStrength, "none">, string> = {
+  simple: `## Explanation strength: simple
+
+Use regular assistant output to state briefly what you are doing and why.
+Give concise progress updates before important actions.
+Summarize the result when the work is complete.
+Do not put these explanations only in hidden reasoning.`,
+  detailed: `## Explanation strength: detailed
+
+Use regular assistant output to explain what you are doing and why.
+Explain the plan before implementation.
+Report important actions, decisions, tradeoffs, and validation as the work proceeds.
+Summarize the result and any remaining concerns when the work is complete.
+Do not put these explanations only in hidden reasoning.
+Do not reveal private chain-of-thought. Give useful rationale summaries instead.`,
+};
+
+export function isExplanationStrength(value: unknown): value is ExplanationStrength {
+  return EXPLANATION_STRENGTHS.includes(value as ExplanationStrength);
+}
+
+export function setExplanationStrength(strength: ExplanationStrength): void {
+  currentStrength = strength;
+}
+
+export function getExplanationStrength(): ExplanationStrength {
+  return currentStrength;
+}
+
+export const explanationStrengthExtension: InlineExtension = {
+  name: "pum-explanation-strength",
+  factory(pi) {
+    pi.on("before_agent_start", (event) => {
+      if (currentStrength === "none") return;
+      return {
+        systemPrompt: `${event.systemPrompt}\n\n${EXPLANATION_PROMPTS[currentStrength]}`,
+      };
+    });
+  },
+};

package/src/git-branch.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync, statSync, watch } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * pi has a FooterDataProvider that does this, but only the read-only *type* is
+ * exported from the package root and deep imports are blocked by its exports
+ * map, so PUM reads HEAD itself.
+ */
+function findGitDir(startDir: string): string | null {
+  let dir = resolve(startDir);
+  for (;;) {
+    const dotGit = join(dir, ".git");
+    if (existsSync(dotGit)) {
+      if (statSync(dotGit).isDirectory()) return dotGit;
+      // In a worktree, .git is a file holding "gitdir: <path>".
+      const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"));
+      return match ? resolve(dir, match[1]!.trim()) : null;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function readBranch(cwd: string): string | null {
+  try {
+    const gitDir = findGitDir(cwd);
+    if (!gitDir) return null;
+    const head = readFileSync(join(gitDir, "HEAD"), "utf8").trim();
+    const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
+    return ref ? ref[1]! : "detached";
+  } catch {
+    return null;
+  }
+}
+
+/** Calls back when HEAD changes — a checkout, a commit on a new branch. */
+export function watchBranch(cwd: string, onChange: () => void): () => void {
+  const gitDir = findGitDir(cwd);
+  if (!gitDir) return () => {};
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const watcher = watch(join(gitDir, "HEAD"), () => {
+      clearTimeout(timer);
+      timer = setTimeout(onChange, 100);
+    });
+    return () => {
+      clearTimeout(timer);
+      watcher.close();
+    };
+  } catch {
+    return () => clearTimeout(timer);
+  }
+}

package/src/help-popup.tsx

@@ -0,0 +1,279 @@
+import type { Theme } from "./theme";
+
+type HelpGroup = { title: string; controls: [string, string][] };
+
+export const HELP_SUMMARY_WIDE = [
+  "PUM workflow — prompt or steer · cache prompts · attach images · run managed worktree agents in parallel",
+  "switch transcripts · merge successful agents · persist sessions · use Settings and safety checks",
+] as const;
+
+export const HELP_SUMMARY = [
+  "Prompt or steer. Cache prompts. Attach images.",
+  "Run managed worktree agents in parallel.",
+  "Switch transcripts and merge successful agents.",
+  "Sessions persist. Settings include safety checks.",
+] as const;
+
+/** Shown when `?` is typed into an empty prompt. Keep this list aligned with app.tsx. */
+export const HELP_GROUPS: HelpGroup[] = [
+  {
+    title: "Prompt",
+    controls: [
+      ["Enter", "Send, or steer while working"],
+      ["Ctrl/Shift+Enter", "Insert a new line"],
+      ["\\ then Enter", "Insert a new line fallback"],
+      ["Alt+Enter", "Cache without sending"],
+      ["Ctrl+Alt+Enter", "Cache alias"],
+      ["Alt+V", "Attach a clipboard image"],
+      ["Ctrl+Backspace", "Delete the previous word"],
+    ],
+  },
+  {
+    title: "Cache and agents",
+    controls: [
+      ["Tab", "Open cache, or load selection"],
+      ["Shift+↑ / ↓", "Select cached task range"],
+      ["Delete", "Remove selected cached task"],
+      ["Shift+Tab", "Next agent transcript"],
+      ["Ctrl+Shift+Tab", "Previous agent transcript"],
+      ["Ctrl+L", "Open agent transcript selector"],
+    ],
+  },
+  {
+    title: "History and sessions",
+    controls: [
+      ["↑ / ↓", "Browse prompt history"],
+      ["Ctrl+H", "Open session history"],
+      ["pum -r", "Resume the last session"],
+    ],
+  },
+  {
+    title: "Commands",
+    controls: [
+      ["/compress", "Summarize older context"],
+      ["/clear", "Start a fresh session"],
+      ["/history", "Browse saved sessions"],
+      ["/login", "Add or update a provider"],
+      ["/worktree", "Create a managed worktree"],
+      ["Tab", "Complete a command preview"],
+    ],
+  },
+  {
+    title: "Application",
+    controls: [
+      ["Ctrl+P", "Open Settings"],
+      ["/ in Settings", "Focus settings search"],
+      ["Esc", "Close; twice to cancel work"],
+      ["Ctrl+C", "Press twice to quit"],
+      ["?", "Open or close this help"],
+    ],
+  },
+];
+
+const KEY_WIDTH = 17;
+type HelpLine = { kind: "heading"; text: string } | { kind: "control"; key: string; what: string } | { kind: "blank" };
+
+export function helpLines(terminalHeight: number): HelpLine[] {
+  const gaps = terminalHeight >= 32;
+  return HELP_GROUPS.flatMap((group, groupIndex) => [
+    { kind: "heading" as const, text: group.title },
+    ...group.controls.map(([key, what]) => ({ kind: "control" as const, key, what })),
+    ...(gaps && groupIndex < HELP_GROUPS.length - 1 ? [{ kind: "blank" as const }] : []),
+  ]);
+}
+
+type HelpLayout = {
+  twoColumns: boolean;
+  popupHeight: number;
+  summaryLines: readonly string[];
+  summaryHeight: number;
+  topGap: number;
+  contentHeight: number;
+  bottomGap: number;
+  footerHeight: number;
+};
+
+const POPUP_FRAME_ROWS = 4;
+
+export function helpLayout(terminalWidth: number, terminalHeight: number): HelpLayout {
+  const twoColumns = terminalWidth >= 82;
+  const categorySpacing = terminalHeight >= 32;
+  const desiredHeight = twoColumns ? (categorySpacing ? 30 : 28) : 39;
+  const popupHeight = Math.max(1, Math.min(terminalHeight, desiredHeight));
+  const innerHeight = Math.max(0, popupHeight - POPUP_FRAME_ROWS);
+  const allSummaryLines = twoColumns
+    ? HELP_SUMMARY_WIDE
+    : ["PUM workflow", ...HELP_SUMMARY];
+  const footerHeight = innerHeight >= 1 ? 1 : 0;
+  const minimumContentHeight = innerHeight >= 2 ? 1 : 0;
+  const summaryHeight = Math.min(
+    allSummaryLines.length,
+    Math.max(0, innerHeight - footerHeight - minimumContentHeight),
+  );
+  const fullSummaryFits = summaryHeight === allSummaryLines.length;
+  const gapCapacity = fullSummaryFits
+    ? Math.max(0, innerHeight - summaryHeight - footerHeight - minimumContentHeight)
+    : 0;
+  // Keep the footer separate first when only one compact-layout gap fits.
+  const bottomGap = gapCapacity >= 1 ? 1 : 0;
+  const topGap = gapCapacity >= 2 ? 1 : 0;
+  const contentHeight = Math.max(
+    0,
+    innerHeight - summaryHeight - topGap - bottomGap - footerHeight,
+  );
+
+  return {
+    twoColumns,
+    popupHeight,
+    summaryLines: allSummaryLines.slice(0, summaryHeight),
+    summaryHeight,
+    topGap,
+    contentHeight,
+    bottomGap,
+    footerHeight,
+  };
+}
+
+export function helpPageSize(terminalHeight: number): number {
+  return Math.max(1, helpLayout(0, terminalHeight).contentHeight);
+}
+
+export function maxHelpScrollOffset(terminalHeight: number): number {
+  const lines = helpLines(terminalHeight);
+  const raw = Math.max(0, lines.length - helpPageSize(terminalHeight));
+  const lastHeading = lines.findLastIndex((line) => line.kind === "heading");
+  return lastHeading < 0 ? raw : Math.min(raw, lastHeading);
+}
+
+function HelpLineRow({ line, theme }: { line: HelpLine; theme: Theme }) {
+  if (line.kind === "blank") return <box style={{ height: 1, flexShrink: 0 }} />;
+  if (line.kind === "heading") {
+    return <text content={line.text} fg={theme.dim} bg={theme.popupBg} />;
+  }
+  return (
+    <box style={{ flexDirection: "row", height: 1, flexShrink: 0 }}>
+      <box style={{ width: KEY_WIDTH, flexShrink: 0 }}>
+        <text content={line.key} fg={theme.accent} bg={theme.popupBg} wrapMode="none" />
+      </box>
+      <text
+        content={line.what}
+        fg={theme.fg}
+        bg={theme.popupBg}
+        wrapMode="none"
+        style={{ flexGrow: 1, minWidth: 0 }}
+      />
+    </box>
+  );
+}
+
+function HelpColumn({ groups, theme, spaced }: { groups: HelpGroup[]; theme: Theme; spaced: boolean }) {
+  return (
+    <box style={{ flexDirection: "column", flexGrow: 1, minWidth: 0 }}>
+      {groups.map((group, groupIndex) => (
+        <box key={group.title} style={{ flexDirection: "column", flexShrink: 0, marginBottom: spaced && groupIndex < groups.length - 1 ? 1 : 0 }}>
+          <text content={group.title} fg={theme.dim} bg={theme.popupBg} />
+          {group.controls.map(([key, what], index) => (
+            <box key={`${key}:${index}`} style={{ flexDirection: "row", height: 1, flexShrink: 0 }}>
+              <box style={{ width: KEY_WIDTH, flexShrink: 0 }}>
+                <text content={key} fg={theme.accent} bg={theme.popupBg} wrapMode="none" />
+              </box>
+              <text
+                content={what}
+                fg={theme.fg}
+                bg={theme.popupBg}
+                wrapMode="none"
+                style={{ flexGrow: 1, minWidth: 0 }}
+              />
+            </box>
+          ))}
+        </box>
+      ))}
+    </box>
+  );
+}
+
+export function HelpPopup({
+  theme,
+  terminalWidth,
+  terminalHeight,
+  scrollOffset,
+}: {
+  theme: Theme;
+  terminalWidth: number;
+  terminalHeight: number;
+  scrollOffset: number;
+}) {
+  const layout = helpLayout(terminalWidth, terminalHeight);
+  const margin = terminalWidth < 3
+    ? 0
+    : terminalWidth < 64 ? 1 : Math.max(2, Math.floor(terminalWidth * 0.08));
+  const popupWidth = Math.max(1, terminalWidth - margin * 2);
+  const split = 3;
+  const lines = helpLines(terminalHeight);
+  const spaced = terminalHeight >= 32;
+
+  return (
+    <box
+      title=" Controls "
+      style={{
+        position: "absolute",
+        top: Math.max(0, Math.floor((terminalHeight - layout.popupHeight) / 2)),
+        left: margin,
+        width: popupWidth,
+        height: layout.popupHeight,
+        zIndex: 100,
+        border: true,
+        borderColor: theme.border,
+        backgroundColor: theme.popupBg,
+        flexDirection: "column",
+        padding: 1,
+      }}
+    >
+      <box style={{ height: layout.summaryHeight, flexShrink: 0, flexDirection: "column" }}>
+        {layout.summaryLines.map((line, index) => (
+          <text
+            key={line}
+            content={line}
+            fg={layout.twoColumns || index === 0 ? theme.accent : theme.dim}
+            bg={theme.popupBg}
+            wrapMode="none"
+          />
+        ))}
+      </box>
+      {layout.topGap ? <box style={{ height: 1, flexShrink: 0 }} /> : null}
+      <box
+        style={{
+          flexDirection: "row",
+          height: layout.contentHeight,
+          flexShrink: 0,
+          overflow: "hidden",
+        }}
+      >
+        {layout.twoColumns ? (
+          <>
+            <HelpColumn groups={HELP_GROUPS.slice(0, split)} theme={theme} spaced={spaced} />
+            <box style={{ width: 2, flexShrink: 0 }} />
+            <HelpColumn groups={HELP_GROUPS.slice(split)} theme={theme} spaced={spaced} />
+          </>
+        ) : (
+          <box style={{ flexDirection: "column", flexGrow: 1, minWidth: 0 }}>
+            {lines.slice(scrollOffset, scrollOffset + helpPageSize(terminalHeight)).map((line, index) => (
+              <HelpLineRow key={`${scrollOffset + index}:${line.kind}`} line={line} theme={theme} />
+            ))}
+          </box>
+        )}
+      </box>
+      {layout.bottomGap ? <box style={{ height: 1, flexShrink: 0 }} /> : null}
+      {layout.footerHeight ? (
+        <box style={{ height: 1, flexShrink: 0 }}>
+          <text
+            content={layout.twoColumns ? "esc or ? close" : "↑↓ scroll   esc or ? close"}
+            fg={theme.dim}
+            bg={theme.popupBg}
+            wrapMode="none"
+          />
+        </box>
+      ) : null}
+    </box>
+  );
+}

package/src/history.ts

@@ -0,0 +1,57 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_DIR } from "./config";
+import { projectStorageKey } from "./platform";
+
+/** One history list per working directory, so projects do not bleed together. */
+type HistoryFile = Record<string, string[]>;
+
+const HISTORY_PATH = join(AGENT_DIR, "history.json");
+const MAX_ENTRIES = 500;
+
+function readFile(): HistoryFile {
+  try {
+    const parsed = JSON.parse(readFileSync(HISTORY_PATH, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function loadHistory(cwd: string): string[] {
+  const file = readFile();
+  const entries = file[projectStorageKey(cwd)] ?? file[cwd];
+  return Array.isArray(entries) ? entries.filter((e) => typeof e === "string") : [];
+}
+
+/** Appends unless it repeats the previous entry, and returns the new list. */
+export function appendHistory(cwd: string, prompt: string): string[] {
+  const file = readFile();
+  const key = projectStorageKey(cwd);
+  const list = Array.isArray(file[key]) ? file[key]! : loadHistory(cwd);
+  if (list[list.length - 1] !== prompt) list.push(prompt);
+  const trimmed = list.slice(-MAX_ENTRIES);
+  file[key] = trimmed;
+  if (key !== cwd) delete file[cwd];
+  try {
+    writeFileSync(HISTORY_PATH, JSON.stringify(file, null, 2));
+  } catch {
+    // history is a convenience; never break a turn over it
+  }
+  return trimmed;
+}
+
+/** Remove every exact occurrence of a prompt from this directory's history. */
+export function removeHistory(cwd: string, prompt: string): string[] {
+  const file = readFile();
+  const key = projectStorageKey(cwd);
+  const next = loadHistory(cwd).filter((entry) => entry !== prompt);
+  file[key] = next;
+  if (key !== cwd) delete file[cwd];
+  try {
+    writeFileSync(HISTORY_PATH, JSON.stringify(file, null, 2));
+  } catch {
+    // history is a convenience; never break input handling over it
+  }
+  return next;
+}

package/src/image-paste.ts

@@ -0,0 +1,204 @@
+import type { ImageContent } from "@earendil-works/pi-ai";
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+
+const IMAGE_TYPES = [
+  ["image/png", "png"],
+  ["image/jpeg", "jpg"],
+  ["image/webp", "webp"],
+  ["image/gif", "gif"],
+  ["image/bmp", "bmp"],
+  ["image/tiff", "tiff"],
+] as const;
+
+export type PendingImage = {
+  id: number;
+  marker: string;
+  path: string;
+  mimeType: string;
+  start: number;
+  end: number;
+};
+
+let imageDir: string | null = null;
+let fileSequence = 0;
+
+function ensureImageDir(): string {
+  imageDir ??= mkdtempSync(join(tmpdir(), "pum-images-"));
+  return imageDir;
+}
+
+type CommandRunner = (command: string, args: string[]) => Promise<Buffer>;
+type NativeClipboard = {
+  hasImage(): boolean;
+  getImageBinary(): Promise<Array<number>>;
+};
+
+export type ClipboardBackend = "windows" | "wayland" | "x11";
+
+export function clipboardBackend(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): ClipboardBackend | null {
+  if (platform === "win32") return "windows";
+  if (platform === "linux" && env.WAYLAND_DISPLAY) return "wayland";
+  if (platform === "linux" && env.DISPLAY) return "x11";
+  return null;
+}
+
+function run(command: string, args: string[]): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let size = 0;
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_IMAGE_BYTES) {
+        child.kill();
+        reject(new Error("Clipboard image is larger than 25 MB"));
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve(Buffer.concat(stdout));
+      else reject(new Error(Buffer.concat(stderr).toString("utf8").trim() || `${command} failed`));
+    });
+  });
+}
+
+const WINDOWS_CLIPBOARD_SCRIPT = [
+  "Add-Type -AssemblyName System.Windows.Forms",
+  "Add-Type -AssemblyName System.Drawing",
+  "$image = [System.Windows.Forms.Clipboard]::GetImage()",
+  "if ($null -eq $image) { [Console]::Error.Write('Clipboard does not contain an image'); exit 2 }",
+  "$stream = New-Object System.IO.MemoryStream",
+  "try {",
+  "  $image.Save($stream, [System.Drawing.Imaging.ImageFormat]::Png)",
+  "  $bytes = $stream.ToArray()",
+  "  [Console]::OpenStandardOutput().Write($bytes, 0, $bytes.Length)",
+  "} finally {",
+  "  $stream.Dispose()",
+  "  $image.Dispose()",
+  "}",
+].join("\n");
+
+async function loadNativeClipboard(): Promise<NativeClipboard | null> {
+  try {
+    return await import("@mariozechner/clipboard");
+  } catch {
+    return null;
+  }
+}
+
+async function readWindowsClipboard(
+  runner: CommandRunner,
+  nativeClipboard: NativeClipboard | null | undefined,
+): Promise<{ data: Buffer; mimeType: string; ext: string }> {
+  const clipboard = nativeClipboard === undefined ? await loadNativeClipboard() : nativeClipboard;
+  if (clipboard?.hasImage()) {
+    const bytes = await clipboard.getImageBinary();
+    if (bytes.length > 0) {
+      return { data: Buffer.from(bytes), mimeType: "image/png", ext: "png" };
+    }
+  }
+
+  const data = await runner("powershell.exe", [
+    "-NoLogo",
+    "-NoProfile",
+    "-NonInteractive",
+    "-STA",
+    "-Command",
+    WINDOWS_CLIPBOARD_SCRIPT,
+  ]);
+  if (data.length === 0) throw new Error("Clipboard image is empty");
+  return { data, mimeType: "image/png", ext: "png" };
+}
+
+async function readWaylandClipboard(
+  runner: CommandRunner,
+): Promise<{ data: Buffer; mimeType: string; ext: string }> {
+  const offered = (await runner("wl-paste", ["--list-types"]))
+    .toString("utf8")
+    .split(/\r?\n/)
+    .map((type) => type.trim().toLowerCase());
+  const imageType = IMAGE_TYPES.find(([mimeType]) => offered.includes(mimeType));
+  if (!imageType) throw new Error("Clipboard does not contain an image");
+  const [mimeType, ext] = imageType;
+  const data = await runner("wl-paste", ["--no-newline", "--type", mimeType]);
+  if (data.length === 0) throw new Error("Clipboard image is empty");
+  return { data, mimeType, ext };
+}
+
+async function readX11Clipboard(
+  runner: CommandRunner,
+): Promise<{ data: Buffer; mimeType: string; ext: string }> {
+  const offered = (await runner("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"]))
+    .toString("utf8")
+    .split(/\r?\n/)
+    .map((type) => type.trim().toLowerCase());
+  const imageType = IMAGE_TYPES.find(([mimeType]) => offered.includes(mimeType));
+  if (!imageType) throw new Error("Clipboard does not contain an image");
+  const [mimeType, ext] = imageType;
+  const data = await runner("xclip", ["-selection", "clipboard", "-t", mimeType, "-o"]);
+  if (data.length === 0) throw new Error("Clipboard image is empty");
+  return { data, mimeType, ext };
+}
+
+export async function captureClipboardImage(options: {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  runner?: CommandRunner;
+  nativeClipboard?: NativeClipboard | null;
+} = {}): Promise<{ path: string; mimeType: string }> {
+  const runner = options.runner ?? run;
+  const backend = clipboardBackend(options.platform, options.env);
+  let image: { data: Buffer; mimeType: string; ext: string };
+  if (backend === "windows") {
+    image = await readWindowsClipboard(runner, options.nativeClipboard);
+  }
+  else if (backend === "wayland") image = await readWaylandClipboard(runner);
+  else if (backend === "x11") image = await readX11Clipboard(runner);
+  else throw new Error("No supported graphical clipboard is available");
+
+  const path = join(ensureImageDir(), `image-${++fileSequence}.${image.ext}`);
+  writeFileSync(path, image.data);
+  return { path, mimeType: image.mimeType };
+}
+
+export function imageContent(image: PendingImage): ImageContent {
+  return {
+    type: "image",
+    data: readFileSync(image.path).toString("base64"),
+    mimeType: image.mimeType,
+  };
+}
+
+export function removePendingImage(image: PendingImage): void {
+  try {
+    unlinkSync(image.path);
+  } catch {
+    // The file can already be gone during shutdown or failed-send cleanup.
+  }
+}
+
+export function cleanupPendingImages(): void {
+  if (!imageDir) return;
+  try {
+    rmSync(imageDir, { recursive: true, force: true });
+  } catch {
+    // Temporary image cleanup must not break shutdown.
+  }
+  imageDir = null;
+}