@pi-unipi/subagents 2.6.0 → 2.6.2

package/src/file-system-retry.ts

@@ -0,0 +1,50 @@
+/**
+ * @pi-unipi/subagents — File-system retry ladder
+ *
+ * Ported from pi-subagents src/shared/file-system-retry.ts (the blocking
+ * waitForFileSystemRetry primitive + ladder constants). Env override uses OUR
+ * prefix: UNIPI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS.
+ */
+
+const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
+const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
+
+export const FS_RETRY_MAX_TOTAL_MS_ENV = "UNIPI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS";
+export const BASE_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
+
+export function resolveFileSystemRetryDelays(
+  env: NodeJS.ProcessEnv = process.env,
+  base: readonly number[] = BASE_FILE_SYSTEM_RETRY_DELAYS_MS,
+): readonly number[] {
+  const raw = env[FS_RETRY_MAX_TOTAL_MS_ENV];
+  if (raw === undefined || raw.trim() === "") return base;
+  const budget = Number(raw);
+  if (!Number.isInteger(budget) || budget < 0) {
+    throw new Error(`${FS_RETRY_MAX_TOTAL_MS_ENV} must be a non-negative integer number of milliseconds.`);
+  }
+  let spent = 0;
+  return base.map((delay) => {
+    const remaining = budget - spent;
+    spent += delay;
+    if (remaining <= 0) return 0;
+    return Math.min(delay, remaining);
+  });
+}
+
+export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = resolveFileSystemRetryDelays();
+
+export function waitForFileSystemRetry(delayMs: number): void {
+  if (delayMs <= 0) return;
+  if (WAIT_VIEW) {
+    try {
+      Atomics.wait(WAIT_VIEW, 0, 0, delayMs);
+      return;
+    } catch {
+      // fall through to setTimeout-free busy wait fallback below
+    }
+  }
+  const end = Date.now() + delayMs;
+  while (Date.now() < end) {
+    // Blocking sleep fallback for runtimes without Atomics.wait
+  }
+}

package/src/fleet-data.ts

