@pi-unipi/unipi 2.6.3 → 2.7.0

package/packages/subagents/src/custom-agents.ts

@@ -4,13 +4,18 @@
  * Discovers agent types from:
  * - <workspace>/.unipi/config/agents/*.md (project, highest priority)
  * - ~/.unipi/config/agents/*.md (global)
+ * - packages/subagents/agents/*.md (builtin, lowest priority — pi-subagents parity)
+ *
+ * Recursive subdirectory discovery: project wins name collisions.
  */
 
 import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "./types.js";
+import { parseMemoryFrontmatter } from "./agent-memory.js";
 
 function compareCodeUnits(a: string, b: string): number {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -39,10 +44,132 @@ function getGlobalAgentsDir(): string {
 /** All known built-in tool names. */
 const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
 
+/** Known frontmatter fields (pi-subagents KNOWN_FIELDS + our unipi extensions). */
+const KNOWN_FIELDS = new Set([
+  "name",
+  "display_name",
+  "description",
+  "alias",
+  "aliases",
+  "tools",
+  "disallowed_tools",
+  "model",
+  "fallbackModels",
+  "thinking",
+  "extensions",
+  "skills",
+  "max_turns",
+  "systemPromptMode",
+  "prompt_mode",
+  "inheritProjectContext",
+  "inheritSkills",
+  "defaultContext",
+  "async",
+  "run_in_background",
+  "isolated",
+  "timeoutMs",
+  "toolTimeoutMs",
+  "turnBudget",
+  "skill",
+  "skillPath",
+  "subagentOnlyExtensions",
+  "output",
+  "outputMode",
+  "defaultReads",
+  "defaultProgress",
+  "interactive",
+  "maxSubagentDepth",
+  "completionGuard",
+  "toolBudget",
+  "memory",
+  "enabled",
+  "runner",
+]);
+
+/** Parse a comma-separated frontmatter list (reference parseFrontmatterList). */
+function parseList(raw: unknown): string[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (Array.isArray(raw)) return raw.map(String).map((s) => s.trim()).filter(Boolean);
+  if (typeof raw === "string") return raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return undefined;
+}
+
+/** Default systemPromptMode per reference (delegate appends, others replace). */
+function defaultSystemPromptMode(name: string): "replace" | "append" {
+  return name === "delegate" || name === "explore" ? "append" : "replace";
+}
+
+/** Default inheritProjectContext per reference (delegate only). */
+function defaultInheritProjectContext(name: string): boolean {
+  return name === "delegate";
+}
+
+/** Parse a boolean-ish frontmatter value ("true"/"false" strings or actual booleans). */
+function parseBool(raw: unknown): boolean | undefined {
+  if (raw === "true" || raw === true) return true;
+  if (raw === "false" || raw === false) return false;
+  return undefined;
+}
+
+/** Parse a positive-integer frontmatter value with a visible error. */
+function parsePositiveInt(raw: unknown, label: string): number | undefined {
+  if (raw === undefined || raw === null || raw === "") return undefined;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 2_147_483_647) {
+    throw new Error(`${label} must be a positive integer no greater than 2147483647 (got ${JSON.stringify(raw)})`);
+  }
+  return parsed;
+}
+
+/** Directory names pruned during recursive discovery. */
+const DISCOVERY_PRUNED_DIR_NAMES = new Set(["node_modules", ".git", ".pi", ".unipi"]);
+
+/** List agent .md files recursively under a directory (skips .chain.md, prunes node_modules). */
+function listAgentFilesRecursive(dir: string): string[] {
+  const files: string[] = [];
+  if (!existsSync(dir)) return files;
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    );
+  } catch {
+    return files;
+  }
+  for (const entry of entries) {
+    const filePath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!DISCOVERY_PRUNED_DIR_NAMES.has(entry.name)) {
+        files.push(...listAgentFilesRecursive(filePath));
+      }
+      continue;
+    }
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+    if (!entry.name.endsWith(".md") || entry.name.endsWith(".chain.md")) continue;
+    files.push(filePath);
+  }
+  return files;
+}
+
+/** Builtin agent definition files shipped in packages/subagents/agents/. */
+const BUILTIN_AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "agents");
+
+/** Frontmatter fields stored as-is on the config for later phases. */
+function collectExtraFields(frontmatter: Record<string, unknown>): Record<string, string> | undefined {
+  const extra: Record<string, string> = {};
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (!KNOWN_FIELDS.has(key)) extra[key] = String(value);
+  }
+  return Object.keys(extra).length ? extra : undefined;
+}
+
 /**
- * Load a single agent from a .md file.
+ * Load a single agent from a .md file. Accepts both our legacy unipi frontmatter
+ * (display_name, disallowed_tools, prompt_mode, max_turns, run_in_background,
+ * isolated, enabled) and the pi-subagents reference frontmatter (aliases,
+ * systemPromptMode, inheritProjectContext, defaultContext, timeoutMs, ...).
  */
