pi-harness-delegate 0.2.2 → 0.4.0

package/extensions/notify.ts

@@ -0,0 +1,50 @@
+/**
+ * Batches successful fan-out completion notifications so `/delegate all …` emits one
+ * notification instead of one per harness. Failures are never delayed or batched — they
+ * flush any pending batch and are emitted immediately. Confined to the notification path;
+ * not a general event system.
+ */
+
+export type NotifyLevel = 'info' | 'warning' | 'error';
+export type NotifyFn = (text: string, level: NotifyLevel) => void;
+
+/** Pure joiner for a batch of success lines — testable without timers. */
+export function joinBatch(lines: string[]): string {
+  if (lines.length === 1) return lines[0];
+  return `${lines.length} runs completed:\n${lines.map(l => `  · ${l}`).join('\n')}`;
+}
+
+export class NotifyBatcher {
+  private pending: string[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly emit: NotifyFn,
+    private readonly debounceMs = 400,
+  ) {}
+
+  /** Queue a successful-completion line; flushes as one combined notification after a quiet period. */
+  success(line: string): void {
+    this.pending.push(line);
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.flush(), this.debounceMs);
+  }
+
+  /** Flush any pending batch immediately, then emit this failure on its own — never delayed. */
+  failure(line: string): void {
+    this.flush();
+    this.emit(line, 'error');
+  }
+
+  /** Emit whatever is pending as one notification, then clear it. No-op when nothing is pending. */
+  flush(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.pending.length === 0) return;
+    const lines = this.pending;
+    this.pending = [];
+    this.emit(joinBatch(lines), 'info');
+  }
+}

package/extensions/progress-multi.ts

