pum-agent 0.1.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugen1763
+
+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,196 @@
+<div align="center">
+
+# PUM
+
+**A compact coding agent for the terminal.**
+
+Plan, edit, run commands, review Markdown, and coordinate parallel Git worktrees without leaving the TUI.
+
+[![CI](https://github.com/eugen1763/Pum/actions/workflows/ci.yml/badge.svg)](https://github.com/eugen1763/Pum/actions/workflows/ci.yml)
+[![npm beta](https://img.shields.io/npm/v/pum-agent/beta?label=npm%20beta)](https://www.npmjs.com/package/pum-agent)
+[![License: MIT](https://img.shields.io/github/license/eugen1763/Pum)](LICENSE)
+[![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun&logoColor=14151a)](https://bun.sh)
+
+</div>
+
+> [!WARNING]
+> PUM can read, write, and delete files. PUM can also run shell commands without approval. Start PUM only inside a workspace where these actions are acceptable. Check mode adds a verifier, but it is not a sandbox.
+
+## See PUM in action
+
+The following screens are real OpenTUI renders captured through `tmux`. A local mock provider supplied the model output.
+
+![PUM transcript showing Markdown and a read tool call](docs/images/pum-transcript.svg)
+
+<details>
+<summary><strong>Settings panel</strong></summary>
+
+![PUM settings panel](docs/images/pum-settings.svg)
+
+</details>
+
+## Why PUM
+
+- **Compact terminal UI:** Streaming Markdown, syntax highlighting, thinking traces, tool rows, usage, cost, and Git status.
+- **Full coding loop:** Built-in `read`, `write`, `edit`, `bash`, and atomic `apply_patch` tools.
+- **Parallel subagents:** Persistent agents work in isolated Git worktrees and report to the main agent.
+- **Prompt control:** Steer active work, stash prompt batches, attach clipboard images, cancel turns, and resume sessions.
+- **Provider choice:** Use the login methods exposed by pi, or add an OpenAI-compatible custom endpoint.
+- **Optional safeguards:** Enable fail-closed Check mode for `bash`, `edit`, and `apply_patch` calls.
+- **Terminal-first appearance:** Nine themes, semantic color overrides, Unicode glyphs, and optional animation.
+
+PUM uses [pi](https://github.com/earendil-works/pi) for the agent loop and [OpenTUI](https://github.com/anomalyco/opentui) for rendering.
+
+## Requirements
+
+- [Bun](https://bun.sh)
+- Git
+- An interactive terminal with ANSI/VT and Unicode support
+- Credentials for a supported provider, or an OpenAI-compatible endpoint
+
+Linux and macOS are the primary environments. Windows CI checks the code and Windows path behavior. Native Windows TUI operation remains provisional because it has not been fully validated in a Windows terminal.
+
+On Windows, install Git for Windows. Ensure that `bash.exe` is in `PATH` or remains in its standard location. Use Windows Terminal with PowerShell. Do not use PowerShell ISE.
+
+## Install and start
+
+### Install from source
+
+```bash
+git clone https://github.com/eugen1763/Pum.git
+cd Pum
+bun install --frozen-lockfile
+bun run login
+bun run start
+```
+
+PUM opens the login panel automatically when no provider is available. Use `/login` later to add or update a provider.
+
+Resume the latest session for the current directory:
+
+```bash
+bun run start -r
+```
+
+### Install the beta package
+
+```bash
+bun i -g pum-agent@beta
+pum
+```
+
+The package is named `pum-agent` because the bare `pum` name is already owned. The installed command is still `pum`.
+
+## Essential controls
+
+| Key | Action |
+|---|---|
+| `Enter` | Send a prompt, or steer the selected working agent |
+| `Ctrl+Enter` / `Shift+Enter` | Insert a new line |
+| `Alt+Enter` | Stash the prompt without sending |
+| `Tab` | Open the prompt stash on an empty input |
+| `Shift+↑` / `Shift+↓` | Select a range of stashed tasks |
+| `Alt+V` | Attach an image from the graphical clipboard |
+| `Ctrl+L` | Open the agent transcript selector |
+| `Shift+Tab` / `Ctrl+Shift+Tab` | Cycle through agent transcripts |
+| `Ctrl+H` | Open session history when the terminal reports the key distinctly |
+| `Ctrl+P` | Open settings |
+| `Esc` twice | Cancel the selected working agent |
+| `Ctrl+C` twice | Quit |
+| `?` | Show all controls when the prompt is empty |
+
+Useful commands include `/login`, `/history`, `/clear`, `/compress`, and `/worktree`.
+
+## Parallel subagents
+
+PUM can run up to five active subagents. Each subagent has these resources:
+
+- A persistent pi session
+- An isolated branch and worktree under `.pum/worktrees`
+- Its own transcript, draft, usage data, and cancellation state
+- Tools for progress messages and a single final completion report
+
+Select a range of stashed prompts and press `Enter`. The main agent can group related work and run independent groups in parallel. Successful managed merges remove the completed worktree and branch.
+
+Use `Ctrl+L` to select an agent transcript. Input then goes to that agent. Finished or interrupted agents remain available until PUM merges or removes them.
+
+## Tools and safeguards
+
+### Atomic `apply_patch`
+
+`apply_patch` supports add, update, delete, move, multiple files, and multiple hunks. PUM validates the full patch before changing files. It rejects traversal, absolute paths, escaping symlinks, path conflicts, and ambiguous context. A failed commit restores all touched files.
+
+### Check mode
+
+Enable Check mode in `Ctrl+P`. PUM sends each proposed `bash`, `edit`, or `apply_patch` call to a separate verifier model. The verifier must return a clear `SAFE` decision. Errors, timeouts, unclear replies, and explicit rejections block the tool.
+
+PUM caches only a narrow set of accepted read-only Git inspection commands. It never caches mutation checks. Check mode is off by default and does not replace isolation, backups, or code review.
+
+### Hosted web search
+
+Web search is on by default for supported OpenAI Codex providers. Searches appear as transcript tool rows and persist in resumed sessions. Other providers continue without the hosted search tool. Disable web search in `Ctrl+P`.
+
+### Themes and Markdown
+
+PUM includes `tokyonight`, `gruvbox`, `catppuccin`, `nord`, `dracula`, `rosepine`, `solarized`, `kanagawa`, and `github-light`. Select a preset in `Ctrl+P`.
+
+Create `theme.json` in the PUM config directory to override semantic tokens:
+
+```json
+{
+  "accent": "#ff7a93",
+  "userBg": "#2a2f45"
+}
+```
+
+Markdown renders while streaming. OpenTUI provides syntax parsers for JavaScript, TypeScript, Zig, and Markdown. Other fenced languages still render as code blocks without syntax colors.
+
+## Configuration and data
+
+Set `PUM_DIR` to override the complete PUM data directory.
+
+| Platform | Default directory |
+|---|---|
+| Linux | `$XDG_CONFIG_HOME/pum` or `~/.config/pum` |
+| macOS | `~/Library/Application Support/pum` |
+| Windows | `%LOCALAPPDATA%\pum`, with `%APPDATA%\pum` as fallback |
+
+| Path | Purpose |
+|---|---|
+| `auth.json` | Provider credentials and custom-provider keys |
+| `models.json` | Custom endpoints and model metadata; submitted keys are not stored here |
+| `settings.json` | Model and thinking level managed by pi |
+| `pum.json` | Theme, animation, search, writing, explanation, and check settings |
+| `theme.json` | Optional semantic color overrides |
+| `history.json` | Prompt history by working directory |
+| `prompt-stash.json` | Stashed prompts by working directory |
+| `sessions/` | Main conversation sessions |
+| `subagents/` | Persistent subagent sessions |
+| `check-mode-cache.json` | Accepted checks for eligible read-only Git commands |
+
+PUM keeps this directory separate from pi's default configuration directory.
+
+## Development
+
+```bash
+bun install --frozen-lockfile
+bun test
+bun run typecheck
+git diff --check
+```
+
+Run the TUI from the repository root:
+
+```bash
+bun run start
+```
+
+Use a throwaway `PUM_DIR` for local integration tests. Capture TUI output through `tmux`; do not pipe standard output. See [AGENTS.md](AGENTS.md) for architecture, locked decisions, and TUI test guidance.
+
+## Release status
+
+PUM `0.1` is in beta. Interfaces and persisted formats can still change before the stable release. Review the release notes before upgrading sessions or custom configuration.
+
+## License
+
+PUM is available under the [MIT License](LICENSE).

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "pum-agent",
+  "version": "0.1.0-beta.3",
+  "description": "A compact terminal coding agent powered by pi and OpenTUI.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eugen1763/Pum.git"
+  },
+  "homepage": "https://github.com/eugen1763/Pum#readme",
+  "bugs": {
+    "url": "https://github.com/eugen1763/Pum/issues"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "terminal",
+    "tui",
+    "bun",
+    "opentui"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "pum": "src/index.tsx"
+  },
+  "scripts": {
+    "start": "bun run src/index.tsx",
+    "login": "bun run src/index.tsx login",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "pack:check": "bun run scripts/validate-pack.ts"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@opentui/core": "^0.5.1",
+    "@opentui/react": "^0.5.1",
+    "react": "^19.2.8",
+    "react-devtools-core": "^7.0.1",
+    "typebox": "^1.3.7",
+    "ws": "^8.21.3"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "0.3.9"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.2.18"
+  }
+}

package/src/agent-selector.tsx

@@ -0,0 +1,217 @@
+import { StyledText, type ScrollBoxRenderable } from "@opentui/core";
+import { useTerminalDimensions } from "@opentui/react";
+import { useEffect, useRef } from "react";
+import { normalizeAgentUsage } from "./agent-usage";
+import {
+  fitStatusMetadata,
+  statusMetadataChunks,
+  statusMetadataItems,
+  statusMetadataWidth,
+  type StatusMetadataValues,
+} from "./status-metadata";
+import type { Theme } from "./theme";
+import type { SubagentSnapshot } from "./subagents/types";
+
+export type AgentTreeRow = {
+  id: string | null;
+  name: string;
+  status?: SubagentSnapshot["status"];
+  depth: number;
+  metadata?: StatusMetadataValues;
+};
+
+export type AgentSelectorRowLayout = {
+  indent: number;
+  label: string;
+  labelWidth: number;
+  metadata: ReturnType<typeof statusMetadataItems>;
+  metadataWidth: number;
+};
+
+export function agentSelectorRowLayout(
+  row: AgentTreeRow,
+  popupColumns: number,
+): AgentSelectorRowLayout {
+  const indent = Math.min(2 + row.depth * 2, Math.max(2, popupColumns - 12));
+  // One column remains clear for the pinned scrollbar.
+  const contentColumns = Math.max(1, popupColumns - indent - 1);
+  const label = row.status ? `${row.name} · ${row.status}` : row.name;
+  const minimumLabelWidth = Math.min(
+    label.length,
+    Math.max(8, Math.ceil(contentColumns * 0.45)),
+  );
+  const availableMetadataWidth = Math.max(0, contentColumns - minimumLabelWidth - 2);
+  const metadata = fitStatusMetadata(
+    row.metadata ? statusMetadataItems(row.metadata) : [],
+    availableMetadataWidth,
+  );
+  const metadataWidth = statusMetadataWidth(metadata);
+  const labelWidth = Math.max(1, contentColumns - (metadataWidth ? metadataWidth + 2 : 0));
+  return { indent, label, labelWidth, metadata, metadataWidth };
+}
+
+export function buildAgentTree(agents: readonly SubagentSnapshot[]): AgentTreeRow[] {
+  const children = new Map<string | null, SubagentSnapshot[]>();
+  const ids = new Set(agents.map((agent) => agent.id));
+  for (const agent of agents) {
+    const parent = agent.parentAgentId && ids.has(agent.parentAgentId)
+      ? agent.parentAgentId
+      : null;
+    children.set(parent, [...(children.get(parent) ?? []), agent]);
+  }
+  for (const values of children.values()) values.sort((a, b) => a.startedAt - b.startedAt);
+
+  const rows: AgentTreeRow[] = [{ id: null, name: "main", depth: 0 }];
+  const seen = new Set<string>();
+  const visit = (parentId: string | null, depth: number) => {
+    for (const agent of children.get(parentId) ?? []) {
+      if (seen.has(agent.id)) continue;
+      seen.add(agent.id);
+      const usage = normalizeAgentUsage(agent.usage);
+      rows.push({
+        id: agent.id,
+        name: agent.name,
+        status: agent.status,
+        depth,
+        metadata: {
+          branch: agent.worktree.branch ?? null,
+          outgoingTokens: usage.outgoing,
+          incomingTokens: usage.incoming,
+          cacheReadTokens: usage.cacheRead,
+          cost: usage.cost,
+          contextPct: usage.contextPct,
+        },
+      });
+      visit(agent.id, depth + 1);
+    }
+  };
+  visit(null, 1);
+  // A corrupt parent cycle must not hide a retained agent.
+  for (const agent of agents) {
+    if (seen.has(agent.id)) continue;
+    const usage = normalizeAgentUsage(agent.usage);
+    rows.push({
+      id: agent.id,
+      name: agent.name,
+      status: agent.status,
+      depth: 1,
+      metadata: {
+        branch: agent.worktree.branch ?? null,
+        outgoingTokens: usage.outgoing,
+        incomingTokens: usage.incoming,
+        cacheReadTokens: usage.cacheRead,
+        cost: usage.cost,
+        contextPct: usage.contextPct,
+      },
+    });
+  }
+  return rows;
+}
+
+export function moveAgentSelection(current: number, count: number, direction: -1 | 1): number {
+  if (count <= 0) return 0;
+  return (current + direction + count) % count;
+}
+
+export function AgentSelectorPopup({
+  theme,
+  rows,
+  cursor,
+}: {
+  theme: Theme;
+  rows: readonly AgentTreeRow[];
+  cursor: number;
+}) {
+  const { width, height } = useTerminalDimensions();
+  const scrollRef = useRef<ScrollBoxRenderable>(null);
+  const narrow = width < 50;
+  const popupWidth = narrow ? Math.max(12, width - 2) : Math.floor(width * 0.7);
+  const popupColumns = Math.max(8, popupWidth - 5);
+  const popupHeight = Math.min(
+    rows.length + (narrow ? 10 : 7),
+    Math.max(7, Math.floor(height * (narrow ? 0.85 : 0.7))),
+  );
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      scrollRef.current?.scrollChildIntoView(`agent-tree-${cursor}`);
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [cursor]);
+
+  return (
+    <box
+      title=" Agents "
+      style={{
+        position: "absolute",
+        top: narrow ? 1 : "15%",
+        left: narrow ? 1 : "15%",
+        width: popupWidth,
+        height: popupHeight,
+        zIndex: 100,
+        border: true,
+        borderColor: theme.border,
+        backgroundColor: theme.popupBg,
+        flexDirection: "column",
+        padding: 1,
+      }}
+    >
+      <scrollbox
+        ref={scrollRef}
+        style={{ flexGrow: 1, minHeight: 1 }}
+        verticalScrollbarOptions={{ visible: true }}
+      >
+        <box style={{ flexDirection: "column", width: "100%", flexShrink: 0 }}>
+          {rows.map((row, index) => {
+            const selected = index === cursor;
+            const layout = agentSelectorRowLayout(row, popupColumns);
+            return (
+              <box
+                id={`agent-tree-${index}`}
+                key={row.id ?? "main"}
+                style={{
+                  flexDirection: "row",
+                  width: "100%",
+                  flexShrink: 0,
+                  backgroundColor: selected ? theme.selectionBg : theme.popupBg,
+                }}
+              >
+                <box style={{ width: layout.indent, height: 1, flexShrink: 0 }}>
+                  {selected ? <text content="› " fg={theme.accent} bg={theme.selectionBg} /> : null}
+                </box>
+                <text
+                  content={layout.label}
+                  fg={selected ? theme.fg : theme.dim}
+                  bg={selected ? theme.selectionBg : theme.popupBg}
+                  wrapMode="none"
+                  style={{ width: layout.labelWidth, height: 1, flexShrink: 0 }}
+                />
+                {layout.metadataWidth ? (
+                  <>
+                    <box style={{ width: 2, height: 1, flexShrink: 0 }} />
+                    <text
+                      content={new StyledText(statusMetadataChunks(layout.metadata, theme))}
+                      bg={selected ? theme.selectionBg : theme.popupBg}
+                      wrapMode="none"
+                      style={{ width: layout.metadataWidth, height: 1, flexShrink: 0 }}
+                    />
+                  </>
+                ) : null}
+                {/* Reserve the pinned scrollbar column so it cannot cover text. */}
+                <box style={{ width: 1, height: 1, flexShrink: 0 }} />
+              </box>
+            );
+          })}
+        </box>
+      </scrollbox>
+      <box style={{ height: 1, flexShrink: 0 }} />
+      <text
+        content="↑↓ select   →/enter open   esc close"
+        fg={theme.dim}
+        bg={theme.popupBg}
+        wrapMode="word"
+        style={{ flexShrink: 0, width: "100%" }}
+      />
+    </box>
+  );
+}

package/src/agent-usage.ts

@@ -0,0 +1,93 @@
+import type { Usage } from "@earendil-works/pi-ai";
+
+export type AgentUsage = {
+  /** Tokens PUM sent to the model, including tokens written to a provider cache. */
+  outgoing: number;
+  /** Tokens generated by the model. Pi includes reported reasoning tokens here. */
+  incoming: number;
+  /** Prompt tokens served from a provider cache. */
+  cacheRead: number;
+  cost: number;
+  contextPct: number | null;
+};
+
+export const emptyAgentUsage = (): AgentUsage => ({
+  outgoing: 0,
+  incoming: 0,
+  cacheRead: 0,
+  cost: 0,
+  contextPct: null,
+});
+
+/** Convert retained pre-metric usage records without discarding their token total. */
+export function normalizeAgentUsage(value: unknown): AgentUsage {
+  if (!value || typeof value !== "object") return emptyAgentUsage();
+  const usage = value as Record<string, unknown>;
+  const cost = typeof usage.cost === "number" ? usage.cost : 0;
+  const contextPct = typeof usage.contextPct === "number" ? usage.contextPct : null;
+  if (
+    typeof usage.outgoing === "number" ||
+    typeof usage.incoming === "number" ||
+    typeof usage.cacheRead === "number"
+  ) {
+    return {
+      outgoing: typeof usage.outgoing === "number" ? usage.outgoing : 0,
+      incoming: typeof usage.incoming === "number" ? usage.incoming : 0,
+      cacheRead: typeof usage.cacheRead === "number" ? usage.cacheRead : 0,
+      cost,
+      contextPct,
+    };
+  }
+
+  // Legacy records stored only totalTokens. The exact split is unavailable.
+  // Keep the total visible as outgoing until a retained session can rebuild it.
+  return {
+    outgoing: typeof usage.tokens === "number" ? usage.tokens : 0,
+    incoming: 0,
+    cacheRead: 0,
+    cost,
+    contextPct,
+  };
+}
+
+type TurnUsage = Partial<Omit<Usage, "cost">> & {
+  cost?: Partial<Usage["cost"]>;
+};
+
+export function addTurnUsage(
+  current: AgentUsage,
+  usage: TurnUsage | undefined,
+  contextWindow: number | undefined,
+): AgentUsage {
+  if (!usage) return current;
+  const input = usage.input ?? 0;
+  const output = usage.output ?? 0;
+  const cacheRead = usage.cacheRead ?? 0;
+  const cacheWrite = usage.cacheWrite ?? 0;
+  const promptTokens = input + cacheRead + cacheWrite;
+  return {
+    outgoing: current.outgoing + input + cacheWrite,
+    incoming: current.incoming + output,
+    cacheRead: current.cacheRead + cacheRead,
+    cost: current.cost + (usage.cost?.total ?? 0),
+    contextPct: contextWindow
+      ? Math.min(100, Math.round((promptTokens / contextWindow) * 100))
+      : null,
+  };
+}
+
+export function usageFromEntries(
+  entries: readonly any[],
+  contextWindow: number | undefined,
+): AgentUsage {
+  let result = emptyAgentUsage();
+  for (const entry of entries) {
+    const usage = entry?.type === "message" && entry.message?.role === "assistant"
+      ? entry.message.usage
+      : (entry?.type === "compaction" || entry?.type === "branch_summary")
+        ? entry.usage
+        : undefined;
+    if (usage) result = addTurnUsage(result, usage, contextWindow);
+  }
+  return result;
+}