@pi-unipi/subagents 2.6.0 → 2.6.2

package/src/conversation-viewer.ts

@@ -0,0 +1,281 @@
+/**
+ * @pi-unipi/subagents — Conversation Viewer
+ *
+ * Live-scrolling overlay for viewing agent conversations.
+ * Subscribes to session events for real-time streaming updates.
+ * Supports keyboard navigation: ↑↓, PgUp/PgDn, Home/End, Esc/q to close.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { formatMs, describeActivity } from "./widget.js";
+import {
+  type Component,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import type { AgentActivity } from "./types.js";
+
+/** Lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+
+/** Extract text from content array. */
+function extractText(content: string | Array<{ type: string; text?: string }>): string {
+  if (typeof content === "string") return content;
+  return content
+    .filter((p): p is { type: "text"; text: string } => p.type === "text" && typeof p.text === "string")
+    .map((p) => p.text)
+    .join("");
+}
+
+/** Format tokens compactly. */
+function formatTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M token`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k token`;
+  return `${count} token`;
+}
+
+/** Describe current activity from active tools. */
+
+interface ViewerRecord {
+  type: string;
+  description: string;
+  status: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+}
+
+export class ConversationViewer implements Component {
+  private scrollOffset = 0;
+  private autoScroll = true;
+  private unsubscribe: (() => void) | undefined;
+  private lastInnerW = 0;
+  private closed = false;
+
+  constructor(
+    private tui: TUI,
+    private session: AgentSession,
+    private record: ViewerRecord,
+    private activity: AgentActivity | undefined,
+    private theme: any,
+    private done: (result: undefined) => void,
+  ) {
+    this.unsubscribe = session.subscribe(() => {
+      if (this.closed) return;
+      this.tui.requestRender();
+    });
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.closed = true;
+      this.done(undefined);
+      return;
+    }
+
+    const totalLines = this.buildContentLines(this.lastInnerW).length;
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, totalLines - viewportHeight);
+
+    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "pageUp")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
+      this.autoScroll = false;
+    } else if (matchesKey(data, "pageDown")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "home")) {
+      this.scrollOffset = 0;
+      this.autoScroll = false;
+    } else if (matchesKey(data, "end")) {
+      this.scrollOffset = maxScroll;
+      this.autoScroll = true;
+    }
+  }
+
+  render(width: number): string[] {
+    if (width < 6) return [];
+    const th = this.theme;
+    const innerW = width - 4; // border + padding
+    this.lastInnerW = innerW;
+    const lines: string[] = [];
+
+    const pad = (s: string, len: number) => {
+      const vis = visibleWidth(s);
+      return s + " ".repeat(Math.max(0, len - vis));
+    };
+    const row = (content: string) =>
+      th.fg("border", "│") + " " + truncateToWidth(pad(content, innerW), innerW) + " " + th.fg("border", "│");
+    const hrTop = th.fg("border", `╭${"─".repeat(width - 2)}╮`);
+    const hrBot = th.fg("border", `╰${"─".repeat(width - 2)}╯`);
+    const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+    // Header
+    lines.push(hrTop);
+    const name = this.record.type;
+    const statusIcon =
+      this.record.status === "running"
+        ? th.fg("accent", "●")
+        : this.record.status === "completed"
+          ? th.fg("success", "✓")
+          : this.record.status === "error"
+            ? th.fg("error", "✗")
+            : th.fg("dim", "○");
+
+    const duration = this.record.completedAt
+      ? formatMs(this.record.completedAt - this.record.startedAt)
+      : `${formatMs(Date.now() - this.record.startedAt)} (running)`;
+
+    const headerParts: string[] = [duration];
+    const toolUses = this.activity?.toolUses ?? this.record.toolUses;
+    if (toolUses > 0) headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`);
+    if (this.activity?.session) {
+      try {
+        const tokens = (this.activity.session as any).getSessionStats().tokens.total;
+        if (tokens > 0) headerParts.push(formatTokens(tokens));
+      } catch {
+        /* */
+      }
+    }
+
+    lines.push(
+      row(
+        `${statusIcon} ${th.bold(name)}  ${th.fg("muted", this.record.description)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`,
+      ),
+    );
+    lines.push(hrMid);
+
+    // Content area
+    const contentLines = this.buildContentLines(innerW);
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, contentLines.length - viewportHeight);
+
+    if (this.autoScroll) {
+      this.scrollOffset = maxScroll;
+    }
+
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = contentLines.slice(visibleStart, visibleStart + viewportHeight);
+
+    for (let i = 0; i < viewportHeight; i++) {
+      lines.push(row(visible[i] ?? ""));
+    }
+
+    // Footer
+    lines.push(hrMid);
+    const scrollPct =
+      contentLines.length <= viewportHeight
+        ? "100%"
+        : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
+    const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
+    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+    const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
+    lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
+    lines.push(hrBot);
+
+    return lines;
+  }
+
+  invalidate(): void {
+    /* no cached state to clear */
+  }
+
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  private viewportHeight(): number {
+    return Math.max(MIN_VIEWPORT, this.tui.terminal.rows - CHROME_LINES);
+  }
+
+  private buildContentLines(width: number): string[] {
+    if (width <= 0) return [];
+
+    const th = this.theme;
+    const messages = (this.session as any).messages;
+    const lines: string[] = [];
+
+    if (!messages || messages.length === 0) {
+      lines.push(th.fg("dim", "(waiting for first message...)"));
+      return lines;
+    }
+
+    let needsSeparator = false;
+    for (const msg of messages) {
+      if (msg.role === "user") {
+        const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+        if (!text.trim()) continue;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.fg("accent", "[User]"));
+        for (const line of wrapTextWithAnsi(text.trim(), width)) {
+          lines.push(line);
+        }
+      } else if (msg.role === "assistant") {
+        const textParts: string[] = [];
+        const toolCalls: string[] = [];
+        for (const c of msg.content) {
+          if (c.type === "text" && c.text) textParts.push(c.text);
+          else if (c.type === "tool_use" || c.type === "toolCall") {
+            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
+          }
+        }
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.bold("[Assistant]"));
+        if (textParts.length > 0) {
+          for (const line of wrapTextWithAnsi(textParts.join("\n").trim(), width)) {
+            lines.push(line);
+          }
+        }
+        for (const name of toolCalls) {
+          lines.push(truncateToWidth(th.fg("muted", `  [Tool: ${name}]`), width));
+        }
+      } else if (msg.role === "toolResult") {
+        const text = extractText(msg.content);
+        const truncated = text.length > 500 ? text.slice(0, 500) + "... (truncated)" : text;
+        if (!truncated.trim()) continue;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.fg("dim", "[Result]"));
+        for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
+          lines.push(th.fg("dim", line));
+        }
+      } else if ((msg as any).role === "bashExecution") {
+        const bash = msg as any;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
+        if (bash.output?.trim()) {
+          const out = bash.output.length > 500 ? bash.output.slice(0, 500) + "... (truncated)" : bash.output;
+          for (const line of wrapTextWithAnsi(out.trim(), width)) {
+            lines.push(th.fg("dim", line));
+          }
+        }
+      } else {
+        continue;
+      }
+      needsSeparator = true;
+    }
+
+    // Streaming indicator for running agents
+    if (this.record.status === "running" && this.activity) {
+      const act = describeActivity(this.activity.activeTools, this.activity.responseText);
+      lines.push("");
+      lines.push(truncateToWidth(th.fg("accent", "▍ ") + th.fg("dim", act), width));
+    }
+
+    return lines.map((l) => truncateToWidth(l, width));
+  }
+}

package/src/core-compat.ts

@@ -0,0 +1,94 @@
+/**
+ * @pi-unipi/subagents — Local helpers (not in @pi-unipi/core)
+ *
+ * boundHelperOutput: bounded output with artifact-to-disk fallback.
+ * withHerdrBlocked: wraps a fn with herdr:blocked events.
+ */
+
+import { emitEvent } from "@pi-unipi/core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { chmodSync, lstatSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export interface BoundedHelperOutput {
+  text: string;
+  truncated: boolean;
+  originalBytes: number;
+  artifactPath?: string;
+}
+
+const MAX_RAW_HELPER_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+export function boundHelperOutput(
+  text: string,
+  maxBytes = 64 * 1024,
+  existingArtifactPath?: string,
+): BoundedHelperOutput {
+  const originalBytes = Buffer.byteLength(text, "utf8");
+  if (originalBytes <= maxBytes) return { text, truncated: false, originalBytes };
+
+  let artifactPath = existingArtifactPath;
+  let artifactWarning: string | undefined;
+  if (!artifactPath && originalBytes <= MAX_RAW_HELPER_ARTIFACT_BYTES) {
+    try {
+      const dir = join(homedir(), ".unipi", "tool-results");
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      let stat = lstatSync(dir);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Refusing unsafe tool-result directory: ${dir}`);
+      }
+      if ((stat.mode & 0o077) !== 0) {
+        chmodSync(dir, 0o700);
+        stat = lstatSync(dir);
+        if ((stat.mode & 0o077) !== 0) throw new Error(`Refusing non-private tool-result directory: ${dir}`);
+      }
+      artifactPath = join(dir, `helper-${randomUUID()}.txt`);
+      writeFileSync(artifactPath, text, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    } catch (error) {
+      artifactWarning = `Full-output artifact unavailable: ${error instanceof Error ? error.message : String(error)}`;
+      artifactPath = undefined;
+    }
+  } else if (!artifactPath) {
+    artifactWarning = `Full output exceeded the ${MAX_RAW_HELPER_ARTIFACT_BYTES}-byte local artifact safety cap and was not retained.`;
+  }
+
+  const marker = [
+    "",
+    "--- output bounded by UniPi ---",
+    artifactPath ? `Full output: ${artifactPath}` : artifactWarning!,
+    `Original size: ${originalBytes} bytes; model-visible ceiling: ${maxBytes} bytes.`,
+    ...(artifactPath ? ["Use the read tool with offset/limit to inspect only the needed region."] : []),
+  ].join("\n");
+  const markerBytes = Buffer.byteLength(marker, "utf8");
+  const contentBudget = Math.max(1, maxBytes - markerBytes - 80);
+  const bytes = Buffer.from(text, "utf8");
+  const headBytes = Math.ceil(contentBudget * 0.75);
+  const tailBytes = Math.max(0, contentBudget - headBytes);
+  const head = bytes.subarray(0, headBytes).toString("utf8").replace(/\uFFFD+$/u, "");
+  const tail = bytes.subarray(originalBytes - tailBytes).toString("utf8").replace(/^\uFFFD+/u, "");
+  let bounded = `${head}\n… ${Math.max(0, originalBytes - contentBudget)} bytes omitted …\n${tail}${marker}`;
+  if (Buffer.byteLength(bounded, "utf8") > maxBytes) {
+    bounded = Buffer.from(bounded, "utf8").subarray(0, maxBytes).toString("utf8").replace(/\uFFFD+$/u, "");
+  }
+  return {
+    text: bounded,
+    truncated: true,
+    originalBytes,
+    artifactPath,
+  };
+}
+
+export async function withHerdrBlocked<T>(
+  pi: Pick<ExtensionAPI, "events">,
+  label: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  emitEvent(pi, "herdr:blocked", { active: true, label });
+  try {
+    return await fn();
+  } finally {
+    emitEvent(pi, "herdr:blocked", { active: false, label });
+  }
+}