@@ -0,0 +1,178 @@
+/**
+ * Live progress window for a concurrent multi-harness `/delegate all` fan-out — one overlay
+ * showing every run as a compact row (harness, elapsed, current activity, done/failed marker)
+ * instead of N stacked overlays or one feed with interleaved lines from different harnesses.
+ *
+ * Single-harness runs keep using `progressWindow` in progress.ts unchanged — this is only
+ * mounted for a fan-out. Shares `fmtElapsed` with it; deliberately not merged into one generic
+ * layout framework since the two views render fundamentally different things (one live feed vs
+ * N row summaries).
+ *
+ * Controls: same as progressWindow — ESC twice to cancel (aborts every in-flight run), `m` to
+ * minimize.
+ */
+
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type Component, Key, matchesKey, type TUI, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { fmtElapsed } from './progress.ts';
+
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPIN_INTERVAL_MS = 100;
+
+export type RunStatus = 'queued' | 'running' | 'done' | 'failed';
+
+export interface RunRow {
+  harness: string;
+  /** Set once the run has acquired its concurrency slot and started executing; null while queued. */
+  startedAt: number | null;
+  status: RunStatus;
+  /**
+   * Short current-activity text (tool call, "thinking…", or a text tail). Empty when queued or
+   * done; on a failed run it holds the failure reason (or the last activity seen), so the row
+   * still says *why* rather than going blank at the moment that matters most.
+   */
+  activity: string;
+}
+
+export interface MultiProgressWindowOptions {
+  /** Mode name shown in the title bar (e.g. "review"). */
+  mode: string;
+  /** Epoch ms when the fan-out started — drives the overall elapsed timer. */
+  startedAt: number;
+  /** Live per-harness row state. */
+  getRows: () => RunRow[];
+  /** Show an "unrestricted permissions" warning banner. */
+  dangerous?: boolean;
+  /** Called when the user confirms cancel — must abort every in-flight run. */
+  onCancel: () => void;
+  /** Called when the user presses `m` (minimize — runs continue in the background). */
+  onMinimize: () => void;
+}
+
+/** Per-status glyphs, matching the row markers in the overlay so the chip and the window read alike. */
+const CHIP_GLYPHS: ReadonlyArray<readonly [RunStatus, string]> = [
+  ['done', '✓'],
+  ['failed', '✗'],
+  ['running', '▶'],
+  ['queued', '…'],
+];
+
+/**
+ * Compact fan-out status-bar summary, e.g. `1✓ 1✗ 1▶ 1…`. Zero counts are omitted, so the common
+ * cases stay short (`4▶`, then `4✓`). Counting only `running` — as the first cut did — renders
+ * `0/4 running`, which reads as idle when runs have actually failed or are queued behind the cap.
+ * Pure — testable without a TUI.
+ */
+export function formatFanoutChip(rows: RunRow[]): string {
+  const parts = CHIP_GLYPHS.map(([status, glyph]) => {
+    const n = rows.filter(r => r.status === status).length;
+    return n > 0 ? `${n}${glyph}` : null;
+  }).filter((s): s is string => s !== null);
+  return parts.length > 0 ? parts.join(' ') : `${rows.length}…`;
+}
+
+/** One row's marker + label, e.g. "✓ claude" / "✗ codex" / "⠋ opencode" / "… amp". Pure — testable
+ *  without a TUI/theme. */
+export function renderRowLabel(row: RunRow, frame: number): string {
+  const mark =
+    row.status === 'done'
+      ? '✓'
+      : row.status === 'failed'
+        ? '✗'
+        : row.status === 'running'
+          ? SPINNER[frame % SPINNER.length]
+          : '…';
+  return `${mark} ${row.harness}`;
+}
+
+/** Create the multi-run overlay component; disposes the spinner timer. */
+export function multiProgressWindow(
+  tui: TUI,
+  theme: Theme,
+  opts: MultiProgressWindowOptions,
+): Component & { dispose(): void } {
+  let frame = 0;
+  let armed = false;
+  let armTimer: ReturnType<typeof setTimeout> | null = null;
+  const timer = setInterval(() => {
+    frame++;
+    tui.requestRender();
+  }, SPIN_INTERVAL_MS);
+
+  const disarm = () => {
+    armed = false;
+    if (armTimer) {
+      clearTimeout(armTimer);
+      armTimer = null;
+    }
+  };
+
+  return {
+    render(width: number): string[] {
+      const inner = Math.max(10, width - 4);
+      const padTo = (s: string, w: number) => `${s}${' '.repeat(Math.max(1, w - visibleWidth(s)))}`;
+      const out: string[] = [];
+      const rows = opts.getRows();
+
+      const done = rows.filter(r => r.status === 'done' || r.status === 'failed').length;
+      const title = `${SPINNER[frame % SPINNER.length]} delegate all · ${opts.mode} · ${done}/${rows.length}`;
+      const status = `⏱ ${fmtElapsed(Date.now() - opts.startedAt)}`;
+      const titleStr = `${title} · ${status}`;
+      const dash = '─'.repeat(Math.max(1, inner - visibleWidth(titleStr) - 2));
+      out.push(theme.fg('accent', `╭─ ${titleStr} ${dash}─╮`));
+
+      if (opts.dangerous) {
+        const banner = theme.fg('error', '⚠ danger — unrestricted access');
+        out.push(`│ ${padTo(banner, inner)} │`);
+      }
+
+      for (const row of rows) {
+        const label = renderRowLabel(row, frame);
+        const styledLabel =
+          row.status === 'done'
+            ? theme.fg('success', label)
+            : row.status === 'failed'
+              ? theme.fg('error', label)
+              : theme.fg('accent', label);
+        const elapsed = row.startedAt !== null ? fmtElapsed(Date.now() - row.startedAt) : 'queued';
+        const activity = row.activity ? ` ${theme.fg('muted', row.activity)}` : '';
+        const line = `${styledLabel} ${theme.fg('dim', elapsed)}${activity}`;
+        out.push(`│ ${padTo(truncateToWidth(line, inner), inner)} │`);
+      }
+
+      const hint = armed
+        ? theme.fg('warning', 'press esc again to cancel all') + theme.fg('dim', ' · m minimize')
+        : theme.fg('dim', 'esc cancel all') + theme.fg('dim', ' · m minimize');
+      out.push(`│ ${padTo(hint, inner)} │`);
+
+      out.push(theme.fg('accent', `╰${'─'.repeat(Math.max(1, width - 2))}╯`));
+      return out;
+    },
+    handleInput(data: string): void {
+      if (matchesKey(data, Key.escape)) {
+        if (armed) {
+          disarm();
+          opts.onCancel();
+        } else {
+          armed = true;
+          armTimer = setTimeout(() => {
+            armed = false;
+            armTimer = null;
+            tui.requestRender();
+          }, 1500);
+          tui.requestRender();
+        }
+      } else if (data === 'm') {
+        disarm();
+        opts.onMinimize();
+      }
+    },
+    invalidate(): void {
+      // stateless render — nothing to clear
+    },
+    dispose(): void {
+      clearInterval(timer);
+      disarm();
+    },
+  };
+}

package/extensions/progress.ts

@@ -16,7 +16,7 @@ const SPIN_INTERVAL_MS = 100;
 const MAX_VISIBLE_ENTRIES = 12;
 
 export type FeedEntry =
-  | { kind: 'tool'; text: string; ok?: boolean }
+  | { kind: 'tool'; text: string; ok?: boolean; id?: string }
   | { kind: 'thinking'; text: string }
   | { kind: 'text'; text: string };
 

package/extensions/run-registry.ts

