pi-harness-delegate 0.2.2 → 0.3.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.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.3.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",