@esso0428/pi-subagents 0.15.15 → 0.15.17

package/src/ui/fleet-list.ts

@@ -2,7 +2,7 @@
  * fleet-list.ts — Claude Code-style "FleetView" list rendered below the editor.
  *
  * Shows `main` + each running/queued subagent as a navigable list. Pressing ↓ (or
- * ←) at an empty prompt activates the list; ↑/↓ move the selection (filled ● marker),
+ * `j`) 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 so the final output remains readable.
  *
@@ -28,11 +28,23 @@ 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;
+/** Normalized mouse input accepted by FleetView's widget surface. */
+export type FleetMouseEvent = { type: string; wheelDelta?: number };
+
+type FleetMouseResult = { handled: true; render: true };
+
+type FleetWidgetContent = {
+  render(width: number): string[];
+  invalidate(): void;
+  dispose?(): void;
+  handleMouse?(event: FleetMouseEvent): FleetMouseResult | undefined;
+};
+
 /** Minimal UI surface the FleetView needs from `ctx.ui` (structural subset). */
 export type FleetUICtx = {
   setWidget(
     key: string,
-    content: undefined | ((tui: any, theme: Theme) => { render(width: number): string[]; invalidate(): void; dispose?(): void }),
+    content: undefined | ((tui: any, theme: Theme) => FleetWidgetContent),
     options?: { placement?: "aboveEditor" | "belowEditor" },
   ): void;
   onTerminalInput(handler: (data: string) => { consume?: boolean; data?: string } | undefined): () => void;
@@ -62,30 +74,70 @@ export function formatFleetTokens(count: number): string {
   return `↓ ${compact} tokens`;
 }
 
+/** A bounded slice of the agent-only roster rendered by FleetView. */
+export type FleetAgentWindow = {
+  start: number;
+  end: number;
+  hiddenAbove: number;
+  hiddenBelow: number;
+};
+
 /**
- * Calculate a bounded agent slice for the complete logical roster.
- * `selectedRosterIndex` includes main at index 0; `end` is exclusive.
+ * Calculate a bounded agent slice from an agent-only viewport start.
+ * `end` is exclusive; `main` is rendered separately and is not part of this
+ * window. Marker rows are reserved only when the corresponding side is hidden.
  */
 export function calculateFleetAgentWindow(
   agentCount: number,
-  selectedRosterIndex: number,
-): { start: number; end: number; hiddenAbove: number; hiddenBelow: number } {
+  viewportStart: number,
+): FleetAgentWindow {
   const count = Math.max(0, Math.floor(agentCount));
   if (count === 0) return { start: 0, end: 0, hiddenAbove: 0, hiddenBelow: 0 };
 
-  const selectedAgent = Math.min(
+  const maxStart = Math.max(0, count - (FLEET_BODY_ROWS - 1));
+  const start = Math.min(maxStart, Math.max(0, Math.floor(viewportStart)));
+  const hasAbove = start > 0;
+  const agentBudget = Math.max(1, FLEET_BODY_ROWS - (hasAbove ? 1 : 0));
+  let end = Math.min(count, start + agentBudget);
+  if (end < count) end -= 1; // reserve the ↓ marker row
+
+  return {
+    start,
+    end,
+    hiddenAbove: start,
+    hiddenBelow: count - end,
+  };
+}
+
+/**
+ * Return the smallest viewport adjustment that makes an agent visible. The
+ * selected index is 0-based within the agent-only roster; `main` is handled by
+ * FleetList rather than this pure helper.
+ */
+export function ensureFleetSelectionVisible(
+  agentCount: number,
+  selectedAgentIndex: number,
+  viewportStart: number,
+): number {
+  const count = Math.max(0, Math.floor(agentCount));
+  if (count === 0) return 0;
+
+  const selected = 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),
+    Math.max(0, Math.floor(selectedAgentIndex)),
   );
-  const end = Math.min(count, start + visibleCount);
-  return { start, end, hiddenAbove: start, hiddenBelow: count - end };
+  const maxStart = Math.max(0, count - (FLEET_BODY_ROWS - 1));
+  let start = Math.min(maxStart, Math.max(0, Math.floor(viewportStart)));
+  const current = calculateFleetAgentWindow(count, start);
+
+  if (selected < current.start) {
+    return Math.min(maxStart, selected);
+  }
+  if (selected < current.end) return start;
+
+  // With a possible ↓ marker, selected - 1 is the least forward shift that
+  // exposes the selected row while preserving the marker row budget.
+  return Math.min(maxStart, Math.max(start, selected - 1));
 }
 
 /**
@@ -107,6 +159,7 @@ export class FleetList {
   private inputUnsub: (() => void) | undefined;
   private widgetRegistered = false;
   private lastRosterKey: string | undefined;
+  private lastRenderKey: string | undefined;
   private timer: ReturnType<typeof setInterval> | undefined;
 
   private enabled = true;
@@ -114,6 +167,8 @@ export class FleetList {
   private active = false;
   /** 0 = `main`, 1..N = subagents. */
   private selectedIndex = 0;