@@ -0,0 +1,90 @@
+/**
+ * File-based active-run registry — makes the concurrency guard and `/delegate status`
+ * active count accurate across pi processes, not just the current one.
+ *
+ * One small JSON file per active run in `<agentDir>/delegate/runs/`. Best-effort throughout:
+ * registry I/O failures never break a delegation — callers should combine this with their own
+ * in-process counters as a fallback.
+ *
+ * Concurrency cap is best-effort, not a hard mutex: `countActiveRuns()` (read) and
+ * `acquireRun()` (write) are two separate steps with no lock between them, so two pi
+ * processes starting at the same instant can both observe a count under the limit and both
+ * proceed — `maxConcurrent` can be exceeded by a small margin under a tight race. This is a
+ * deliberate simplicity tradeoff (see AGENTS.md); do not rely on it for a hard cap.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentDir } from './config.ts';
+
+function runsDir(): string {
+  return join(agentDir(), 'delegate', 'runs');
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH: no such process. EPERM: exists but we can't signal it — still alive.
+    return (err as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+export interface RunHandle {
+  file: string;
+}
+
+/** Register an active run. Returns null (never throws) if the registry can't be written. */
+export function acquireRun(harness: string, mode: string): RunHandle | null {
+  try {
+    const dir = runsDir();
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${process.pid}-${harness}-${Math.random().toString(36).slice(2, 8)}.json`);
+    writeFileSync(file, JSON.stringify({ pid: process.pid, harness, mode, startedAt: Date.now() }));
+    return { file };
+  } catch {
+    return null;
+  }
+}
+
+/** Release a previously-acquired run. Best-effort — never throws. */
+export function releaseRun(handle: RunHandle | null): void {
+  if (!handle) return;
+  try {
+    rmSync(handle.file, { force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+/** Count active runs across processes (optionally filtered to one harness), cleaning up
+ *  entries left behind by dead processes. Returns 0 (never throws) if the registry is unreadable. */
+export function countActiveRuns(harness?: string): number {
+  let files: string[];
+  try {
+    files = readdirSync(runsDir());
+  } catch {
+    return 0;
+  }
+  let count = 0;
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const full = join(runsDir(), f);
+    try {
+      const data = JSON.parse(readFileSync(full, 'utf8')) as { pid: number; harness: string };
+      if (typeof data.pid === 'number' && isAlive(data.pid)) {
+        if (!harness || data.harness === harness) count++;
+      } else {
+        rmSync(full, { force: true }); // stale (dead pid) or corrupt (non-numeric pid)
+      }
+    } catch {
+      try {
+        rmSync(full, { force: true }); // corrupt entry
+      } catch {
+        // best-effort
+      }
+    }
+  }
+  return count;
+}

package/extensions/templates.ts

@@ -28,6 +28,8 @@ export interface DelegateTemplate {
   skill?: string;
   defaultTask?: string;
   defaultScope?: string;
+  /** Host-run shell command executed after the harness exits to check its claims (e.g. `bun test`). */
+  verify?: string;
   prompt: string;
   harness?: string;
 }
@@ -95,6 +97,7 @@ export function parseTemplate(text: string): DelegateTemplate | null {
     skill: meta.skill || undefined,
     defaultTask: meta.defaultTask || undefined,
     defaultScope: meta.defaultScope || undefined,
+    verify: meta.verify || undefined,
     prompt: m[2].trim(),
     harness: meta.harness || undefined,
   };

package/extensions/usage.ts

@@ -5,16 +5,20 @@ export interface HarnessUsage {
   outputTokens: number;
   cacheCreationInputTokens: number;
   cacheReadInputTokens: number;
-  totalCostUsd: number;
+  /** null when the harness didn't report cost — distinct from a measured $0. */
+  totalCostUsd: number | null;
 }
 
 export type ClaudeUsage = HarnessUsage;
 
 /**
  * Map harness usage/cost into pi's `Usage` shape so delegated runs appear
- * in the pi footer token/cost stats and /session totals.
+ * in the pi footer token/cost stats and /session totals. Returns undefined when cost
+ * is unknown — `Usage.cost.total` is mandatory, so there's no honest number to put there,
+ * and reporting a fake $0 would silently under-report spend in pi's session totals.
  */
-export function mapHarnessUsage(u: HarnessUsage): Usage {
+export function mapHarnessUsage(u: HarnessUsage): Usage | undefined {
+  if (u.totalCostUsd === null) return undefined;
   const input = u.inputTokens + u.cacheCreationInputTokens;
   const cacheRead = u.cacheReadInputTokens;
   const output = u.outputTokens;
@@ -35,6 +39,6 @@ export function mapHarnessUsage(u: HarnessUsage): Usage {
   };
 }
 
-export function mapClaudeUsage(u: ClaudeUsage): Usage {
+export function mapClaudeUsage(u: ClaudeUsage): Usage | undefined {
   return mapHarnessUsage(u);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-delegate",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Delegate work to any harness (Claude Code, Muse, OpenCode, Amp) from the pi coding agent \u2014 code reviews, plans, implementation, security audits, docs, or your own custom templates.",
   "type": "module",
   "packageManager": "bun@1.3.14",