@pi-unipi/subagents 2.6.1 → 2.6.2

package/src/retained-children.ts

@@ -0,0 +1,176 @@
+/**
+ * @pi-unipi/subagents — Retained children + resume
+ *
+ * Ported from pi-subagents src/runs/background/retained-children.ts (core).
+ * Completed workflow children from the current parent session stay
+ * addressable: children.list shows up to 10 (newest first, a resumable child
+ * retained when available) with explicit resumable/not-resumable state.
+ * Resume only rows reported resumable; the revived child keeps its stored
+ * agent/model/tool contract and gets the follow-up task.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ASYNC_DIR } from "./parity-types.js";
+import { readStatus } from "./async-runner.js";
+
+const MAX_RETAINED_CHILDREN = 10;
+const MAX_RETAINED_CHILD_CANDIDATES = 100;
+const MAX_TASK_SUMMARY_LENGTH = 120;
+
+export type RetainedChildState = "completed" | "failed" | "paused" | "stopped";
+
+export type RetainedChildResumability =
+  | { state: "resumable"; sessionPath: string }
+  | { state: "not-resumable"; reason: string };
+
+export interface RetainedChild {
+  runId: string;
+  state: RetainedChildState;
+  agent: string;
+  taskSummary: string;
+  completedAt: number;
+  resumability: RetainedChildResumability;
+  sessionPath?: string;
+}
+
+function isRetainedChildState(state: unknown): state is RetainedChildState {
+  return state === "completed" || state === "failed" || state === "paused" || state === "stopped";
+}
+
+function retainedSessionFile(sessionFile: string | undefined): RetainedChildResumability {
+  if (!sessionFile) return { state: "not-resumable", reason: "no persisted session file" };
+  if (!sessionFile.endsWith(".jsonl")) return { state: "not-resumable", reason: "persisted session file is not a .jsonl file" };
+  try {
+    const stat = fs.lstatSync(sessionFile);
+    if (!stat.isFile() || stat.isSymbolicLink()) return { state: "not-resumable", reason: "persisted session file is not a regular file" };
+    return { state: "resumable", sessionPath: sessionFile };
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { state: "not-resumable", reason: `persisted session file is missing: ${sessionFile}` };
+    }
+    return { state: "not-resumable", reason: `persisted session file could not be inspected: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+function boundedTaskSummary(value: string | undefined): string {
+  const normalized = value?.replace(/\s+/g, " ").trim() ?? "";
+  return normalized.length > MAX_TASK_SUMMARY_LENGTH ? `${normalized.slice(0, MAX_TASK_SUMMARY_LENGTH - 1)}…` : normalized;
+}
+
+/** List terminal async runs from this session with their resumability. */
+export function listRetainedChildren(asyncDirRoot: string = ASYNC_DIR, sessionId?: string): RetainedChild[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(asyncDirRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const children: RetainedChild[] = [];
+  for (const entry of entries.slice(0, MAX_RETAINED_CHILD_CANDIDATES)) {
+    if (!entry.isDirectory()) continue;
+    const runDir = path.join(asyncDirRoot, entry.name);
+    const status = readStatus(runDir);
+    if (!isRetainedChildState(status.status)) continue;
+    if (sessionId && status.sessionId !== sessionId) continue;
+
+    const completedAt =
+      typeof status.updatedAt === "number" ? status.updatedAt : statMtime(runDir);
+    if (completedAt === undefined) continue;
+
+    // Reference rule: stopped runs are never resumable.
+    if (status.status === "stopped") {
+      const agent = typeof status.agent === "string" ? status.agent : "unknown";
+      const completedAt2 = typeof status.updatedAt === "number" ? status.updatedAt : statMtime(runDir);
+      if (completedAt2 === undefined) continue;
+      children.push({
+        runId: entry.name,
+        state: "stopped",
+        agent,
+        taskSummary: boundedTaskSummary(typeof status.task === "string" ? status.task : undefined),
+        completedAt: completedAt2,
+        resumability: { state: "not-resumable", reason: "stopped run" },
+      });
+      continue;
+    }
+
+    const agent = typeof status.agent === "string" ? status.agent : "unknown";
+    const taskSummary = boundedTaskSummary(typeof status.task === "string" ? status.task : undefined);
+    const resumability = retainedSessionFile(
+      typeof status.sessionFile === "string" ? status.sessionFile : undefined,
+    );
+
+    children.push({
+      runId: entry.name,
+      state: status.status,
+      agent,
+      taskSummary,
+      completedAt,
+      resumability,
+      ...(resumability.state === "resumable" ? { sessionPath: resumability.sessionPath } : {}),
+    });
+  }
+
+  return children.sort((left, right) => right.completedAt - left.completedAt);
+}
+
+function statMtime(dir: string): number | undefined {
+  try {
+    return fs.statSync(dir).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+export function formatRetainedChildren(children: RetainedChild[]): string {
+  if (children.length === 0) {
+    return "No retained workflow children in the active parent session. If a retained-writer challenge is required, launch a same-role fallback challenge and label it as fallback.";
+  }
+  const retained = children.slice(0, MAX_RETAINED_CHILDREN);
+  if (!retained.some((child) => child.resumability.state === "resumable")) {
+    const resumable = children.slice(MAX_RETAINED_CHILDREN).find((child) => child.resumability.state === "resumable");
+    if (resumable && retained.length === MAX_RETAINED_CHILDREN) retained[MAX_RETAINED_CHILDREN - 1] = resumable;
+  }
+  const hasResumableChild = retained.some((child) => child.resumability.state === "resumable");
+  return [
+    `Retained workflow children (up to ${MAX_RETAINED_CHILDREN}; newest first, with a resumable child retained when available):`,
+    ...retained.flatMap((child) => [
+      `- ${child.runId} | ${child.agent} | ${child.state} | ${new Date(child.completedAt).toISOString()}`,
+      `  task: ${child.taskSummary || "(no task summary)"}`,
+      child.resumability.state === "resumable"
+        ? "  resumability: resumable"
+        : `  resumability: not resumable (${child.resumability.reason})`,
+      ...(child.resumability.state === "resumable"
+        ? [
+            `  session: ${child.resumability.sessionPath}`,
+            `  resume: spawn_helper({ action: "resume", id: "${child.runId}", message: "..." })`,
+          ]
+        : []),
+    ]),
+    ...(hasResumableChild ? [] : ["No resumable retained child is listed. Launch a same-role fallback challenge and label it as fallback."]),
+  ].join("\n");
+}
+
+/**
+ * Resolve a resume target: only rows reported resumable may resume. Returns
+ * the stored contract (agent name + session file) or an error message.
+ */
+export function resolveResumeTarget(
+  asyncDirRoot: string,
+  runIdOrPrefix: string,
+): { ok: true; runId: string; agent: string; sessionFile: string } | { ok: false; error: string } {
+  const children = listRetainedChildren(asyncDirRoot);
+  const matches = children.filter((child) => child.runId.startsWith(runIdOrPrefix));
+  if (matches.length === 0) {
+    return { ok: false, error: `No retained child matches "${runIdOrPrefix}". Use children.list to see retained runs.` };
+  }
+  if (matches.length > 1) {
+    return { ok: false, error: `"${runIdOrPrefix}" matches ${matches.length} retained children; use a longer prefix.` };
+  }
+  const target = matches[0]!;
+  if (target.resumability.state !== "resumable") {
+    return { ok: false, error: `Run ${target.runId} is not resumable (${target.resumability.reason}).` };
+  }
+  return { ok: true, runId: target.runId, agent: target.agent, sessionFile: target.resumability.sessionPath };
+}

package/src/run-fanout-budget.ts

@@ -0,0 +1,356 @@
+/**
+ * @pi-unipi/subagents — Run fan-out budget (maxSubagentSpawnsPerRun)
+ *
+ * Ported from pi-subagents src/runs/shared/run-fanout-budget.ts. Durable,
+ * file-backed claim directory per top-level run tree; claims are never
+ * refunded; groups admit atomically under an admission lock (stale-lock
+ * reclaim via pid check). Layout under OUR temp root
+ * (unipi-subagents-<scope>/run-fanout-budgets).
+ */
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS,
+  waitForFileSystemRetry,
+} from "./file-system-retry.js";
+import { TEMP_ROOT_DIR } from "./parity-types.js";
+
+const RUN_FANOUT_ROOT = path.join(TEMP_ROOT_DIR, "run-fanout-budgets");
+
+export interface RunFanoutBudgetDescriptor {
+  version: 1;
+  rootRunId: string;
+  directory: string;
+  limit: number;
+  parentPath?: string;
+}
+
+export interface RunFanoutBudgetSnapshot {
+  used: number;
+  limit: number;
+  remaining: number;
+}
+
+export interface RunFanoutRejection extends RunFanoutBudgetSnapshot {
+  code: "RUN_FANOUT_LIMIT";
+  path: string;
+  requested: number;
+}
+
+export class RunFanoutLimitError extends Error {
+  readonly rejection: RunFanoutRejection;
+  readonly snapshot: RunFanoutBudgetSnapshot;
+
+  constructor(rejection: RunFanoutRejection) {
+    super(formatRunFanoutRejection(rejection));
+    this.name = "RunFanoutLimitError";
+    this.rejection = rejection;
+    this.snapshot = { used: rejection.used, limit: rejection.limit, remaining: rejection.remaining };
+  }
+}
+
+interface ManifestV1 {
+  version: 1;
+  rootRunId: string;
+  limit: number;
+  createdAt: number;
+}
+
+interface ClaimV1 {
+  version: 1;
+  claimId: string;
+  path: string;
+  claimedAt: number;
+}
+
+function safeRootRunId(rootRunId: string): string {
+  return rootRunId.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || randomUUID();
+}
+
+function parseManifest(value: unknown): ManifestV1 | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const manifest = value as Partial<ManifestV1>;
+  if (
+    manifest.version !== 1 ||
+    typeof manifest.rootRunId !== "string" ||
+    !manifest.rootRunId ||
+    !Number.isInteger(manifest.limit) ||
+    (manifest.limit ?? 0) <= 0 ||
+    typeof manifest.createdAt !== "number" ||
+    !Number.isFinite(manifest.createdAt)
+  ) {
+    return undefined;
+  }
+  return manifest as ManifestV1;
+}
+
+function readManifest(directory: string): ManifestV1 {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(directory, "manifest.json"), "utf-8"));
+  } catch (error) {
+    throw new Error(
+      `Run fan-out budget manifest is unreadable at '${directory}': ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const manifest = parseManifest(parsed);
+  if (!manifest) throw new Error(`Run fan-out budget manifest is invalid at '${directory}'.`);
+  return manifest;
+}
+
+function validateDirectory(directory: string): string {
+  let realDirectory: string;
+  let realRoot: string;
+  try {
+    realDirectory = fs.realpathSync(path.resolve(directory));
+    realRoot = fs.realpathSync(path.resolve(RUN_FANOUT_ROOT));
+  } catch (error) {
+    throw new Error(
+      `Run fan-out budget directory is unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (realDirectory !== realRoot && !realDirectory.startsWith(`${realRoot}${path.sep}`)) {
+    throw new Error("Run fan-out budget directory resolves outside the managed budget root.");
+  }
+  return realDirectory;
+}
+
+export function createRunFanoutBudget(rootRunId: string, limit: number): RunFanoutBudgetDescriptor {
+  if (!Number.isInteger(limit) || limit <= 0) throw new Error("Run fan-out limit must be a positive integer.");
+  fs.mkdirSync(RUN_FANOUT_ROOT, { recursive: true, mode: 0o700 });
+  let directory: string;
+  do {
+    directory = path.join(RUN_FANOUT_ROOT, `${safeRootRunId(rootRunId)}-${randomUUID()}`);
+  } while (fs.existsSync(directory));
+  fs.mkdirSync(path.join(directory, "claims"), { recursive: true, mode: 0o700 });
+  const manifest: ManifestV1 = { version: 1, rootRunId, limit, createdAt: Date.now() };
+  fs.writeFileSync(path.join(directory, "manifest.json"), `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: "wx" });
+  return { version: 1, rootRunId, directory, limit };
+}
+
+export function validateRunFanoutBudgetDescriptor(value: unknown): RunFanoutBudgetDescriptor {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Run fan-out budget descriptor is missing or invalid.");
+  }
+  const descriptor = value as Partial<RunFanoutBudgetDescriptor>;
+  if (
+    descriptor.version !== 1 ||
+    typeof descriptor.rootRunId !== "string" ||
+    !descriptor.rootRunId ||
+    typeof descriptor.directory !== "string" ||
+    !descriptor.directory ||
+    !Number.isInteger(descriptor.limit) ||
+    (descriptor.limit ?? 0) <= 0 ||
+    (descriptor.parentPath !== undefined && typeof descriptor.parentPath !== "string")
+  ) {
+    throw new Error("Run fan-out budget descriptor is invalid.");
+  }
+  const directory = validateDirectory(descriptor.directory);
+  const manifest = readManifest(directory);
+  if (manifest.rootRunId !== descriptor.rootRunId || manifest.limit !== descriptor.limit) {
+    throw new Error("Run fan-out budget descriptor does not match its manifest.");
+  }
+  return {
+    version: 1,
+    rootRunId: descriptor.rootRunId,
+    directory,
+    limit: descriptor.limit,
+    ...(descriptor.parentPath ? { parentPath: descriptor.parentPath } : {}),
+  };
+}
+
+export function writeRunFanoutBudgetDescriptor(asyncDir: string, descriptor: RunFanoutBudgetDescriptor): void {
+  const valid = validateRunFanoutBudgetDescriptor(descriptor);
+  fs.mkdirSync(asyncDir, { recursive: true });
+  fs.writeFileSync(path.join(asyncDir, "run-fanout-budget.json"), `${JSON.stringify(valid)}\n`, { mode: 0o600 });
+}
+
+export function readRunFanoutBudgetDescriptor(asyncDir: string | undefined): RunFanoutBudgetDescriptor | undefined {
+  if (!asyncDir) return undefined;
+  const descriptorPath = path.join(asyncDir, "run-fanout-budget.json");
+  if (!fs.existsSync(descriptorPath)) return undefined;
+  try {
+    return validateRunFanoutBudgetDescriptor(JSON.parse(fs.readFileSync(descriptorPath, "utf-8")));
+  } catch (error) {
+    throw new Error(
+      `Invalid persisted run fan-out budget '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+interface AdmissionLockOwner {
+  pid: number;
+  token: string;
+}
+
+const ADMISSION_LOCK_STALE_MS = 60_000;
+
+function readAdmissionLockOwner(lockPath: string): AdmissionLockOwner | undefined {
+  try {
+    const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf-8")) as Partial<AdmissionLockOwner>;
+    if (Number.isSafeInteger(owner.pid) && (owner.pid ?? 0) > 0 && typeof owner.token === "string" && owner.token) {
+      return owner as AdmissionLockOwner;
+    }
+  } catch {
+    // unreadable = treat as absent
+  }
+  return undefined;
+}
+
+function admissionLockIsStale(lockPath: string): boolean {
+  const owner = readAdmissionLockOwner(lockPath);
+  if (owner) {
+    try {
+      process.kill(owner.pid, 0);
+      return false;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code !== "EPERM";
+    }
+  }
+  try {
+    return Date.now() - fs.statSync(lockPath).mtimeMs > ADMISSION_LOCK_STALE_MS;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function withAdmissionLock<T>(directory: string, operation: () => T): T {
+  const lockPath = path.join(directory, "admission.lock");
+  const owner: AdmissionLockOwner = { pid: process.pid, token: randomUUID() };
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.mkdirSync(lockPath, { mode: 0o700 });
+      try {
+        fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { mode: 0o600 });
+      } catch (error) {
+        fs.rmSync(lockPath, { recursive: true, force: true });
+        throw error;
+      }
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (admissionLockIsStale(lockPath)) {
+        const stalePath = path.join(directory, `admission.stale-${randomUUID()}`);
+        try {
+          fs.renameSync(lockPath, stalePath);
+          fs.rmSync(stalePath, { recursive: true, force: true });
+          continue;
+        } catch (reclaimError) {
+          if ((reclaimError as NodeJS.ErrnoException).code !== "ENOENT") throw reclaimError;
+        }
+      }
+      const delay = DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt];
+      if (delay === undefined) {
+        throw new Error(`Timed out acquiring run fan-out admission lock at '${directory}'.`);
+      }
+      waitForFileSystemRetry(delay);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    if (readAdmissionLockOwner(lockPath)?.token === owner.token) {
+      fs.rmSync(lockPath, { recursive: true, force: true });
+    }
+  }
+}
+
+function claimCount(directory: string): number {
+  const claimsDir = path.join(directory, "claims");
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(claimsDir, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(
+      `Run fan-out claims directory is unreadable at '${claimsDir}': ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return entries.filter((entry) => /^\d{6}\.json$/.test(entry.name)).length;
+}
+
+export function getRunFanoutBudgetSnapshot(descriptor: RunFanoutBudgetDescriptor): RunFanoutBudgetSnapshot {
+  const valid = validateRunFanoutBudgetDescriptor(descriptor);
+  const used = claimCount(valid.directory);
+  return { used, limit: valid.limit, remaining: Math.max(0, valid.limit - used) };
+}
+
+function qualifyRunFanoutPaths(descriptor: RunFanoutBudgetDescriptor, paths: string[]): string[] {
+  const prefix = descriptor.parentPath?.trim();
+  return paths.map((item) => (prefix ? `${prefix}/${item}` : item));
+}
+
+function commitRunFanoutBatch<T>(
+  descriptor: RunFanoutBudgetDescriptor,
+  paths: string[],
+  commit: (snapshot: RunFanoutBudgetSnapshot) => T,
+): T {
+  const valid = validateRunFanoutBudgetDescriptor(descriptor);
+  if (paths.length === 0) return commit(getRunFanoutBudgetSnapshot(valid));
+  const qualified = qualifyRunFanoutPaths(valid, paths);
+  return withAdmissionLock(valid.directory, () => {
+    const before = getRunFanoutBudgetSnapshot(valid);
+    if (qualified.length > before.remaining) {
+      throw new RunFanoutLimitError({
+        code: "RUN_FANOUT_LIMIT",
+        path: qualified[before.remaining] ?? qualified[0]!,
+        requested: qualified.length,
+        ...before,
+      });
+    }
+    const created: string[] = [];
+    try {
+      for (const claimPath of qualified) {
+        for (let slot = 0; slot < valid.limit; slot++) {
+          const slotPath = path.join(valid.directory, "claims", `${String(slot).padStart(6, "0")}.json`);
+          try {
+            const fd = fs.openSync(slotPath, "wx", 0o600);
+            created.push(slotPath);
+            try {
+              const claim: ClaimV1 = { version: 1, claimId: randomUUID(), path: claimPath, claimedAt: Date.now() };
+              fs.writeFileSync(fd, `${JSON.stringify(claim)}\n`, "utf-8");
+            } finally {
+              fs.closeSync(fd);
+            }
+            break;
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+            throw error;
+          }
+        }
+      }
+      return commit(getRunFanoutBudgetSnapshot(valid));
+    } catch (error) {
+      for (const slotPath of created) {
+        try {
+          fs.unlinkSync(slotPath);
+        } catch {
+          // best-effort rollback
+        }
+      }
+      throw error;
+    }
+  });
+}
+
+export function claimRunFanoutBatch(descriptor: RunFanoutBudgetDescriptor, paths: string[]): RunFanoutBudgetSnapshot {
+  return commitRunFanoutBatch(descriptor, paths, (snapshot) => snapshot);
+}
+
+export function claimRunFanoutBatchWithCommit<T>(
+  descriptor: RunFanoutBudgetDescriptor,
+  paths: string[],
+  commit: () => T,
+): T {
+  return commitRunFanoutBatch(descriptor, paths, commit);
+}
+
+export function formatRunFanoutBudget(snapshot: RunFanoutBudgetSnapshot): string {
+  return `Run fan-out: ${snapshot.used}/${snapshot.limit} used, ${snapshot.remaining} remaining`;
+}
+
+function formatRunFanoutRejection(rejection: RunFanoutRejection): string {
+  return `Run fan-out limit reached at ${rejection.path} (${rejection.used}/${rejection.limit} used; ${rejection.requested} requested, ${rejection.remaining} remaining). No children from this admission group were started. Start a new top-level run or raise the maxSubagentSpawnsPerRun config.`;
+}