+  /** 0-based start in the agent-only roster; main is rendered separately. */
+  private viewportStart = 0;
   /** Set while a conversation overlay is open; calling it closes the overlay. */
   private viewerClose: (() => void) | undefined;
   private viewingAgentId: string | undefined;
@@ -136,14 +191,23 @@ export class FleetList {
   }
 
   /** Capture the UI context and (re)register the global input handler. */
-  setUICtx(ui: FleetUICtx): void {
-    if (ui === this.ui) return;
+  setUICtx(ui: FleetUICtx): boolean {
+    if (ui === this.ui) return false;
     this.inputUnsub?.();
     this.ui = ui;
     this.widgetRegistered = false;
     this.lastRosterKey = undefined;
+    this.lastRenderKey = undefined;
     this.tui = undefined;
     this.inputUnsub = ui.onTerminalInput(data => this.handleKey(data));
+    return true;
+  }
+
+  /** Request a render on the currently registered TUI without touching input. */
+  requestUiRefresh(force = true): boolean {
+    if (!this.tui) return false;
+    this.tui.requestRender(force);
+    return true;
   }
 
   /** Ensure the re-render timer is running (called when an agent spawns). */
@@ -168,8 +232,11 @@ export class FleetList {
     if (this.ui && this.widgetRegistered) this.ui.setWidget(FLEET_KEY, undefined);
     this.widgetRegistered = false;
     this.lastRosterKey = undefined;
+    this.lastRenderKey = undefined;
     this.tui = undefined;
     this.active = false;
+    this.selectedIndex = 0;
+    this.viewportStart = 0;
     // Null last so a `viewerClose()` microtask above can't re-register the widget.
     this.ui = undefined;
   }
@@ -192,12 +259,16 @@ export class FleetList {
       if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
       this.active = false;
       this.selectedIndex = 0;
+      this.viewportStart = 0;
       this.lastRosterKey = undefined;
+      this.lastRenderKey = undefined;
       return;
     }
 
     this.clampSelection();
+    this.ensureSelectionVisible();
     this.ensureTimer(); // keep stats ticking whenever the list is shown (e.g. after a re-enable)
+    const renderKey = this.renderKey(records);
 
     if (!this.widgetRegistered) {
       this.ui.setWidget(FLEET_KEY, (tui, theme) => {
@@ -205,12 +276,47 @@ export class FleetList {
         return {
           render: (w: number) => this.renderBar(w, theme),
           invalidate: () => { this.widgetRegistered = false; this.tui = undefined; },
+          handleMouse: (event: FleetMouseEvent) => this.handleMouse(event),
         };
       }, { placement: "belowEditor" });
       this.widgetRegistered = true;
-    } else {
+    } else if (renderKey !== this.lastRenderKey) {
+      // The timer runs more frequently than elapsed time is displayed. Avoid
+      // waking the TUI when the visible FleetView snapshot is unchanged, but
+      // preserve a forced redraw when rows were added/removed.
       this.tui?.requestRender(rosterChanged);
     }
+    this.lastRenderKey = renderKey;
+  }
+
+  /**
+   * Return only values that affect `renderBar()`. Elapsed time is rendered in
+   * whole seconds, so the 200ms timer can skip four out of five updates while
+   * still refreshing the row at the visible cadence.
+   */
+  private renderKey(records: AgentRecord[]): string {
+    const now = Date.now();
+    const agentState = records.map(record => {
+      const activity = this.agentActivity.get(record.id);
+      const usage = activity?.lifetimeUsage ?? record.lifetimeUsage;
+      return [
+        record.id,
+        record.type,
+        record.description,
+        record.status,
+        record.startedAt,
+        record.completedAt ?? "",
+        getLifetimeTotal(usage),
+        Math.round(((record.completedAt ?? now) - record.startedAt) / 1000),
+      ].join("\u001f");
+    });
+    return [
+      this.enabled ? "1" : "0",
+      this.active ? "1" : "0",
+      String(this.selectedIndex),
+      String(this.viewportStart),
+      ...agentState,
+    ].join("\u001e");
   }
 
   // ---- Roster ----
@@ -237,8 +343,84 @@ export class FleetList {
     if (this.selectedIndex < 0) this.selectedIndex = 0;
   }
 
+  /** Keep the selected agent visible without recentering an already-valid window. */
+  private ensureSelectionVisible(): void {
+    const agents = this.agentRecords();
+    if (agents.length === 0) {
+      this.viewportStart = 0;
+      return;
+    }
+    if (this.selectedIndex > 0) {
+      this.viewportStart = ensureFleetSelectionVisible(
+        agents.length,
+        this.selectedIndex - 1,
+        this.viewportStart,
+      );
+      return;
+    }
+    // `main` does not constrain the agent window, but a roster shrink can make
+    // its previous start invalid. Use the same pure clamp as renderBar.
+    this.viewportStart = calculateFleetAgentWindow(agents.length, this.viewportStart).start;
+  }
+
   // ---- Key handling ----
 
+  /**
+   * Move the selection while keeping keyboard and wheel input on one path.
+   * Returns whether the direction was handled; inactive upward input and input
+   * that cannot activate the list are left for the editor/transcript.
+   */
+  private moveSelection(direction: -1 | 1): boolean {
+    const max = this.roster().length - 1;
+    if (max < 0) return false;
+
+    if (!this.active) {
+      // Match ↓ activation: only a downward direction at an empty prompt with
+      // the editor focused enters the list. Upward input remains a no-op.
+      if (direction !== 1 || !this.editorHasFocus() || this.agentRecords().length === 0 || this.ui?.getEditorText() !== "") {
+        return false;
+      }
+      this.active = true;
+      this.selectedIndex = 0;
+      this.viewportStart = 0;
+      this.update();
+      return true;
+    }
+
+    this.clampSelection();
+    if (direction === -1 && this.selectedIndex === 0) {
+      this.deactivate();
+      return true;
+    }
+    this.selectedIndex = direction === 1
+      ? Math.min(max, this.selectedIndex + 1)
+      : Math.max(0, this.selectedIndex - 1);
+    this.ensureSelectionVisible();
+    this.update();
+    return true;
+  }
+
+  /** Handle normalized wheel input from the registered widget. */
+  handleMouse(event: FleetMouseEvent): FleetMouseResult | undefined {
+    if (!this.enabled || !this.ui || this.viewerClose) return undefined;
+    if (event.type !== "wheel") return undefined;
+
+    const wheelDelta = event.wheelDelta;
+    const direction: -1 | 1 | undefined = wheelDelta == null
+      ? undefined
+      : wheelDelta < 0
+        ? -1
+        : wheelDelta > 0
+          ? 1
+          : undefined;
+    if (!direction || !this.moveSelection(direction)) return undefined;
+
+    // The widget handled the normalized wheel, including at selection
+    // boundaries; explicitly request a redraw so it never falls through to
+    // Pi's transcript fallback.
+    return { handled: true, render: true };
+  }
+
   /** Returns `{consume:true}` to swallow a key, or undefined to let it through. */
   handleKey(data: string): { consume?: boolean; data?: string } | undefined {
     if (!this.enabled || !this.ui) return undefined;
@@ -257,31 +439,17 @@ export class FleetList {
       return undefined;
     }
 
-    if (!this.active) {
-      // Activate: ↓ or ← at an empty prompt moves focus into the list.
-      const isActivator = matchesKey(data, "down") || matchesKey(data, "left");
-      if (isActivator && this.agentRecords().length > 0 && this.ui.getEditorText() === "") {
-        this.active = true;
-        this.selectedIndex = 0;
-        this.update();
-        return { consume: true };
-      }
-      return undefined;
-    }
+    const direction: -1 | 1 | undefined = matchesKey(data, "down") || matchesKey(data, "j")
+      || (!this.active && matchesKey(data, "left"))
+      ? 1
+      : matchesKey(data, "up") || matchesKey(data, "k")
+        ? -1
+        : undefined;
+    if (direction && this.moveSelection(direction)) return { consume: true };
 
-    // Active — arrows navigate, Enter opens, Esc / Up-past-top exits.
-    if (matchesKey(data, "down")) {
-      const max = this.roster().length - 1;
-      this.selectedIndex = Math.min(max, this.selectedIndex + 1);
-      this.update();
-      return { consume: true };
-    }
-    if (matchesKey(data, "up")) {
-      if (this.selectedIndex === 0) { this.deactivate(); return { consume: true }; }
-      this.selectedIndex -= 1;
-      this.update();
-      return { consume: true };
-    }
+    if (!this.active) return undefined;
+
+    // Active — Enter opens, Esc / Up-past-top exits.
     if (matchesKey(data, "escape")) { this.deactivate(); return { consume: true }; }
     if (matchesKey(data, Key.enter)) { this.openSelected(); return { consume: true }; }
 
@@ -306,6 +474,7 @@ export class FleetList {
   private deactivate(): void {
     this.active = false;
     this.selectedIndex = 0;
+    this.viewportStart = 0;
     this.update();
   }
 
@@ -383,12 +552,12 @@ export class FleetList {
 
     const hint = this.active
       ? "↑↓ select · enter view · esc back"
-      : "esc to interrupt · ← for agents · ↓ to manage";
+      : "esc to interrupt · ↓ to manage";
     const lines: string[] = [];
     lines.push(truncateToWidth("  " + theme.fg("dim", hint), width));
     lines.push(truncateToWidth(`  ${this.bullet(0, sel, theme)} main`, width));
 
-    const window = calculateFleetAgentWindow(agents.length, sel);
+    const window = calculateFleetAgentWindow(agents.length, this.viewportStart);
     if (window.hiddenAbove > 0) {
       lines.push(rightAlign("", theme.fg("dim", `↑ ${window.hiddenAbove} more`), width));
     }

package/test/ui/agent-widget.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { AgentManager } from "../../src/agent-manager.js";
 import {
   AgentWidget,
@@ -48,6 +48,25 @@ function renderWidget(
   return { render, widget };
 }
 
+function createWidgetHarness(records: AgentRecord[]) {
+  const manager = { listAgents: () => records } as unknown as AgentManager;
+  let factory: ((tui: any, theme: Theme) => { render(): string[]; invalidate(): void }) | undefined;
+  const tui = {
+    terminal: { columns: 120, rows: 24 },
+    requestRender: vi.fn(),
+  };
+  const ui = {
+    setStatus: vi.fn(),
+    setWidget: vi.fn((_key: string, content: any) => { factory = content; }),
+  };
+  const widget = new AgentWidget(manager, new Map(), () => "all");
+  widget.setUICtx(ui);
+  widget.update();
+  factory?.(tui, theme).render();
+  tui.requestRender.mockClear();
+  return { records, tui, ui, widget, render: () => factory?.(tui, theme).render() ?? [] };
+}
+
 describe("AgentWidget live records", () => {
   it("keeps restored history in the live widget and manager history", () => {
     const manager = new AgentManager();
@@ -120,4 +139,34 @@ describe("AgentWidget live records", () => {
     expect(getWidgetLineBudget(9)).toBe(5);
     expect(getWidgetLineBudget(100)).toBe(MAX_WIDGET_LINES);
   });
+
+  it("does not request a render when a live snapshot is unchanged", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(10_000);
+    try {
+      const running = makeRecord({ id: "running", status: "running", completedAt: undefined });
+      const { widget, tui } = createWidgetHarness([running]);
+
+      widget.update();
+      expect(tui.requestRender).not.toHaveBeenCalled();
+
+      running.description = "changed description";
+      widget.update();
+      expect(tui.requestRender).toHaveBeenCalledTimes(1);
+      widget.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("exposes a safe render-only refresh target", () => {
+    const running = makeRecord({ id: "running", status: "running", completedAt: undefined });
+    const { widget, tui } = createWidgetHarness([running]);
+    tui.requestRender.mockClear();
+
+    expect((widget as any).requestUiRefresh(true)).toBe(true);
+    expect(tui.requestRender).toHaveBeenCalledWith(true);
+    widget.dispose();
+    expect((widget as any).requestUiRefresh(true)).toBe(false);
+  });
 });

package/test/ui/deferred-ui-refresh.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDeferredUiRefresh } from "../../src/ui/deferred-ui-refresh.js";
+
+describe("createDeferredUiRefresh", () => {
+  afterEach(() => vi.useRealTimers());
+
+  it("fires once after the debounce delay", () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const refresh = createDeferredUiRefresh(requestRender);
+
+    refresh.schedule();
+    vi.advanceTimersByTime(49);
+    expect(requestRender).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(requestRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("coalesces repeated schedules and respects the max wait", () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const refresh = createDeferredUiRefresh(requestRender);
+
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(40);
+    refresh.schedule();
+    vi.advanceTimersByTime(39);
+    expect(requestRender).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(requestRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("supports cancel and dispose without firing a stale callback", () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const refresh = createDeferredUiRefresh(requestRender);
+
+    refresh.schedule();
+    refresh.cancel();
+    vi.advanceTimersByTime(250);
+    expect(requestRender).not.toHaveBeenCalled();
+
+    refresh.schedule();
+    refresh.dispose();
+    refresh.schedule();
+    vi.advanceTimersByTime(250);
+    expect(requestRender).not.toHaveBeenCalled();
+  });
+});