@esso0428/pi-subagents 0.15.5 → 0.15.7

package/src/ui/fleet-list.ts

@@ -4,7 +4,7 @@
  * Shows `main` + each running/queued subagent as a navigable list. Pressing ↓ (or
  * ←) at an empty prompt activates the list; ↑/↓ move the selection (filled ● marker),
  * Enter opens the selected agent's live conversation overlay, Esc returns to the prompt.
- * A viewer stays open when its agent finishes; finished agents linger briefly in the list.
+ * A viewer stays open when its agent finishes so the final output remains readable.
  *
  * Mechanics (see plan): the list is a `belowEditor` widget (render-only), and ALL key
  * handling goes through `onTerminalInput` — which fires before the focused editor and
@@ -12,22 +12,22 @@
  */
 
 import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentManager } from "../agent-manager.js";
-import { hasAgentHistory, readAgentHistory } from "../agent-history.js";
+import { canOpenActiveAgent } from "../agent-history-list.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal } from "../usage.js";
 import { type AgentActivity, getDisplayName, type Theme } from "./agent-widget.js";
-import { ConversationViewer, createStaticConversationSource, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
+import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
 
 /** Widget key for the below-editor fleet list. */
 const FLEET_KEY = "fleet";
-/** Max agent rows shown at once; extras collapse into a "↓ N more" indicator. */
-const MAX_AGENT_ROWS = 5;
+/** Maximum total rows contributed by FleetView, including hint and indicators. */
+export const FLEET_MAX_RENDER_ROWS = 6;
+const FLEET_BASE_ROWS = 2; // hint + main
+const FLEET_BODY_ROWS = FLEET_MAX_RENDER_ROWS - FLEET_BASE_ROWS;
 /** Re-render cadence so elapsed/token stats tick while agents run. */
 const TICK_MS = 200;
-/** How long a finished agent lingers in the list before it drops out. */
-const FINISHED_LINGER_MS = 4000;
-
 /** Minimal UI surface the FleetView needs from `ctx.ui` (structural subset). */
 export type FleetUICtx = {
   setWidget(
@@ -62,6 +62,32 @@ export function formatFleetTokens(count: number): string {
   return `↓ ${compact} tokens`;
 }
 
+/**
+ * Calculate a bounded agent slice for the complete logical roster.
+ * `selectedRosterIndex` includes main at index 0; `end` is exclusive.
+ */
+export function calculateFleetAgentWindow(
+  agentCount: number,
+  selectedRosterIndex: number,
+): { start: number; end: number; hiddenAbove: number; hiddenBelow: number } {
+  const count = Math.max(0, Math.floor(agentCount));
+  if (count === 0) return { start: 0, end: 0, hiddenAbove: 0, hiddenBelow: 0 };
+
+  const selectedAgent = Math.min(
+    count - 1,
+    Math.max(0, Math.floor(selectedRosterIndex) - 1),
+  );
+  const reserveAbove = selectedAgent > 0 ? 1 : 0;
+  const reserveBelow = selectedAgent < count - 1 ? 1 : 0;
+  const visibleCount = Math.max(1, FLEET_BODY_ROWS - reserveAbove - reserveBelow);
+  const start = Math.min(
+    Math.max(0, selectedAgent - visibleCount + 1),
+    Math.max(0, count - visibleCount),
+  );
+  const end = Math.min(count, start + visibleCount);
+  return { start, end, hiddenAbove: start, hiddenBelow: count - end };
+}
+
 /**
  * Place `right` flush to `width`, truncating `left` first so the stats survive.
  * The final clamp guarantees the line never exceeds `width` (which would wrap and
@@ -80,6 +106,7 @@ export class FleetList {
   private tui: any | undefined;
   private inputUnsub: (() => void) | undefined;
   private widgetRegistered = false;
+  private lastRosterKey: string | undefined;
   private timer: ReturnType<typeof setInterval> | undefined;
 
   private enabled = true;
@@ -95,6 +122,8 @@ export class FleetList {
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
     private getCwd: () => string | undefined = () => undefined,
+    private pi?: ExtensionAPI,
+    private getCtx: () => ExtensionContext | undefined = () => undefined,
   ) {}
 
   // ---- Lifecycle ----
@@ -112,6 +141,7 @@ export class FleetList {
     this.inputUnsub?.();
     this.ui = ui;
     this.widgetRegistered = false;
+    this.lastRosterKey = undefined;
     this.tui = undefined;
     this.inputUnsub = ui.onTerminalInput(data => this.handleKey(data));
   }
@@ -123,7 +153,7 @@ export class FleetList {
 
   /**
    * Called when an agent finishes. The viewer (if open on it) stays open so the
-   * final output remains readable, and the row lingers in the list — just refresh.
+   * final output remains readable; refresh the active-only roster.
    */
   onAgentFinished(_id: string): void {
     this.update();
@@ -137,6 +167,7 @@ export class FleetList {
     this.viewingAgentId = undefined;
     if (this.ui && this.widgetRegistered) this.ui.setWidget(FLEET_KEY, undefined);
     this.widgetRegistered = false;
+    this.lastRosterKey = undefined;
     this.tui = undefined;
     this.active = false;
     // Null last so a `viewerClose()` microtask above can't re-register the widget.
@@ -146,7 +177,11 @@ export class FleetList {
   /** Re-register/refresh the below-editor widget; clears it when no agents remain. */
   update(): void {
     if (!this.ui) return;
-    const hasAgents = this.enabled && this.agentRecords().length > 0;
+    const records = this.agentRecords();
+    const hasAgents = this.enabled && records.length > 0;
+    const rosterKey = records.map(record => record.id).join("\0");
+    const rosterChanged = rosterKey !== this.lastRosterKey;
+    this.lastRosterKey = rosterKey;
 
     if (!hasAgents) {
       if (this.widgetRegistered) {
@@ -157,6 +192,7 @@ export class FleetList {
       if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
       this.active = false;
       this.selectedIndex = 0;
+      this.lastRosterKey = undefined;
       return;
     }
 
@@ -173,35 +209,21 @@ export class FleetList {
       }, { placement: "belowEditor" });
       this.widgetRegistered = true;
     } else {
-      this.tui?.requestRender();
+      this.tui?.requestRender(rosterChanged);
     }
   }
 
   // ---- Roster ----
 
   /**
-   * Agents shown in the list, ordered earliest-launched first so the ones you
-   * started sooner sit at the top. Live rows are openable through their session;
-   * terminal rows are included only when their durable transcript exists. This
-   * prevents Enter from dead-ending on stale rehydrated metadata.
-   * Included: running/queued, plus the agent currently being viewed, plus
-   * recently-finished ones (they linger briefly before dropping out).
-   * Pending agents with no session yet are hidden until they start.
-   * (`listAgents()` is newest-first, so we re-sort.)
+   * Active agents shown in the list, ordered earliest-launched first so the
+   * ones you started sooner sit at the top. Pending agents with no session yet
+   * are hidden until they start. (`listAgents()` is newest-first, so we
+   * re-sort.)
    */
   private agentRecords(): AgentRecord[] {
-    const now = Date.now();
     return this.manager.listAgents()
-      .filter(a => {
-        const live = a.session && (
-          a.status === "running" || a.status === "queued"
-          || a.id === this.viewingAgentId
-          || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)
-        );
-        const cwd = this.getCwd();
-        const history = cwd !== undefined && hasAgentHistory(cwd, a.transcriptPath);
-        return !!live || history;
-      })
+      .filter(record => canOpenActiveAgent(record))
       .sort((a, b) => a.startedAt - b.startedAt);
   }
 
@@ -296,18 +318,18 @@ export class FleetList {
     }
     const record = entry.record;
     if (!this.ui) return;
-    const session = record.session ?? (record.transcriptPath && this.getCwd()
-      ? (() => {
-          const messages = readAgentHistory(this.getCwd()!, record.transcriptPath!);
-          return messages ? createStaticConversationSource(messages) : undefined;
-        })()
-      : undefined);
-    if (!session) {
-      this.ui.notify(`Agent is ${record.status} — no history available.`, "info");
+    if (!canOpenActiveAgent(record) || !record.session) {
+      this.ui.notify(`Agent is ${record.status} — no live session available.`, "info");
+      return;
+    }
+    const session = record.session;
+    const ctx = this.getCtx();
+    const pi = this.pi;
+    if (!ctx || !pi) {
+      this.ui.notify("Agent conversation is unavailable — no active session.", "info");
       return;
     }
     const activity = this.agentActivity.get(record.id);
-    const isLive = record.session !== undefined;
     this.viewingAgentId = record.id;
 
     void this.ui.custom<undefined>(
@@ -320,11 +342,12 @@ export class FleetList {
           activity,
           theme,
           done,
-          isLive ? () => {
+          () => {
             if (this.manager.abort(record.id)) this.ui?.notify(`Stopped "${record.description}".`, "info");
-          } : undefined,
+          },
           keybindings,
-          isLive ? (message: string) => this.manager.steer(record.id, message) : undefined,
+          (message: string) => this.manager.steer(record.id, message),
+          { pi, ctx, readOnly: false },
         );
       },
       {
@@ -363,20 +386,18 @@ export class FleetList {
       : "esc to interrupt · ← for agents · ↓ to manage";
     const lines: string[] = [];
     lines.push(truncateToWidth("  " + theme.fg("dim", hint), width));
-    lines.push("");
     lines.push(truncateToWidth(`  ${this.bullet(0, sel, theme)} main`, width));
 
-    // Window the agent rows so the selected one stays visible.
-    const visible = Math.min(MAX_AGENT_ROWS, agents.length);
-    const selAgent = Math.max(0, sel - 1);
-    const start = selAgent < visible ? 0 : selAgent - visible + 1;
-    const hiddenBelow = agents.length - (start + visible);
-
-    if (start > 0) lines.push(rightAlign("", theme.fg("dim", `↑ ${start} more`), width));
-    for (let a = start; a < start + visible; a++) {
+    const window = calculateFleetAgentWindow(agents.length, sel);
+    if (window.hiddenAbove > 0) {
+      lines.push(rightAlign("", theme.fg("dim", `↑ ${window.hiddenAbove} more`), width));
+    }
+    for (let a = window.start; a < window.end; a++) {
       lines.push(this.renderAgentRow(a + 1, sel, agents[a].record, width, theme));
     }
-    if (hiddenBelow > 0) lines.push(rightAlign("", theme.fg("dim", `↓ ${hiddenBelow} more`), width));
+    if (window.hiddenBelow > 0) {
+      lines.push(rightAlign("", theme.fg("dim", `↓ ${window.hiddenBelow} more`), width));
+    }
 
     return lines;
   }

package/src/write-execution.ts

@@ -0,0 +1,180 @@
+import { createWriteToolDefinition, generateDiffString, generateUnifiedPatch, type ExtensionContext, type ToolDefinition, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+/** Maximum UTF-8 size of the durable display diff plus unified patch. */
+export const MAX_DURABLE_DIFF_BYTES = 4 * 1024 * 1024;
+/** Avoid retaining arbitrarily large previous files in the live-only store. */
+export const MAX_COMPARABLE_WRITE_BYTES = 512_000;
+export const MAX_WRITE_METADATA_ENTRIES = 100;
+
+export interface DurableWriteDetails {
+  diff?: string;
+  patch?: string;
+  firstChangedLine?: number;
+  diffUnavailableReason?: string;
+}
+
+/** Ephemeral execution metadata used by the live renderer. Never persisted as a before/after pair. */
+export interface WriteExecutionMeta extends DurableWriteDetails {
+  fileExistedBeforeWrite: boolean;
+  previousContent?: string;
+}
+
+export class WriteExecutionMetadataStore {
+  readonly entries = new Map<string, WriteExecutionMeta>();
+
+  set(toolCallId: string, metadata: WriteExecutionMeta): void {
+    this.entries.delete(toolCallId);
+    this.entries.set(toolCallId, metadata);
+    while (this.entries.size > MAX_WRITE_METADATA_ENTRIES) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
+
+  get(toolCallId: unknown): WriteExecutionMeta | undefined {
+    return typeof toolCallId === "string" ? this.entries.get(toolCallId) : undefined;
+  }
+
+  delete(toolCallId: string): void {
+    this.entries.delete(toolCallId);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+type WriteParams = { path: string; content: string };
+
+function resolveWritePath(path: string, cwd: string): string {
+  if (path === "~") return process.env.HOME ?? cwd;
+  if (path.startsWith("~/") || path.startsWith("~\\")) {
+    return resolve(process.env.HOME ?? cwd, path.slice(2));
+  }
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+async function capturePreviousContent(absolutePath: string): Promise<WriteExecutionMeta> {
+  let info;
+  try {
+    info = await lstat(absolutePath);
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return { fileExistedBeforeWrite: false, previousContent: "" };
+    return {
+      fileExistedBeforeWrite: true,
+      diffUnavailableReason: "unable to inspect the previous file",
+    };
+  }
+
+  if (!info.isFile()) {
+    return {
+      fileExistedBeforeWrite: true,
+      diffUnavailableReason: "previous path is not a regular file",
+    };
+  }
+  if (info.size > MAX_COMPARABLE_WRITE_BYTES) {
+    return {
+      fileExistedBeforeWrite: true,
+      diffUnavailableReason: `previous file exceeds ${MAX_COMPARABLE_WRITE_BYTES} bytes`,
+    };
+  }
+
+  try {
+    const bytes = await readFile(absolutePath);
+    if (bytes.byteLength > MAX_COMPARABLE_WRITE_BYTES) {
+      return {
+        fileExistedBeforeWrite: true,
+        diffUnavailableReason: `previous file exceeds ${MAX_COMPARABLE_WRITE_BYTES} bytes`,
+      };
+    }
+    const previousContent = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return { fileExistedBeforeWrite: true, previousContent };
+  } catch {
+    return {
+      fileExistedBeforeWrite: true,
+      diffUnavailableReason: "previous file is not comparable UTF-8 text",
+    };
+  }
+}
+
+function durableDetails(
+  metadata: WriteExecutionMeta,
+  path: string,
+  content: string,
+): DurableWriteDetails {
+  if (metadata.diffUnavailableReason) {
+    return { diffUnavailableReason: metadata.diffUnavailableReason };
+  }
+  const previousContent = metadata.previousContent ?? "";
+  const diffResult = generateDiffString(previousContent, content);
+  const patch = generateUnifiedPatch(path, previousContent, content);
+  const totalBytes = Buffer.byteLength(diffResult.diff, "utf8") + Buffer.byteLength(patch, "utf8");
+  if (totalBytes > MAX_DURABLE_DIFF_BYTES) {
+    return { diffUnavailableReason: `durable diff exceeds ${MAX_DURABLE_DIFF_BYTES} bytes` };
+  }
+  return {
+    diff: diffResult.diff,
+    patch,
+    firstChangedLine: diffResult.firstChangedLine,
+  };
+}
+
+export async function executeWriteWithMetadata(
+  store: WriteExecutionMetadataStore,
+  toolCallId: string,
+  params: WriteParams,
+  signal: AbortSignal | undefined,
+  cwd: string,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details?: DurableWriteDetails }> {
+  const absolutePath = resolveWritePath(params.path, cwd);
+  store.delete(toolCallId);
+
+  return withFileMutationQueue(absolutePath, async () => {
+    const throwIfAborted = () => {
+      if (signal?.aborted) throw new Error("Operation aborted");
+    };
+    throwIfAborted();
+    const metadata = await capturePreviousContent(absolutePath);
+    throwIfAborted();
+    await mkdir(dirname(absolutePath), { recursive: true });
+    throwIfAborted();
+    await writeFile(absolutePath, params.content, "utf8");
+    throwIfAborted();
+
+    const details = durableDetails(metadata, params.path, params.content);
+    store.set(toolCallId, { ...metadata, ...details });
+    return {
+      content: [{ type: "text" as const, text: `Successfully wrote to ${params.path}` }],
+      details,
+    };
+  }).catch((error) => {
+    store.delete(toolCallId);
+    throw error;
+  });
+}
+
+/**
+ * A session-local write definition. It retains Pi's public schema/description
+ * and replaces only execution so the parent registry is never mutated.
+ */
+export function createTrackedWriteTool(
+  cwd: string,
+  store = new WriteExecutionMetadataStore(),
+): ToolDefinition<any, DurableWriteDetails> {
+  const nativeWrite = createWriteToolDefinition(cwd);
+  return {
+    ...nativeWrite,
+    async execute(
+      toolCallId: string,
+      params: WriteParams,
+      signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ExtensionContext,
+    ) {
+      return executeWriteWithMetadata(store, toolCallId, params, signal, ctx.cwd || cwd);
+    },
+  } as ToolDefinition<any, DurableWriteDetails>;
+}

package/test/agent-history-list.test.ts

@@ -0,0 +1,121 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  buildAgentStatusMenuEntries,
+  canOpenActiveAgent,
+  canOpenAgentHistory,
+  formatAgentHistoryOption,
+  isTerminalAgentStatus,
+  splitAgentRecords,
+} from "../src/agent-history-list.js";
+
+type TestRecord = {
+  status: string;
+  session?: object;
+  transcriptPath?: string;
+  type?: string;
+  description?: string;
+  startedAt?: number;
+  completedAt?: number;
+};
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of tempDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function record(overrides: TestRecord): any {
+  return {
+    id: "agent-1",
+    type: "Explore",
+    description: "Inspect the repository",
+    status: "completed",
+    toolUses: 0,
+    startedAt: 1_000,
+    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+    compactionCount: 0,
+    ...overrides,
+  };
+}
+
+describe("agent history list helpers", () => {
+  it("recognizes exactly the five terminal statuses", () => {
+    for (const status of ["completed", "steered", "stopped", "aborted", "error"]) {
+      expect(isTerminalAgentStatus(status)).toBe(true);
+    }
+    for (const status of ["running", "queued", "unknown", ""]) {
+      expect(isTerminalAgentStatus(status)).toBe(false);
+    }
+  });
+
+  it("separates active and terminal records without mutating input", () => {
+    const done = record({ status: "completed", session: {} });
+    const running = record({ status: "running", session: {} });
+    const stopped = record({ status: "stopped", session: {} });
+    const queued = record({ status: "queued", session: {} });
+    const input = [done, running, stopped, queued];
+    const before = [...input];
+
+    const result = splitAgentRecords(input, undefined);
+
+    expect(result.active).toEqual([running, queued]);
+    expect(result.history).toEqual([done, stopped]);
+    expect(input).toEqual(before);
+    expect(input).toEqual([done, running, stopped, queued]);
+  });
+
+  it("requires a session or existing transcript for history", () => {
+    expect(canOpenAgentHistory(record({ session: undefined }), undefined)).toBe(false);
+    expect(canOpenAgentHistory(record({ session: {} }), undefined)).toBe(true);
+    expect(canOpenAgentHistory(record({ status: "running", session: {} }), undefined)).toBe(false);
+    expect(canOpenActiveAgent(record({ status: "running", session: {} }))).toBe(true);
+    expect(canOpenActiveAgent(record({ status: "queued", session: undefined }))).toBe(false);
+    expect(canOpenActiveAgent(record({ status: "completed", session: {} }))).toBe(false);
+  });
+
+  it("opens history only for an existing project-local transcript", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-subagents-history-list-"));
+    tempDirectories.push(cwd);
+    const transcriptPath = ".pi-subagents/agent-transcripts/agent.jsonl";
+    mkdirSync(join(cwd, ".pi-subagents", "agent-transcripts"), { recursive: true });
+    const historical = record({ session: undefined, transcriptPath });
+
+    expect(canOpenAgentHistory(historical, cwd)).toBe(false);
+    writeFileSync(join(cwd, transcriptPath), "{}\n");
+    expect(canOpenAgentHistory(historical, cwd)).toBe(true);
+    expect(canOpenAgentHistory(historical, undefined)).toBe(false);
+  });
+
+  it("builds separate menu entries with openable records only", () => {
+    const entries = buildAgentStatusMenuEntries([
+      record({ status: "running", session: {} }),
+      record({ status: "queued", session: undefined }),
+      record({ status: "completed", session: {} }),
+      record({ status: "error", session: {} }),
+      record({ status: "stopped", session: undefined }),
+    ], undefined);
+
+    expect(entries).toEqual(["Running agents (1)", "Agent history (2)"]);
+    expect(buildAgentStatusMenuEntries([record({ status: "queued", session: undefined })], undefined)).toEqual([]);
+  });
+
+  it("formats a bounded history option using the display name and duration", () => {
+    const option = formatAgentHistoryOption(record({
+      status: "completed",
+      type: "Explore",
+      description: "A very long description ".repeat(20),
+      startedAt: 1_000,
+      completedAt: 3_000,
+    }), 9_000);
+
+    expect(option).toContain("[completed]");
+    expect(option).toContain("Explore");
+    expect(option).toContain("2.0s");
+    expect(option.length).toBeLessThanOrEqual(140);
+  });
+});