@pi-unipi/subagents 2.6.0 → 2.6.2

package/src/pi-spawn.ts

@@ -0,0 +1,147 @@
+/**
+ * @pi-unipi/subagents — Child pi process spawn command resolution
+ *
+ * Ported from pi-subagents src/runs/shared/pi-spawn.ts. Env override uses OUR
+ * prefix: UNIPI_SUBAGENT_PI_BINARY.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+export const UNIPI_SUBAGENT_PI_BINARY_ENV = "UNIPI_SUBAGENT_PI_BINARY";
+
+export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
+  let dir = path.dirname(entryPoint);
+  while (dir !== path.dirname(dir)) {
+    const packageJsonPath = path.join(dir, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as { name?: unknown };
+      if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+export function resolveInstalledPiPackageRoot(): string | undefined {
+  return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+}
+
+export function resolvePiPackageRoot(): string | undefined {
+  try {
+    const entry = process.argv[1];
+    return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface PiSpawnDeps {
+  platform?: NodeJS.Platform;
+  execPath?: string;
+  argv1?: string;
+  existsSync?: (filePath: string) => boolean;
+  realpathSync?: (filePath: string) => string;
+  readFileSync?: (filePath: string, encoding: "utf8") => string;
+  resolvePackageJson?: () => string;
+  resolvePackageEntry?: () => string;
+  piPackageRoot?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface PiSpawnCommand {
+  command: string;
+  args: string[];
+}
+
+function isRunnableNodeScript(
+  filePath: string,
+  existsSync: (filePath: string) => boolean,
+): boolean {
+  if (!existsSync(filePath)) return false;
+  return /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+
+function normalizePath(filePath: string): string {
+  return path.isAbsolute(filePath) ? path.resolve(filePath) : filePath;
+}
+
+function isStandalonePiExecutable(execPath: string): boolean {
+  const executableName = execPath.split(/[\\/]/).pop();
+  return /^pi(?:\.exe)?$/i.test(executableName ?? "");
+}
+
+export function resolvePiCliScript(deps: PiSpawnDeps = {}): string | undefined {
+  const existsSync = deps.existsSync ?? fs.existsSync;
+  const realpathSync = deps.realpathSync ?? fs.realpathSync;
+  const readFileSync =
+    deps.readFileSync ?? ((filePath: string, encoding: "utf8") => fs.readFileSync(filePath, encoding));
+  const argv1 = deps.argv1 ?? process.argv[1];
+
+  if (argv1) {
+    const argvPath = normalizePath(argv1);
+    if (isRunnableNodeScript(argvPath, existsSync)) {
+      try {
+        const canonicalArgvPath = realpathSync(argvPath);
+        if (isRunnableNodeScript(canonicalArgvPath, existsSync) && findPiPackageRootFromEntry(canonicalArgvPath)) {
+          return canonicalArgvPath;
+        }
+      } catch {
+        // Host package metadata is untrusted here; keep resolving the installed Pi CLI.
+      }
+    }
+  }
+
+  try {
+    const resolvePackageJson =
+      deps.resolvePackageJson ??
+      (() => {
+        const root = deps.piPackageRoot ?? resolvePiPackageRoot();
+        if (root) return path.join(root, "package.json");
+        const packageRoot = deps.resolvePackageEntry
+          ? findPiPackageRootFromEntry(deps.resolvePackageEntry())
+          : resolveInstalledPiPackageRoot();
+        if (!packageRoot) {
+          throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
+        }
+        return path.join(packageRoot, "package.json");
+      });
+    const packageJsonPath = resolvePackageJson();
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      bin?: string | Record<string, string>;
+    };
+    const binField = packageJson.bin;
+    const binPath = typeof binField === "string" ? binField : (binField?.pi ?? Object.values(binField ?? {})[0]);
+    if (!binPath) return undefined;
+    const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
+    if (isRunnableNodeScript(candidate, existsSync)) {
+      return candidate;
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+}
+
+export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
+  const env = deps.env ?? process.env;
+  const piBinary = env[UNIPI_SUBAGENT_PI_BINARY_ENV]?.trim();
+  if (piBinary) {
+    return { command: piBinary, args };
+  }
+
+  const execPath = deps.execPath ?? process.execPath;
+  if (isStandalonePiExecutable(execPath)) {
+    return { command: execPath, args };
+  }
+
+  const piCliPath = resolvePiCliScript(deps);
+  if (piCliPath) {
+    return { command: execPath, args: [piCliPath, ...args] };
+  }
+
+  return { command: "pi", args };
+}

package/src/result-files.ts

@@ -0,0 +1,232 @@
+/**
+ * @pi-unipi/subagents — Durable async result files + indexes
+ *
+ * Ported from pi-subagents src/runs/background/result-files.ts (core).
+ * Results land under OUR RESULTS_DIR (temp root /async-subagent-results):
+ *   <runId>.json                — the result payload
+ *   result-index/runs/<runId>   — run-id index entry
+ *   result-index/sessions/<sid> — session index entries
+ *   result-pending/<sid>/<rid>  — pending delivery markers
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { RESULTS_DIR } from "./parity-types.js";
+
+export const RESULT_INDEX_VERSION = 1;
+const RESULT_INDEX_DIR = "result-index";
+const SESSION_INDEX_DIR = "sessions";
+const RUN_INDEX_DIR = "runs";
+const RESULT_PENDING_DIR = "result-pending";
+
+export interface ResultIndexEntry {
+  version: 1;
+  runId: string;
+  sessionId: string;
+  file: string;
+  writtenAt: number;
+  asyncDir?: string;
+}
+
+export interface ResultFileData {
+  version: 1;
+  runId: string;
+  sessionId: string;
+  agent?: string;
+  output?: string;
+  structuredOutput?: unknown;
+  error?: string;
+  success?: boolean;
+  state?: string;
+  timedOut?: boolean;
+  stopped?: boolean;
+  processSignal?: string | null;
+  durationMs?: number;
+  writtenAt: number;
+}
+
+/** Encode an index segment safely (reference index-segment core). */
+function encodeSegment(value: string): string {
+  const sanitized = value
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return sanitized || "unknown";
+}
+
+export function resultFilePath(resultsDir: string, runId: string): string {
+  return path.join(resultsDir, `${runId}.json`);
+}
+
+function sessionIndexDir(resultsDir: string, sessionId: string): string {
+  return path.join(resultsDir, RESULT_INDEX_DIR, SESSION_INDEX_DIR, encodeSegment(sessionId));
+}
+
+function resultIndexPath(resultsDir: string, sessionId: string, runId: string): string {
+  return path.join(sessionIndexDir(resultsDir, sessionId), `${runId}.json`);
+}
+
+function runIndexPath(resultsDir: string, runId: string): string {
+  return path.join(resultsDir, RESULT_INDEX_DIR, RUN_INDEX_DIR, `${runId}.json`);
+}
+
+function resultPendingPath(resultsDir: string, sessionId: string, runId: string): string {
+  return path.join(resultsDir, RESULT_PENDING_DIR, encodeSegment(sessionId), `${runId}.json`);
+}
+
+function writeAtomicJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+function parseResultIndexEntry(value: unknown): ResultIndexEntry | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const record = value as Partial<ResultIndexEntry>;
+  if (
+    record.version !== RESULT_INDEX_VERSION ||
+    typeof record.runId !== "string" ||
+    !record.runId ||
+    typeof record.sessionId !== "string" ||
+    !record.sessionId ||
+    typeof record.file !== "string" ||
+    !record.file ||
+    typeof record.writtenAt !== "number"
+  ) {
+    return undefined;
+  }
+  return record as ResultIndexEntry;
+}
+
+/** Write the durable result payload + run/session indexes + pending marker. */
+export function writeAsyncResultFile(
+  resultsDir: string,
+  data: Omit<ResultFileData, "version" | "writtenAt">,
+  options: { asyncDir?: string } = {},
+): ResultFileData {
+  const payload: ResultFileData = { ...data, version: 1, writtenAt: Date.now() };
+  const file = resultFilePath(resultsDir, payload.runId);
+  writeAtomicJson(file, payload);
+
+  const entry: ResultIndexEntry = {
+    version: RESULT_INDEX_VERSION,
+    runId: payload.runId,
+    sessionId: payload.sessionId,
+    file,
+    writtenAt: payload.writtenAt,
+    ...(options.asyncDir ? { asyncDir: options.asyncDir } : {}),
+  };
+  writeAtomicJson(runIndexPath(resultsDir, payload.runId), entry);
+  writeAtomicJson(resultIndexPath(resultsDir, payload.sessionId, payload.runId), entry);
+  writeAtomicJson(resultPendingPath(resultsDir, payload.sessionId, payload.runId), entry);
+  return payload;
+}
+
+/** Read a result payload by run id (via the run index). */
+export function readAsyncResultFile(resultsDir: string, runId: string): ResultFileData | undefined {
+  const entry = readResultIndexEntry(runIndexPath(resultsDir, runId));
+  if (!entry) return undefined;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(entry.file, "utf8")) as ResultFileData;
+    if (parsed?.version !== 1 || typeof parsed.runId !== "string") return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function readResultIndexEntry(indexPath: string): ResultIndexEntry | undefined {
+  try {
+    return parseResultIndexEntry(JSON.parse(fs.readFileSync(indexPath, "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
+/** List result index entries for a session. */
+export function resultCandidateFilesForSession(
+  resultsDir: string,
+  sessionId: string,
+): string[] {
+  const dir = sessionIndexDir(resultsDir, sessionId);
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}
+
+/** Remove a pending delivery marker (after delivery or dismissal). */
+export function removePendingResult(resultsDir: string, sessionId: string, runId: string): void {
+  try {
+    fs.unlinkSync(resultPendingPath(resultsDir, sessionId, runId));
+  } catch {
+    // Already gone.
+  }
+}
+
+/** Remove the result payload + all indexes for a run. */
+export function removeResultIndex(resultsDir: string, sessionId: string, runId: string): void {
+  removePendingResult(resultsDir, sessionId, runId);
+  for (const target of [
+    runIndexPath(resultsDir, runId),
+    resultIndexPath(resultsDir, sessionId, runId),
+    resultFilePath(resultsDir, runId),
+  ]) {
+    try {
+      fs.unlinkSync(target);
+    } catch {
+      // Already gone.
+    }
+  }
+}
+
+/** Prune result indexes older than maxAgeMs (default 24h). Returns removed count. */
+export function cleanupResultIndexes(resultsDir: string, now = Date.now(), maxAgeMs = 24 * 60 * 60 * 1000): number {
+  let removed = 0;
+  const indexRoot = path.join(resultsDir, RESULT_INDEX_DIR);
+  let walk: string[];
+  try {
+    walk = [indexRoot];
+  } catch {
+    return 0;
+  }
+  while (walk.length > 0) {
+    const dir = walk.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk.push(entryPath);
+        continue;
+      }
+      if (!entry.name.endsWith(".json")) continue;
+      try {
+        const stat = fs.statSync(entryPath);
+        if (now - stat.mtimeMs > maxAgeMs) {
+          fs.unlinkSync(entryPath);
+          removed++;
+        }
+      } catch {
+        // raced away
+      }
+    }
+  }
+  return removed;
+}
+
+/** Our default results dir. */
+export function defaultResultsDir(): string {
+  return RESULTS_DIR;
+}

package/src/result-watcher.ts

@@ -0,0 +1,221 @@
+/**
+ * @pi-unipi/subagents — Async result watcher
+ *
+ * Ported from pi-subagents src/runs/background/result-watcher.ts (core).
+ * Watches OUR results dir for pending delivery markers, parses payloads,
+ * delivers completion notifications to the owning session, and logs slow
+ * scans per the resultScanLogging config ("all" | "activity" | "off").
+ * Periodic healthy rescans keep cross-session deliveries working.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  readAsyncResultFile,
+  removePendingResult,
+  removeResultIndex,
+  resultCandidateFilesForSession,
+  type ResultFileData,
+} from "./result-files.js";
+
+const POLL_INTERVAL_MS = 3000;
+const HEALTHY_SCAN_INTERVAL_MS = 60_000;
+const SLOW_RESULT_SCAN_MS = 500;
+
+export interface CompletionNotification {
+  runId: string;
+  agent?: string;
+  output?: string;
+  error?: string;
+  success: boolean;
+  state?: string;
+  timedOut?: boolean;
+  durationMs?: number;
+}
+
+export interface ResultWatcherDeps {
+  resultsDir: string;
+  sessionId: string;
+  /** Deliver a completion (e.g. pi.sendMessage notification). */
+  notifier: (notification: CompletionNotification) => void;
+  /** Logging mode for slow scans. Default "all". */
+  resultScanLogging?: "all" | "activity" | "off";
+  /** Test seams. */
+  intervalMs?: number;
+  healthyScanIntervalMs?: number;
+  log?: (message: string) => void;
+}
+
+export interface ResultWatcher {
+  /** Force a scan now. */
+  scan(): Promise<void>;
+  stop(): void;
+}
+
+/**
+ * Create the watcher. Scans the session's pending result markers; for each
+ * found payload, delivers the completion and removes the marker. The full
+ * result payload + indexes are retained for later reads (get_helper_result,
+ * children.list) until retention cleanup.
+ */
+export function createResultWatcher(deps: ResultWatcherDeps): ResultWatcher {
+  const log = deps.log ?? ((message: string) => console.error(message));
+  const scanLogging = deps.resultScanLogging ?? "all";
+  let stopped = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let healthyTimer: ReturnType<typeof setInterval> | undefined;
+  let scanning = false;
+
+  async function scanOnce(): Promise<void> {
+    if (stopped || scanning) return;
+    scanning = true;
+    try {
+      const startedAt = Date.now();
+      const pendingFiles = listPendingFiles(deps.resultsDir, deps.sessionId);
+      const scanDuration = Date.now() - startedAt;
+      const slow = scanDuration > SLOW_RESULT_SCAN_MS;
+      const foundWork = pendingFiles.length > 0;
+
+      if (slow && scanLogging !== "off" && (scanLogging === "all" || foundWork)) {
+        log(
+          `Subagent result scan inspected ${pendingFiles.length} pending marker(s) in ${scanDuration}ms`,
+        );
+      }
+
+      for (const pendingFile of pendingFiles) {
+        const runId = path.basename(pendingFile).replace(/\.json$/, "");
+        const payload = readAsyncResultFile(deps.resultsDir, runId);
+        if (!payload) {
+          // Unreadable/corrupt marker — drop it so it never loops.
+          try {
+            fs.unlinkSync(pendingFile);
+          } catch { /* gone */ }
+          continue;
+        }
+        deps.notifier({
+          runId: payload.runId,
+          ...(payload.agent ? { agent: payload.agent } : {}),
+          ...(payload.output !== undefined ? { output: payload.output } : {}),
+          ...(payload.error ? { error: payload.error } : {}),
+          success: payload.success ?? payload.state === "completed",
+          state: payload.state,
+          timedOut: payload.timedOut,
+          durationMs: payload.durationMs,
+        });
+        removePendingResult(deps.resultsDir, deps.sessionId, runId);
+      }
+    } finally {
+      scanning = false;
+    }
+  }
+
+  // Pending markers for this session live under result-pending/<session>/.
+  function listPendingFiles(resultsDir: string, sessionId: string): string[] {
+    const dir = path.join(resultsDir, "result-pending", sessionId);
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => path.join(dir, entry.name))
+      .sort();
+  }
+
+  function start(): void {
+    const interval = deps.intervalMs ?? POLL_INTERVAL_MS;
+    timer = setInterval(() => {
+      void scanOnce();
+    }, interval);
+    timer.unref?.();
+    const healthyInterval = deps.healthyScanIntervalMs ?? HEALTHY_SCAN_INTERVAL_MS;
+    healthyTimer = setInterval(() => {
+      void scanOnce();
+    }, healthyInterval);
+    healthyTimer.unref?.();
+  }
+
+  start();
+  void scanOnce();
+
+  return {
+    scan: scanOnce,
+    stop(): void {
+      stopped = true;
+      if (timer) clearInterval(timer);
+      if (healthyTimer) clearInterval(healthyTimer);
+    },
+  };
+}
+
+/** Persist a nonBlocking wake subscription: a pending marker for a run that
+ *  has not completed yet. The watcher delivers when the result lands. */
+export function writePendingSubscription(resultsDir: string, sessionId: string, runId: string): void {
+  const dir = path.join(resultsDir, "result-pending", sessionId);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `${runId}.json`);
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, JSON.stringify({ runId, sessionId, subscribedAt: Date.now() }) + "\n", { mode: 0o600 });
+  }
+}
+
+/**
+ * Retention cleanup (ported essence of async-retention.ts): remove terminal
+ * async run dirs + result payloads older than maxAgeMs. Only terminal runs
+ * are eligible; a missing status.json is treated as terminal after the age
+ * window (orphan cleanup).
+ */
+export function cleanupAsyncRetention(
+  asyncDir: string,
+  resultsDir: string,
+  now = Date.now(),
+  maxAgeMs = 24 * 60 * 60 * 1000,
+): { runsRemoved: number; resultsRemoved: number } {
+  let runsRemoved = 0;
+  let resultsRemoved = 0;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(asyncDir, { withFileTypes: true });
+  } catch {
+    return { runsRemoved, resultsRemoved };
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const runDir = path.join(asyncDir, entry.name);
+    try {
+      const stat = fs.statSync(runDir);
+      if (now - stat.mtimeMs <= maxAgeMs) continue;
+      const statusFile = path.join(runDir, "status.json");
+      let terminal = true;
+      if (fs.existsSync(statusFile)) {
+        try {
+          const status = JSON.parse(fs.readFileSync(statusFile, "utf8")) as { status?: string };
+          terminal = !["queued", "running"].includes(String(status.status));
+        } catch {
+          terminal = true; // unreadable = treat as terminal after age window
+        }
+      }
+      if (!terminal) continue;
+      fs.rmSync(runDir, { recursive: true, force: true });
+      runsRemoved++;
+      // Remove the associated result payload + indexes if present.
+      try {
+        const payload = readAsyncResultFile(resultsDir, entry.name);
+        if (payload) {
+          removeResultIndex(resultsDir, payload.sessionId, entry.name);
+          resultsRemoved++;
+        }
+      } catch {
+        // best effort
+      }
+    } catch {
+      // raced away
+    }
+  }
+
+  return { runsRemoved, resultsRemoved };
+}