-function loadAgentFromFile(filePath: string, source: "project" | "global"): AgentConfig | null {
+function loadAgentFromFile(filePath: string, source: "project" | "global" | "builtin"): AgentConfig | null {
   try {
     const content = readFileSync(filePath, "utf-8");
     const { frontmatter, body } = parseFrontmatter(content);
@@ -50,71 +177,142 @@ function loadAgentFromFile(filePath: string, source: "project" | "global"): Agen
     if (!frontmatter || typeof frontmatter !== "object") {
       return null;
     }
+    const fm = frontmatter as Record<string, unknown>;
+
+    // Name: frontmatter name wins; else filename (our legacy convention).
+    const name =
+      (typeof fm.name === "string" && fm.name.trim()) ||
+      filePath.split("/").pop()?.replace(/\.md$/, "") ||
+      "unknown";
+
+    const description =
+      (typeof fm.description === "string" && fm.description) || `${name} agent`;
+
+    // Tools: comma-separated string; unknown tool names kept (mcp/extension tools).
+    const toolsList = parseList(fm.tools);
+    const builtinToolNames = toolsList ?? [...BUILTIN_TOOL_NAMES];
+
+    const aliases = parseList(fm.aliases ?? fm.alias);
 
-    const name = filePath.split("/").pop()?.replace(/\.md$/, "") ?? "unknown";
+    // Prompt mode: reference systemPromptMode or our legacy prompt_mode.
+    const promptModeRaw = fm.systemPromptMode ?? fm.prompt_mode;
+    const promptMode: "replace" | "append" =
+      promptModeRaw === "replace" || promptModeRaw === "append"
+        ? promptModeRaw
+        : defaultSystemPromptMode(name);
 
-    // Parse tools from comma-separated string
-    const toolsStr = (frontmatter as any).tools as string | undefined;
-    const builtinToolNames = toolsStr
-      ? toolsStr.split(",").map((t) => t.trim()).filter((t) => BUILTIN_TOOL_NAMES.includes(t))
-      : [...BUILTIN_TOOL_NAMES];
+    const inheritProjectContext =
+      parseBool(fm.inheritProjectContext) ?? defaultInheritProjectContext(name);
+    const inheritSkills = parseBool(fm.inheritSkills) ?? false;
+
+    const defaultContext =
+      fm.defaultContext === "fork" ? "fork" : fm.defaultContext === "fresh" ? "fresh" : undefined;
+
+    const timeoutMs = parsePositiveInt(fm.timeoutMs, `Agent '${name}' timeoutMs`);
+    const toolTimeoutMs = parsePositiveInt(fm.toolTimeoutMs, `Agent '${name}' toolTimeoutMs`);
+    const maxSubagentDepth =
+      fm.maxSubagentDepth !== undefined && fm.maxSubagentDepth !== null && fm.maxSubagentDepth !== ""
+        ? parsePositiveInt(fm.maxSubagentDepth, `Agent '${name}' maxSubagentDepth`)
+        : undefined;
+
+    let defaultAsync: boolean | undefined;
+    if (fm.async !== undefined) {
+      const parsed = parseBool(fm.async);
+      if (parsed === undefined) {
+        throw new Error(`Agent '${name}' has invalid async frontmatter; expected true or false.`);
+      }
+      defaultAsync = parsed;
+    }
+
+    let outputMode: "inline" | "file-only" | undefined;
+    if (fm.outputMode !== undefined && fm.outputMode !== "") {
+      if (fm.outputMode === "inline" || fm.outputMode === "file-only") outputMode = fm.outputMode;
+      else throw new Error(`Agent '${name}' has invalid outputMode frontmatter; expected 'inline' or 'file-only'.`);
+    }
 
     return {
       name,
-      displayName: (frontmatter as any).display_name as string | undefined,
-      description: ((frontmatter as any).description as string) ?? `${name} agent`,
+      displayName: (fm.display_name as string | undefined) ?? undefined,
+      description,
+      ...(aliases?.length ? { aliases } : {}),
       builtinToolNames,
-      disallowedTools: ((frontmatter as any).disallowed_tools as string | undefined)
-        ?.split(",")
-        .map((t) => t.trim()),
-      extensions: (frontmatter as any).extensions !== false,
-      skills: (frontmatter as any).skills !== false,
-      model: (frontmatter as any).model as string | undefined,
-      thinking: (frontmatter as any).thinking as any,
-      maxTurns: (frontmatter as any).max_turns as number | undefined,
+      disallowedTools: parseList(fm.disallowed_tools),
+      extensions: fm.extensions !== false,
+      skills: fm.skills !== false,
+      ...(parseList(fm.skillPath)?.length ? { skillPath: parseList(fm.skillPath) } : {}),
+      model: (fm.model as string | undefined) || undefined,
+      ...(parseList(fm.fallbackModels)?.length ? { fallbackModels: parseList(fm.fallbackModels) } : {}),
+      thinking: fm.thinking as any,
+      maxTurns: parsePositiveInt(fm.max_turns, `Agent '${name}' max_turns`),
       systemPrompt: body.trim(),
-      promptMode: ((frontmatter as any).prompt_mode as "replace" | "append") ?? "replace",
-      runInBackground: (frontmatter as any).run_in_background as boolean | undefined,
-      isolated: (frontmatter as any).isolated as boolean | undefined,
-      enabled: (frontmatter as any).enabled !== false,
+      promptMode,
+      inheritProjectContext,
+      inheritSkills,
+      ...(defaultContext !== undefined ? { defaultContext } : {}),
+      ...(defaultAsync !== undefined ? { runInBackground: defaultAsync } : {}),
+      runInBackground: (fm.run_in_background as boolean | undefined) ?? defaultAsync,
+      isolated: fm.isolated as boolean | undefined,
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+      ...(toolTimeoutMs !== undefined ? { toolTimeoutMs } : {}),
+      ...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
+      ...(outputMode !== undefined ? { outputMode } : {}),
+      ...(typeof fm.output === "string" && fm.output ? { output: fm.output } : {}),
+      ...(parseList(fm.defaultReads)?.length ? { defaultReads: parseList(fm.defaultReads) } : {}),
+      ...(parseBool(fm.defaultProgress) !== undefined ? { defaultProgress: parseBool(fm.defaultProgress) } : {}),
+      ...(parseMemoryFrontmatter(fm.memory) ? { memory: parseMemoryFrontmatter(fm.memory)! } : undefined),
+      enabled: fm.enabled !== false,
       source,
+      ...(collectExtraFields(fm) ? { extraFields: collectExtraFields(fm) } : {}),
     };
-  } catch {
-    // Corrupted file — backup and skip
+  } catch (err) {
+    // Corrupted file — backup and skip (builtin files rethrow: they ship with us)
+    if (source === "builtin") throw err;
     backupCorrupted(filePath);
     return null;
   }
 }
 
+/**
+ * Load builtin definition-file agents from packages/subagents/agents/.
+ * Loaded at the LOWEST priority: user/global and project agents override by name.
+ */
+export function loadBuiltinFileAgents(): Map<string, AgentConfig> {
+  const agents = new Map<string, AgentConfig>();
+  for (const filePath of listAgentFilesRecursive(BUILTIN_AGENTS_DIR)) {
+    const agent = loadAgentFromFile(filePath, "builtin");
+    if (agent) agents.set(agent.name, agent);
+  }
+  return agents;
+}
+
 /**
  * Load all custom agents from project and global directories.
- * Project agents override global agents with the same name.
+ * Priority: project > global > builtin (code BUILTIN_CONFIGS last).
  */
 export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
   const agents = new Map<string, AgentConfig>();
 
-  // Load global agents first
+  // Builtin file agents first (lowest priority)
+  for (const [name, agent] of loadBuiltinFileAgents()) {
+    agents.set(name, agent);
+  }
+
+  // Global agents (override builtins)
   const globalDir = getGlobalAgentsDir();
   if (existsSync(globalDir)) {
-    const files = readdirSync(globalDir)
-      .filter((f) => f.endsWith(".md"))
-      .sort(compareCodeUnits);
-    for (const file of files) {
-      const agent = loadAgentFromFile(join(globalDir, file), "global");
+    for (const filePath of listAgentFilesRecursive(globalDir)) {
+      const agent = loadAgentFromFile(filePath, "global");
       if (agent) {
         agents.set(agent.name, agent);
       }
     }
   }
 
-  // Load project agents (overrides global)
+  // Project agents (override global + builtin)
   const projectDir = getProjectAgentsDir(cwd);
   if (existsSync(projectDir)) {
-    const files = readdirSync(projectDir)
-      .filter((f) => f.endsWith(".md"))
-      .sort(compareCodeUnits);
-    for (const file of files) {
-      const agent = loadAgentFromFile(join(projectDir, file), "project");
+    for (const filePath of listAgentFilesRecursive(projectDir)) {
+      const agent = loadAgentFromFile(filePath, "project");
       if (agent) {
         agents.set(agent.name, agent);
       }

package/packages/subagents/src/file-system-retry.ts

@@ -0,0 +1,50 @@
+/**
+ * @pi-unipi/subagents — File-system retry ladder
+ *
+ * Ported from pi-subagents src/shared/file-system-retry.ts (the blocking
+ * waitForFileSystemRetry primitive + ladder constants). Env override uses OUR
+ * prefix: UNIPI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS.
+ */
+
+const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
+const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
+
+export const FS_RETRY_MAX_TOTAL_MS_ENV = "UNIPI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS";
+export const BASE_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
+
+export function resolveFileSystemRetryDelays(
+  env: NodeJS.ProcessEnv = process.env,
+  base: readonly number[] = BASE_FILE_SYSTEM_RETRY_DELAYS_MS,
+): readonly number[] {
+  const raw = env[FS_RETRY_MAX_TOTAL_MS_ENV];
+  if (raw === undefined || raw.trim() === "") return base;
+  const budget = Number(raw);
+  if (!Number.isInteger(budget) || budget < 0) {
+    throw new Error(`${FS_RETRY_MAX_TOTAL_MS_ENV} must be a non-negative integer number of milliseconds.`);
+  }
+  let spent = 0;
+  return base.map((delay) => {
+    const remaining = budget - spent;
+    spent += delay;
+    if (remaining <= 0) return 0;
+    return Math.min(delay, remaining);
+  });
+}
+
+export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = resolveFileSystemRetryDelays();
+
+export function waitForFileSystemRetry(delayMs: number): void {
+  if (delayMs <= 0) return;
+  if (WAIT_VIEW) {
+    try {
+      Atomics.wait(WAIT_VIEW, 0, 0, delayMs);
+      return;
+    } catch {
+      // fall through to setTimeout-free busy wait fallback below
+    }
+  }
+  const end = Date.now() + delayMs;
+  while (Date.now() < end) {
+    // Blocking sleep fallback for runtimes without Atomics.wait
+  }
+}

package/packages/subagents/src/fleet-data.ts

@@ -0,0 +1,61 @@
+/**
+ * @pi-unipi/subagents — Async run summaries for the fleet panel
+ *
+ * Reads run dirs (status.json) into lightweight summaries. Ported essence of
+ * pi-subagents async-status.ts listAsyncRuns.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readStatus } from "./async-runner.js";
+
+export interface AsyncRunSummary {
+  runId: string;
+  runDir: string;
+  agent: string;
+  state: string;
+  startedAt: number;
+  taskSummary?: string;
+}
+
+const MAX_CANDIDATES = 100;
+
+/** List async runs (any state), newest first. */
+export function listAsyncRunSummaries(asyncDirRoot: string): AsyncRunSummary[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(asyncDirRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const summaries: AsyncRunSummary[] = [];
+  for (const entry of entries.slice(0, MAX_CANDIDATES)) {
+    if (!entry.isDirectory()) continue;
+    const runDir = path.join(asyncDirRoot, entry.name);
+    const status = readStatus(runDir);
+    if (!status.status) continue;
+    summaries.push({
+      runId: entry.name,
+      runDir,
+      agent: typeof status.agent === "string" ? status.agent : "unknown",
+      state: String(status.status),
+      startedAt:
+        typeof status.startedAt === "number"
+          ? status.startedAt
+          : typeof status.updatedAt === "number"
+            ? status.updatedAt
+            : statMtime(runDir),
+      ...(typeof status.task === "string" ? { taskSummary: status.task.slice(0, 120) } : {}),
+    });
+  }
+  return summaries.sort((left, right) => right.startedAt - left.startedAt);
+}
+
+function statMtime(dir: string): number {
+  try {
+    return fs.statSync(dir).mtimeMs;
+  } catch {
+    return Date.now();
+  }
+}