pum-agent 0.2.27-beta.1 → 0.2.28-beta.1

package/README.md

@@ -4,7 +4,7 @@
 
 **A compact coding agent for the terminal.**
 
-Plan, edit, run commands, review Markdown, and coordinate parallel Git worktrees without leaving the TUI.
+Plan, edit, run commands, review Markdown, and coordinate parallel subagents 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)
@@ -51,8 +51,9 @@ drives the actual TUI and converts the captured cells to SVG.
 ## What it does
 
 - **A full coding loop** — `read`, `write`, `edit`, and `bash`, with streaming Markdown, syntax highlighting, usage, cost, and Git status.
-- **Parallel subagents** — persistent agents in isolated Git worktrees that message each other durably and report to their spawner. See [Subagents](docs/subagents.md).
+- **Parallel subagents** — persistent agents that share the project by default, with optional isolated Git worktrees. They message each other durably and report to their spawner. See [Subagents](docs/subagents.md).
 - **Goals that outlive a turn** — `/goal` keeps working, reviewed after each turn by a judge that reads but never writes. See [Goals](docs/goals.md).
+- **Project memory across sessions** — the main agent maintains private Markdown facts that follow linked Git worktrees. See [Tools](docs/tools.md#project-memory).
 - **Supervised processes** — background shells and external triggers such as `gh run watch`, which wake the exact agent that was waiting. See [Tools](docs/tools.md).
 - **Layered safeguards** — a path guard on the file tools, deterministic Check mode, and a native OS sandbox for the processes the model starts. See [Safety](docs/security.md).
 - **A terminal-first look** — nine themes, semantic colour overrides, and optional animation. See [Appearance](docs/appearance.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.2.27-beta.1",
+  "version": "0.2.28-beta.1",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",

package/src/agent-selector.tsx

@@ -18,6 +18,7 @@ export type AgentTreeRow = {
   name: string;
   status?: SubagentSnapshot["status"];
   readonly?: boolean;
+  shared?: boolean;
   depth: number;
   metadata?: StatusMetadataValues;
 };
@@ -38,7 +39,7 @@ export function agentSelectorRowLayout(
   // One column remains clear for the pinned scrollbar.
   const contentColumns = Math.max(1, popupColumns - indent - 1);
   const label = row.status
-    ? `${row.name}${row.readonly ? " · readonly" : ""} · ${row.status}`
+    ? `${row.name}${row.readonly ? " · readonly" : ""}${row.shared ? " · shared" : ""} · ${row.status}`
     : row.name;
   const minimumLabelWidth = Math.min(
     label.length,
@@ -77,9 +78,10 @@ export function buildAgentTree(agents: readonly SubagentSnapshot[]): AgentTreeRo
         name: agent.name,
         status: agent.status,
         readonly: agent.readonly === true,
+        shared: agent.usesWorktree === false,
         depth,
         metadata: {
-          branch: agent.worktree.branch ?? null,
+          branch: agent.usesWorktree === false ? null : agent.worktree.branch ?? null,
           outgoingTokens: usage.outgoing,
           incomingTokens: usage.incoming,
           cacheReadTokens: usage.cacheRead,
@@ -100,9 +102,10 @@ export function buildAgentTree(agents: readonly SubagentSnapshot[]): AgentTreeRo
       name: agent.name,
       status: agent.status,
       readonly: agent.readonly === true,
+      shared: agent.usesWorktree === false,
       depth: 1,
       metadata: {
-        branch: agent.worktree.branch ?? null,
+        branch: agent.usesWorktree === false ? null : agent.worktree.branch ?? null,
         outgoingTokens: usage.outgoing,
         incomingTokens: usage.incoming,
         cacheReadTokens: usage.cacheRead,

package/src/animation.tsx

@@ -143,7 +143,12 @@ const RULE_CHARS_PER_MS = 0.04;
 const RULE_HIGHLIGHT_WIDTH = 10;
 const COMET_CHARS_PER_MS = 0.035;
 const ELECTRIC_FRAME_MS = 140;
-const CONSTELLATION_SPACING = 13;
+/** Average columns per star. Each slot places its own star inside this span. */
+const CONSTELLATION_SPACING = 11;
+/** Base period of one star. A hashed factor spreads the real periods around it. */
+const CONSTELLATION_TWINKLE_MS = 2600;
+/** How much of its period a star burns for. It is dark and moves in the rest. */
+const CONSTELLATION_LIFETIME = 0.72;
 const RANDOM_CONSTELLATION_CYCLE_MS = 2000;
 /** How much of one cycle a single sparkle burns for, start to finish. */
 const RANDOM_CONSTELLATION_LIFETIME = 0.5;
@@ -222,48 +227,6 @@ const ClockContext = createContext<Clock>({
 
 export const useClock = () => useContext(ClockContext);
 
-/** The prompt cursor stays visible for most of each slow blink cycle. */
-export function inputCursorVisible(elapsedMs: number): boolean {
-  const phase = ((elapsedMs % CARET_PERIOD_MS) + CARET_PERIOD_MS) % CARET_PERIOD_MS;
-  return phase < CARET_PERIOD_MS * 0.65;
-}
-
-/** Replace the terminal-defined fast cursor blink with the shared slow clock. */
-export function PromptCursorBlink({
-  inputRef,
-  active,
-}: {
-  inputRef: RefObject<TextareaRenderable | null>;
-  active: boolean;
-}) {
-  const { subscribe, enabled } = useClock();
-
-  useEffect(() => {
-    const input = inputRef.current;
-    if (!input) return;
-    input.cursorStyle = { style: "block", blinking: false };
-    if (!active) {
-      input.showCursor = false;
-      return;
-    }
-
-    input.showCursor = true;
-    if (!enabled) return;
-
-    let startedAt: number | undefined;
-    let visible = true;
-    return subscribe((elapsedMs) => {
-      startedAt ??= elapsedMs;
-      const next = inputCursorVisible(elapsedMs - startedAt);
-      if (next === visible) return;
-      visible = next;
-      if (inputRef.current) inputRef.current.showCursor = next;
-    });
-  }, [active, enabled, inputRef, subscribe]);
-
-  return null;
-}
-
 /**
  * One frame callback for the whole app. Animated components write straight to
  * their own renderable, so no React render happens per frame. The renderer is
@@ -700,6 +663,44 @@ const hashPosition = (frame: number, seed: number, width: number) => {
   return Math.abs(value) % width;
 };
 
+export type ConstellationStar = { column: number; strength: number };
+
+/**
+ * One star of the constellation field, for the slot of columns it belongs to.
+ *
+ * The field used to be a fixed grid: a star every `CONSTELLATION_SPACING`
+ * columns, in the same place for the whole run. Each slot now holds a star with
+ * its own period, its own start, its own peak brightness, and a column that is
+ * re-drawn for every life. A star is dark between two lives, so it never moves
+ * while it is visible. Returns `null` while the slot is empty.
+ */
+export function constellationStar(
+  slot: number,
+  elapsedMs: number,
+  role: WorkingRuleRole,
+): ConstellationStar | null {
+  if (slot < 0) return null;
+  const seed = roleSeed(role);
+  const period = CONSTELLATION_TWINKLE_MS *
+    (0.55 + (hashPosition(slot * 13 + 7, seed + 3, 100) / 100) * 1.05);
+  const offset = (hashPosition(slot * 29 + 5, seed + 11, 1000) / 1000) * period;
+  const time = elapsedMs + offset;
+  const life = (time % period) / period;
+  if (life >= CONSTELLATION_LIFETIME) return null;
+
+  const epoch = Math.floor(time / period);
+  // Two columns of margin on each side keep the halo of one star clear of the
+  // next slot, so no two stars ever touch.
+  const span = CONSTELLATION_SPACING - 4;
+  const column = slot * CONSTELLATION_SPACING + 2 +
+    hashPosition(epoch * 31 + slot, seed * 7 + slot, span);
+  const amplitude = 0.5 + (hashPosition(epoch * 17 + slot, seed + 23, 100) / 100) * 0.5;
+  const strength = clampStrength(
+    Math.sin((life / CONSTELLATION_LIFETIME) * Math.PI) ** 1.2 * amplitude,
+  );
+  return { column, strength };
+}
+
 /** Choose stable, random-looking sparkle centers for one two-second cycle. */
 export function randomConstellationCenters(
   width: number,
@@ -796,20 +797,24 @@ export function workingRuleCell(
   }
 
   if (mode === "constellation") {
-    const seed = roleSeed(role);
-    const spacing = (offset: number) => (column + offset + seed * 3) % CONSTELLATION_SPACING === 0;
-    // A star ends at its own cell unless it carries a halo, which is what
-    // makes it bloom on the rule rather than switch on and off in place.
-    const halo = spacing(1) || spacing(-1);
-    if (!spacing(0) && !halo) return { strength: 0, glyph: "─" };
-    const star = spacing(0) ? column : spacing(1) ? column + 1 : column - 1;
-    // Stars sit thirteen columns apart, so any fixed phase step per column put
-    // them all within a fifth of a radian of each other and they blinked in
-    // unison. A hashed offset gives each one its own place in the cycle.
-    const phase = elapsedMs / 620 + hashPosition(star, seed, 628) / 100;
-    const peak = 0.12 + ((Math.sin(phase) + 1) / 2) * 0.88;
-    if (!spacing(0)) return { strength: peak * CONSTELLATION_HALO, glyph: "·" };
-    return { strength: peak, glyph: peak > 0.82 ? "✦" : peak > 0.48 ? "✧" : "·" };
+    const slot = Math.floor(column / CONSTELLATION_SPACING);
+    let strength = 0;
+    let glyph = "─";
+    // A star can sit in the neighbouring slot and still reach this column with
+    // its halo, which is what makes it bloom instead of switching on in place.
+    for (let index = slot - 1; index <= slot + 1; index++) {
+      const star = constellationStar(index, elapsedMs, role);
+      if (!star || star.column >= width) continue;
+      const distance = Math.abs(column - star.column);
+      if (distance > 1) continue;
+      const lit = distance === 0 ? star.strength : star.strength * CONSTELLATION_HALO;
+      if (lit <= strength) continue;
+      strength = lit;
+      glyph = distance > 0 ? "·"
+        : star.strength > 0.82 ? "✦"
+          : star.strength > 0.48 ? "✧" : "·";
+    }
+    return { strength, glyph };
   }
 
   if (mode === "random-constellation") {

package/src/app.tsx

@@ -14,7 +14,6 @@ import { Component, memo, useEffect, useLayoutEffect, useMemo, useRef, useState,
 import {
   AnimationProvider,
   PlaceholderWave,
-  PromptCursorBlink,
   supportsTrueColor,
   useWorkingRule,
   type WorkingRuleLabel,
@@ -233,6 +232,7 @@ import {
   type ShellManagerLike,
 } from "./processes-popup";
 import type { TerminalTitleController } from "./terminal-title";
+import { resolveOrcaStatusState, type OrcaStatusController } from "./orca-status";
 import { readClipboardText } from "./text-paste";
 import { copyTextToClipboard } from "./clipboard";
 import { NewsPopup } from "./news-popup";
@@ -832,6 +832,7 @@ export function App({
   shellManager,
   messageCacheController,
   terminalTitle,
+  orcaStatus,
   startupWarnings = [],
   onSandboxModeChange,
   sandboxWarningSource,
@@ -871,6 +872,7 @@ export function App({
   shellManager?: ShellManagerLike;
   messageCacheController?: MessageCacheController;
   terminalTitle?: TerminalTitleController;
+  orcaStatus?: OrcaStatusController;
   /** Visible process-local warnings. These lines never enter pi session context. */
   startupWarnings?: readonly string[];
   onSandboxModeChange?: (mode: NonNullable<PumSettings["sandboxMode"]>) => void;
@@ -1243,7 +1245,9 @@ export function App({
   });
   const visibleModelId = activeAgent?.modelId.split("/").slice(1).join("/") || modelId;
   const visibleThinkingLevel = activeAgent?.thinkingLevel ?? thinkingLevel;
-  const visibleBranch = activeAgent?.worktree.branch ?? branch;
+  const visibleBranch = activeAgent?.usesWorktree === false
+    ? branch
+    : activeAgent?.worktree.branch ?? branch;
   const visibleElapsedSec = activeAgent ? agentElapsedSec : elapsedSec;
   const visibleUsage = activeAgent?.usage ?? usage;
   const agentTreeRows = buildAgentTree(agents);
@@ -1950,11 +1954,28 @@ export function App({
   useEffect(() => {
     // A delegate answering counts as work even though it is not a managed
     // agent, or the terminal reads as idle while AFK decides something.
+    orcaStatus?.update({
+      state: resolveOrcaStatusState({
+        working: busy || activeSubagentCount > 0 || afkAnswering,
+        waitingForUser: Boolean(visibleQuestionnaire),
+      }),
+      model: session.agent.state.model?.id,
+      sessionKey: session.sessionId,
+    });
     terminalTitle?.update({
       working: busy || activeSubagentCount > 0 || afkAnswering,
       activeSubagentCount,
     });
-  }, [terminalTitle, busy, activeSubagentCount, afkAnswering]);
+  }, [
+    terminalTitle,
+    orcaStatus,
+    busy,
+    activeSubagentCount,
+    afkAnswering,
+    visibleQuestionnaire,
+    session.sessionId,
+    session.agent.state.model?.id,
+  ]);
 
   useEffect(() => spawnPreviewManager?.subscribe(() => {
     setSpawnPreviewRevision((revision) => revision + 1);
@@ -4181,7 +4202,10 @@ export function App({
       appendRequesterLine(requesterAgentId, {
         kind: "text",
         role: "system",
-        text: `background agent started: ${spawned.name} (${spawned.id})\n${spawned.worktree.branch}\n${spawned.worktree.path}`,
+        text: `background agent started: ${spawned.name} (${spawned.id})\n`
+          + (spawned.usesWorktree
+            ? `${spawned.worktree.branch}\n${spawned.worktree.path}`
+            : `shared directory\n${spawned.worktree.path}`),
       });
     })().catch((error) => {
       appendRequesterLine(requesterAgentId, {
@@ -4443,7 +4467,7 @@ export function App({
   };
 
   const cachedBatchDisplay = (prompts: readonly string[]): string => [
-    `Run ${prompts.length} cached tasks with worktree subagents:`,
+    `Run ${prompts.length} cached tasks with subagents:`,
     ...prompts.map((prompt, index) => `${index + 1}. ${prompt}`),
   ].join("\n");
 
@@ -6007,14 +6031,12 @@ export function App({
             keyBindings={PROMPT_TEXTAREA_KEY_BINDINGS}
             scrollMargin={1}
             scrollSpeed={PROMPT_SCROLL_SPEED}
-            cursorStyle={{ style: "block", blinking: false }}
             focused={promptFocused}
             onContentChange={handleTextareaChange}
             onCursorChange={scheduleInputMetrics}
             onSubmit={() => shellModeRef.current ? submitShellCommand() : submitPrompt()}
             style={{ width: promptInputColumns, flexShrink: 0, minWidth: 0, height: inputRows }}
           />
-          <PromptCursorBlink inputRef={inputRef} active={promptFocused} />
           {/* Reserve six columns on normal terminals. This forces wrapping
               before cursor movement can briefly overdraw the terminal edge. */}
           <box style={{ width: promptRightColumns, height: inputRows, flexShrink: 0 }} />

package/src/commands.ts

@@ -31,7 +31,7 @@ export const COMMANDS: Command[] = [
   },
   {
     name: "/background",
-    description: "Start a managed worktree agent for the selected transcript",
+    description: "Start a shared-project agent for the selected transcript",
   },
   {
     name: "/history",

package/src/headless.ts

@@ -7,6 +7,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { mkdirSync } from "node:fs";
 import { AGENT_DIR, AUTH_PATH, MODELS_PATH, sessionDir } from "./config";
+import { createMemoryExtension, MEMORY_EDIT_TOOL_NAME, MEMORY_READ_TOOL_NAME } from "./memory";
 import { checkPathsForProject, loadSettings } from "./settings";
 import { identityExtension } from "./identity";
 import { setWritingStyle, writingStyleExtension } from "./writing-style";
@@ -34,7 +35,14 @@ import { prepareHeadlessStatsOutput, type HeadlessStatsOutput } from "./headless
  * are not constructed here, and subagent, trigger, and message-cache tools
  * need the running TUI for routing and notifications.
  */
-const HEADLESS_TOOL_NAMES = ["read", "write", "edit", "bash"];
+const HEADLESS_TOOL_NAMES = [
+  "read",
+  "write",
+  "edit",
+  "bash",
+  MEMORY_READ_TOOL_NAME,
+  MEMORY_EDIT_TOOL_NAME,
+];
 
 /**
  * Handle one hosted web-search call from a headless run.
@@ -188,6 +196,7 @@ async function runPromptSession(
             checkModePromptExtension,
             checkModeExtension,
             sandboxController.extension(),
+            createMemoryExtension({ agentDir: AGENT_DIR, audience: "main" }),
           ],
         },
       });

package/src/help-popup.tsx

@@ -4,14 +4,14 @@ import { PopupFrame } from "./popup-frame";
 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",
+  "PUM workflow — prompt or steer · cache prompts · attach images · run managed agents in parallel",
+  "switch transcripts · close successful agents · optional worktrees · persistent sessions · safety settings",
 ] 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.",
+  "Run agents in parallel. Use worktrees for isolation.",
+  "Switch transcripts and close successful agents.",
   "Sessions persist. Settings include safety checks.",
 ] as const;
 
@@ -59,7 +59,7 @@ export const HELP_GROUPS: HelpGroup[] = [
       ["/clear", "Start a fresh session"],
       ["/goal", "Set or control a goal"],
       ["/goalf", "Work out a goal, then start it"],
-      ["/background", "Start a managed agent for the selected transcript"],
+      ["/background", "Start a shared-project agent for the selected transcript"],
       ["/history", "Browse saved sessions"],
       ["/providers", "Add, edit, or delete a provider; /login adds"],
       ["/news", "Open recent answers (News)"],

package/src/main.tsx

@@ -7,10 +7,11 @@ import {
   ModelRuntime,
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, writeSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { App } from "./app";
 import { AGENT_DIR, AUTH_PATH, MODELS_PATH, sessionDir } from "./config";
+import { createMemoryExtension } from "./memory";
 import { checkPathsForProject, loadSettings } from "./settings";
 import { setBashOutputSettingsIfPresent } from "./bash-output";
 import { installWebSearch, webSearch } from "./web-search";
@@ -49,6 +50,7 @@ import type { StartupOptions } from "./cli";
 import { TodoToolsController } from "./todo-tools";
 import { installSelectionClipboard } from "./clipboard";
 import { TerminalTitleController } from "./terminal-title";
+import { isOrcaTerminal, OrcaStatusController } from "./orca-status";
 import { SandboxController } from "./sandbox";
 import {
   createFilesystemSandboxExtension,
@@ -260,6 +262,9 @@ export async function start(
       (_agentId, isReadonly) => sandboxController.extension({ readonly: isReadonly }),
       (_agentId, isReadonly) => createFilesystemSandboxExtension({ readonly: isReadonly }),
     ],
+    childWorkerExtensionFactories: [
+      () => createMemoryExtension({ agentDir: AGENT_DIR, audience: "subagent" }),
+    ],
     sandboxModeSource: () => sandboxController.mode,
   });
   const subagentExtension = subagentManager.mainExtension();
@@ -295,6 +300,7 @@ export async function start(
             filesystemSandboxExtension,
             mainCheckModeExtension,
             sandboxExtension,
+            createMemoryExtension({ agentDir: AGENT_DIR, audience: "main" }),
             questionnaireManager.extension({ id: "main", name: "main" }),
             mainToolGroups.extension(),
             mainTodoTools.extension(),
@@ -342,6 +348,11 @@ export async function start(
 
   const renderer = await createCliRenderer({ exitOnCtrlC: false });
   const terminalTitle = new TerminalTitleController((title) => renderer.setTerminalTitle(title));
+  const orcaStatus = new OrcaStatusController(
+    isOrcaTerminal(process.env),
+    // Keep the control message outside OpenTUI's external-output path.
+    (sequence) => { writeSync(process.stdout.fd, sequence); },
+  );
   const selectionClipboard = installSelectionClipboard(renderer);
   const root = createRoot(renderer);
   // Reported on the restored terminal by the exit action below, so the message
@@ -445,6 +456,7 @@ export async function start(
       spawnPreviewManager={spawnPreviewManager}
       messageCacheController={messageCacheController}
       terminalTitle={terminalTitle}
+      orcaStatus={orcaStatus}
       startupWarnings={[
         ...(sandboxWarning ? [sandboxWarning] : []),
         ...(outerSandbox ? [

package/src/memory-identity.ts

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { posix, win32 } from "node:path";
+import {
+  canonicalRealpathSync,
+  projectStorageKey,
+  type RuntimePlatform,
+} from "./platform";
+
+export type MemoryIdentity = {
+  key: string;
+  digest: string;
+  kind: "git" | "directory";
+};
+
+type MemoryIdentityOptions = {
+  platform?: RuntimePlatform;
+  gitPath?: (cwd: string, args: string[]) => string;
+  realpath?: (path: string, platform: RuntimePlatform) => string;
+};
+
+const resolvedIdentities = new Map<string, MemoryIdentity>();
+
+function defaultGitPath(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 4 * 1024 * 1024,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "ignore"],
+  }).replace(/\r?\n$/, "");
+}
+
+function digest(key: string): string {
+  return createHash("sha256").update(key).digest("hex");
+}
+
+/**
+ * Use Git's shared administrative directory as the repository identity.
+ * Every linked worktree reports the same directory, even when its checkout
+ * path is unrelated to the primary checkout path.
+ */
+export function resolveMemoryIdentity(
+  cwd: string,
+  options: MemoryIdentityOptions = {},
+): MemoryIdentity {
+  const platform = options.platform ?? process.platform;
+  const paths = platform === "win32" ? win32 : posix;
+  const realpath = options.realpath ?? canonicalRealpathSync;
+  const gitPath = options.gitPath ?? defaultGitPath;
+  const cacheKey = `${platform}\0${projectStorageKey(cwd, platform)}`;
+  const cacheable = options.gitPath === undefined && options.realpath === undefined;
+  if (cacheable) {
+    const cached = resolvedIdentities.get(cacheKey);
+    if (cached) return cached;
+  }
+
+  try {
+    const raw = gitPath(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    const absolute = paths.isAbsolute(raw) ? raw : paths.resolve(cwd, raw);
+    const canonical = realpath(absolute, platform);
+    const key = `git:${projectStorageKey(canonical, platform)}`;
+    const identity: MemoryIdentity = { key, digest: digest(key), kind: "git" };
+    if (cacheable) resolvedIdentities.set(cacheKey, identity);
+    return identity;
+  } catch {
+    let canonical = paths.resolve(cwd);
+    try {
+      canonical = realpath(canonical, platform);
+    } catch { /* the session startup owns directory validation */ }
+    const key = `directory:${projectStorageKey(canonical, platform)}`;
+    const identity: MemoryIdentity = { key, digest: digest(key), kind: "directory" };
+    if (cacheable) resolvedIdentities.set(cacheKey, identity);
+    return identity;
+  }
+}