package/src/custom-agents.ts

@@ -0,0 +1,323 @@
+/**
+ * @pi-unipi/subagents — Custom agent loader
+ *
+ * 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 { 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;
+}
+
+/** Backup a corrupted file by renaming to .bak */
+function backupCorrupted(filePath: string): void {
+  const backupPath = filePath + ".bak";
+  try {
+    renameSync(filePath, backupPath);
+  } catch {
+    // If backup fails, just leave it
+  }
+}
+
+/** Get project agents directory. */
+function getProjectAgentsDir(cwd: string): string {
+  return join(cwd, ".unipi", "config", "agents");
+}
+
+/** Get global agents directory. */
+function getGlobalAgentsDir(): string {
+  return join(homedir(), ".unipi", "config", "agents");
+}
+
+/** 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. 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" | "builtin"): AgentConfig | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    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);
+
+    // 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);
+
+    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: (fm.display_name as string | undefined) ?? undefined,
+      description,
+      ...(aliases?.length ? { aliases } : {}),
+      builtinToolNames,
+      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,
+      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 (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.
+ * Priority: project > global > builtin (code BUILTIN_CONFIGS last).
+ */
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+  const agents = new Map<string, AgentConfig>();
+
+  // 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)) {
+    for (const filePath of listAgentFilesRecursive(globalDir)) {
+      const agent = loadAgentFromFile(filePath, "global");
+      if (agent) {
+        agents.set(agent.name, agent);
+      }
+    }
+  }
+
+  // Project agents (override global + builtin)
+  const projectDir = getProjectAgentsDir(cwd);
+  if (existsSync(projectDir)) {
+    for (const filePath of listAgentFilesRecursive(projectDir)) {
+      const agent = loadAgentFromFile(filePath, "project");
+      if (agent) {
+        agents.set(agent.name, agent);
+      }
+    }
+  }
+
+  return agents;
+}