@@ -0,0 +1,61 @@
+/**
+ * @pi-unipi/subagents — Async run summaries for the fleet panel
+ *
+ * Reads run dirs (status.json) into lightweight summaries. Ported essence of
+ * pi-subagents async-status.ts listAsyncRuns.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readStatus } from "./async-runner.js";
+
+export interface AsyncRunSummary {
+  runId: string;
+  runDir: string;
+  agent: string;
+  state: string;
+  startedAt: number;
+  taskSummary?: string;
+}
+
+const MAX_CANDIDATES = 100;
+
+/** List async runs (any state), newest first. */
+export function listAsyncRunSummaries(asyncDirRoot: string): AsyncRunSummary[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(asyncDirRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const summaries: AsyncRunSummary[] = [];
+  for (const entry of entries.slice(0, MAX_CANDIDATES)) {
+    if (!entry.isDirectory()) continue;
+    const runDir = path.join(asyncDirRoot, entry.name);
+    const status = readStatus(runDir);
+    if (!status.status) continue;
+    summaries.push({
+      runId: entry.name,
+      runDir,
+      agent: typeof status.agent === "string" ? status.agent : "unknown",
+      state: String(status.status),
+      startedAt:
+        typeof status.startedAt === "number"
+          ? status.startedAt
+          : typeof status.updatedAt === "number"
+            ? status.updatedAt
+            : statMtime(runDir),
+      ...(typeof status.task === "string" ? { taskSummary: status.task.slice(0, 120) } : {}),
+    });
+  }
+  return summaries.sort((left, right) => right.startedAt - left.startedAt);
+}
+
+function statMtime(dir: string): number {
+  try {
+    return fs.statSync(dir).mtimeMs;
+  } catch {
+    return Date.now();
+  }
+}

package/src/fleet-view.ts

@@ -0,0 +1,316 @@
+/**
+ * @pi-unipi/subagents — FleetView (persistent fleet panel)
+ *
+ * pi-subagents parity built on OUR panel system: a persistent setWidget slot
+ * (belowEditor/aboveEditor placement from config) summarizing active work —
+ * in-process agents from the AgentManager plus async process runs from the
+ * run dirs. Collapsed by default; ↓/← activates selection, j/k navigate,
+ * enter opens the inspector, esc deactivates.
+ */
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, Key, truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentManager } from "./agent-manager.js";
+import type { AgentActivity } from "./types.js";
+import { listAsyncRunSummaries, type AsyncRunSummary } from "./fleet-data.js";
+
+const REFRESH_MS = 500;
+const MAX_AGENT_ROWS = 6;
+
+export interface FleetEntry {
+  key: string;
+  source: "inprocess" | "async";
+  agent: string;
+  description?: string;
+  startedAt: number;
+  state: string;
+  /** Run dir for async entries (inspector target). */
+  runDir?: string;
+}
+
+export interface FleetViewOptions {
+  refreshMs?: number;
+  maxAgentRows?: number;
+  placement?: "belowEditor" | "aboveEditor";
+  /** Open the inspector for an entry (wired to ConversationViewer overlay). */
+  openInspector?: (entry: FleetEntry) => Promise<void> | void;
+}
+
+function isActiveState(state: string): boolean {
+  return state === "running" || state === "queued" || state === "pending";
+}
+
+/** Collect active entries across both transports. */
+export function collectFleetEntries(
+  manager: AgentManager,
+  activity: Map<string, AgentActivity>,
+  asyncDirRoot: string,
+): FleetEntry[] {
+  const entries: FleetEntry[] = [];
+
+  for (const record of manager.listAgents()) {
+    if (!isActiveState(record.status)) continue;
+    const act = activity.get(record.id);
+    entries.push({
+      key: `inprocess:${record.id}`,
+      source: "inprocess",
+      agent: record.type,
+      description: record.description,
+      startedAt: record.startedAt,
+      state: record.status,
+    });
+    void act;
+  }
+
+  for (const run of listAsyncRunSummaries(asyncDirRoot)) {
+    if (!isActiveState(run.state)) continue;
+    entries.push({
+      key: `async:${run.runId}`,
+      source: "async",
+      agent: run.agent,
+      description: run.taskSummary,
+      startedAt: run.startedAt,
+      state: run.state,
+      runDir: run.runDir,
+    });
+  }
+
+  return entries.sort((left, right) => left.startedAt - right.startedAt || left.key.localeCompare(right.key));
+}
+
+export class FleetView {
+  private uiCtx: ExtensionUIContext | undefined;
+  private tui: { requestRender(): void } | undefined;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private widgetRegistered = false;
+  private lastRenderKey = "";
+  private entries: FleetEntry[] = [];
+  private active = false;
+  private selectedKey = "main";
+  private inspectorOpen = false;
+
+  constructor(
+    private manager: AgentManager,
+    private activity: Map<string, AgentActivity>,
+    private asyncDirRoot: string,
+    private options: FleetViewOptions = {},
+  ) {}
+
+  setUICtx(ctx: ExtensionUIContext): void {
+    if (ctx === this.uiCtx) return;
+    this.clearRegistration();
+    this.uiCtx = ctx;
+    this.ensureTimer();
+    this.refresh();
+  }
+
+  dispose(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.clearRegistration();
+    this.uiCtx = undefined;
+    this.entries = [];
+    this.active = false;
+    this.selectedKey = "main";
+  }
+
+  /** Called when work starts/finishes to trigger a refresh. */
+  refresh(): void {
+    const ctx = this.uiCtx;
+    if (!ctx) return;
+    this.entries = collectFleetEntries(this.manager, this.activity, this.asyncDirRoot);
+    this.clampSelection();
+
+    if (this.inspectorOpen) {
+      this.lastRenderKey = "";
+      this.clearWidget();
+      return;
+    }
+    if (this.entries.length === 0) {
+      this.active = false;
+      this.selectedKey = "main";
+      this.lastRenderKey = "";
+      this.clearWidget();
+      return;
+    }
+
+    const renderKey = JSON.stringify({
+      active: this.active,
+      selected: this.selectedKey,
+      entries: this.entries.map((e) => [e.key, e.state]),
+    });
+    if (!this.widgetRegistered) {
+      ctx.setWidget(
+        "unipi-fleet-status",
+        (tui: unknown, _theme: unknown) => {
+          this.tui = tui as { requestRender(): void };
+          return {
+            render: (width: number) => this.render(width),
+            invalidate: () => {
+              this.lastRenderKey = "";
+            },
+            dispose: () => {
+              this.widgetRegistered = false;
+              this.tui = undefined;
+            },
+          };
+        },
+        { placement: this.options.placement ?? "belowEditor" },
+      );
+      this.widgetRegistered = true;
+      this.lastRenderKey = renderKey;
+      return;
+    }
+    if (renderKey === this.lastRenderKey) return;
+    this.lastRenderKey = renderKey;
+    this.tui?.requestRender();
+  }
+
+  /**
+   * Key handling for the collapsed/active roster. Returns consume intent.
+   * Wired from index.ts's terminal input hook.
+   */
+  handleKey(data: string, editorHasFocus: () => boolean): { consume?: boolean } | undefined {
+    const ctx = this.uiCtx;
+    if (!ctx || this.entries.length === 0) return undefined;
+    if (this.inspectorOpen) return undefined;
+    if (!editorHasFocus()) {
+      if (this.active) this.deactivate();
+      return undefined;
+    }
+
+    if (!this.active) {
+      const activates = matchesKey(data, "down") || matchesKey(data, "left");
+      if (!activates || ctx.getEditorText?.() !== "") return undefined;
+      this.active = true;
+      this.selectedKey = "main";
+      this.refresh();
+      return { consume: true };
+    }
+
+    const roster = this.rosterKeys();
+    const selectedIndex = Math.max(0, roster.indexOf(this.selectedKey));
+    if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.selectedKey = roster[Math.min(roster.length - 1, selectedIndex + 1)] ?? "main";
+      this.refresh();
+      return { consume: true };
+    }
+    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      if (selectedIndex === 0) {
+        this.deactivate();
+        return { consume: true };
+      }
+      this.selectedKey = roster[selectedIndex - 1] ?? "main";
+      this.refresh();
+      return { consume: true };
+    }
+    if (matchesKey(data, "escape")) {
+      this.deactivate();
+      return { consume: true };
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (this.selectedKey === "main") {
+        this.deactivate();
+        return { consume: true };
+      }
+      const entry = this.entries.find((e) => e.key === this.selectedKey);
+      if (!entry) return undefined;
+      this.inspectorOpen = true;
+      this.refresh();
+      void Promise.resolve()
+        .then(() => this.options.openInspector?.(entry))
+        .catch(() => {})
+        .finally(() => {
+          this.inspectorOpen = false;
+          this.refresh();
+        });
+      return { consume: true };
+    }
+    return undefined;
+  }
+
+  render(width: number): string[] {
+    if (this.entries.length === 0) return [];
+    if (!this.active) {
+      // Collapsed summary row.
+      const count = this.entries.length;
+      const noun = count === 1 ? "agent" : "agents";
+      const states = new Map<string, number>();
+      for (const entry of this.entries) states.set(entry.state, (states.get(entry.state) ?? 0) + 1);
+      const breakdown = [...states.entries()].map(([state, n]) => `${n} ${state}`).join(", ");
+      return [
+        truncateToWidth(`  ${count} active ${noun} (${breakdown}) · ↓ to inspect`, width),
+      ];
+    }
+
+    const roster = this.rosterKeys();
+    const selectedIndex = Math.max(0, roster.indexOf(this.selectedKey));
+    const lines = [truncateToWidth(`  ↑↓/jk select · enter inspect · esc back`, width), ""];
+    lines.push(truncateToWidth(`  ${this.bullet(0, selectedIndex)} main`, width));
+
+    const visibleCount = Math.min(this.options.maxAgentRows ?? MAX_AGENT_ROWS, this.entries.length);
+    const start = selectedIndex < visibleCount ? 0 : selectedIndex - visibleCount + 1;
+    const hiddenBelow = this.entries.length - (start + visibleCount);
+    if (start > 0) lines.push(truncateToWidth(`  ↑ ${start} more`, width));
+    for (let index = start; index < start + visibleCount; index++) {
+      const entry = this.entries[index];
+      if (!entry) break;
+      lines.push(...this.renderEntry(index + 1, selectedIndex, entry, width));
+    }
+    if (hiddenBelow > 0) lines.push(truncateToWidth(`  ↓ ${hiddenBelow} more`, width));
+    return lines;
+  }
+
+  private renderEntry(rosterIndex: number, selectedIndex: number, entry: FleetEntry, width: number): string[] {
+    void rosterIndex;
+    const elapsed = formatElapsed(Date.now() - entry.startedAt);
+    const sourceTag = entry.source === "async" ? "proc" : "local";
+    const left = `  ${this.bullet(-1, selectedIndex)} ${entry.agent} · ${entry.state}`;
+    const right = `${sourceTag} · ${elapsed}`;
+    return [truncateToWidth(`${left}  ${right}`, width)];
+  }
+
+  private bullet(_index: number, selectedIndex: number): string {
+    return selectedIndex > 0 ? ">" : " ";
+  }
+
+  private rosterKeys(): string[] {
+    return ["main", ...this.entries.map((entry) => entry.key)];
+  }
+
+  private clampSelection(): void {
+    if (!this.rosterKeys().includes(this.selectedKey)) this.selectedKey = "main";
+  }
+
+  private deactivate(): void {
+    this.active = false;
+    this.selectedKey = "main";
+    this.refresh();
+  }
+
+  private clearWidget(): void {
+    if (this.widgetRegistered && this.uiCtx) {
+      this.uiCtx.setWidget("unipi-fleet-status", undefined);
+      this.widgetRegistered = false;
+      this.tui = undefined;
+    }
+  }
+
+  private clearRegistration(): void {
+    this.clearWidget();
+  }
+
+  private ensureTimer(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.refresh(), this.options.refreshMs ?? REFRESH_MS);
+    this.timer.unref?.();
+  }
+}
+
+function formatElapsed(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m${seconds % 60}s`;
+  return `${Math.floor(minutes / 60)}h${minutes % 60}m`;
+}

package/src/foreground-detach.ts

@@ -0,0 +1,59 @@
+/**
+ * @pi-unipi/subagents — Foreground detach shortcut
+ *
+ * Ported from pi-subagents foregroundDetachShortcut (config) +
+ * foregroundSingleHintText (render.ts). Optionally binds a shortcut that
+ * detaches the active foreground single-agent run WITHOUT terminating it:
+ * the parent stops waiting, the child keeps running, and the completion
+ * arrives later as a normal task-notification.
+ */
+
+export interface DetachShortcutConfig {
+  /** Shortcut string like "ctrl+b". Empty/unset disables the feature. */
+  shortcut?: string;
+}
+
+/** Parse a shortcut string into normalized parts ("ctrl+b" → ["ctrl","b"]). */
+export function parseDetachShortcut(raw: string | undefined): string[] | undefined {
+  const trimmed = raw?.trim().toLowerCase();
+  if (!trimmed) return undefined;
+  const parts = trimmed.split("+").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0 || parts.some((part) => !part)) return undefined;
+  // Must include at least one modifier to avoid stealing plain keys.
+  const modifiers = new Set(["ctrl", "alt", "shift", "meta", "super"]);
+  if (!parts.slice(0, -1).some((part) => modifiers.has(part))) return undefined;
+  return parts;
+}
+
+/** Human-readable label ("ctrl+b" → "Ctrl+B"). */
+export function formatDetachHint(parts: string[] | undefined): string | undefined {
+  if (!parts) return undefined;
+  const label = parts
+    .map((part) => {
+      if (part === "ctrl") return "Ctrl";
+      if (part === "alt") return "Alt";
+      if (part === "shift") return "Shift";
+      if (part === "escape") return "Esc";
+      if (part.length === 1) return part.toUpperCase();
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+    .join("+");
+  return `${label} detaches (run continues in background)`;
+}
+
+/**
+ * Whether a raw terminal input matches the configured shortcut.
+ * Matches pi-tui-style control sequences for ctrl+<letter> plus literal text
+ * for other combos.
+ */
+export function matchesDetachInput(data: string, parts: string[] | undefined): boolean {
+  if (!parts) return false;
+  const hasCtrl = parts.includes("ctrl");
+  const key = parts[parts.length - 1]!;
+  if (hasCtrl && parts.length === 2 && key.length === 1) {
+    // Control sequence: C0 codes 0x01–0x1a map to ctrl+a–z.
+    const expected = String.fromCharCode(key.charCodeAt(0) - 96);
+    return data === expected;
+  }
+  return data === parts.join("+");
+}