@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.10

package/src/group-join.ts

@@ -0,0 +1,142 @@
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ */
+
+import type { AgentRecord } from "./types.js";
+
+export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
+
+interface AgentGroup {
+  groupId: string;
+  agentIds: Set<string>;
+  completedRecords: Map<string, AgentRecord>;
+  timeoutHandle?: ReturnType<typeof setTimeout>;
+  /** Shorter timeout for stragglers after a partial delivery. */
+  isStraggler: boolean;
+}
+
+/** Default timeout: 30s after first completion in a group. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Straggler re-batch timeout: 15s. */
+const STRAGGLER_TIMEOUT = 15_000;
+
+export class GroupJoinManager {
+  private groups = new Map<string, AgentGroup>();
+  private agentToGroup = new Map<string, string>();
+
+  constructor(
+    private deliverCb: DeliveryCallback,
+    private groupTimeout = DEFAULT_TIMEOUT,
+  ) {}
+
+  /** Register a group of agent IDs that should be joined. */
+  registerGroup(groupId: string, agentIds: string[]): void {
+    const group: AgentGroup = {
+      groupId,
+      agentIds: new Set(agentIds),
+      completedRecords: new Map(),
+      isStraggler: false,
+    };
+    this.groups.set(groupId, group);
+    for (const id of agentIds) {
+      this.agentToGroup.set(id, groupId);
+    }
+  }
+
+  /**
+   * Called when an agent completes.
+   * Returns:
+   * - 'pass'      — agent is not grouped, caller should send individual nudge
+   * - 'held'      — result held, waiting for group completion
+   * - 'delivered'  — this completion triggered the group notification
+   */
+  onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass' {
+    const groupId = this.agentToGroup.get(record.id);
+    if (!groupId) return 'pass';
+
+    const group = this.groups.get(groupId);
+    if (!group) return 'pass';
+
+    group.completedRecords.set(record.id, record);
+
+    // All done — deliver immediately
+    if (group.completedRecords.size >= group.agentIds.size) {
+      this.deliver(group, false);
+      return 'delivered';
+    }
+
+    // First completion in this batch — start timeout
+    if (!group.timeoutHandle) {
+      const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+      group.timeoutHandle = setTimeout(() => {
+        this.onTimeout(group);
+      }, timeout);
+    }
+
+    return 'held';
+  }
+
+  private onTimeout(group: AgentGroup): void {
+    group.timeoutHandle = undefined;
+
+    // Partial delivery — some agents still running
+    const remaining = new Set<string>();
+    for (const id of group.agentIds) {
+      if (!group.completedRecords.has(id)) remaining.add(id);
+    }
+
+    // Clean up agentToGroup for delivered agents (they won't complete again)
+    for (const id of group.completedRecords.keys()) {
+      this.agentToGroup.delete(id);
+    }
+
+    // Deliver what we have
+    this.deliverCb([...group.completedRecords.values()], true);
+
+    // Set up straggler group for remaining agents
+    group.completedRecords.clear();
+    group.agentIds = remaining;
+    group.isStraggler = true;
+    // Timeout will be started when the next straggler completes
+  }
+
+  private deliver(group: AgentGroup, partial: boolean): void {
+    if (group.timeoutHandle) {
+      clearTimeout(group.timeoutHandle);
+      group.timeoutHandle = undefined;
+    }
+    this.deliverCb([...group.completedRecords.values()], partial);
+    this.cleanupGroup(group);
+  }
+
+  private cleanupGroup(group: AgentGroup): void {
+    for (const id of group.agentIds) {
+      this.agentToGroup.delete(id);
+    }
+    this.groups.delete(group.groupId);
+  }
+
+  /** Check if an agent is in a group. */
+  isGrouped(agentId: string): boolean {
+    return this.agentToGroup.has(agentId);
+  }
+
+  /** Release held completions to the outbox before a session transfer. */
+  flushPending(): void {
+    for (const group of [...this.groups.values()]) {
+      this.deliver(group, true);
+    }
+  }
+
+  dispose(): void {
+    for (const group of this.groups.values()) {
+      if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
+    }
+    this.groups.clear();
+    this.agentToGroup.clear();
+  }
+}

package/src/home-paths.ts

@@ -0,0 +1,27 @@
+/** User-scoped paths. Omitted homes keep Pi's call-time runtime defaults. */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Mirror Pi's agent-dir override semantics without changing the process environment. */
+export function resolveAgentDir(homeDir?: string): string {
+  if (homeDir === undefined) return getAgentDir();
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (!configured) return join(homeDir, ".pi", "agent");
+  return normalizeHomePath(configured, homeDir);
+}
+
+/** Pi's normalizePath is not exported by its public package entry point. */
+export function normalizeHomePath(path: string, homeDir = homedir()): string {
+  // Match Pi's native normalization of Git Bash, WSL and Cygwin drive paths.
+  if (process.platform === "win32" && path.startsWith("/") && !path.startsWith("//") && !path.includes("\\")) {
+    const [, letter, remainder] = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i) ?? [];
+    if (letter) path = `${letter.toUpperCase()}:\\${remainder?.replaceAll("/", "\\") ?? ""}`;
+  }
+  if (path === "~") return homeDir;
+  if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) {
+    return join(homeDir, path.slice(2));
+  }
+  return path.startsWith("file://") ? fileURLToPath(path) : path;
+}