@herbertgao/pi-subagents 0.17.0 → 0.18.0

package/src/custom-agents.ts

@@ -13,12 +13,20 @@ import type {
   ThinkingLevel,
 } from "./types.js"
 
-interface WarningState {
-  previous: Set<string>
-  current: Set<string>
-}
-
-const warningHistoryByCwd = new Map<string, Set<string>>()
+/**
+ * The one thing a declared `name:` may not contain, matching Claude Code
+ * exactly: it reserves `:` for plugin-scoped identifiers (`my-plugin:reviewer`)
+ * and refuses to load a file whose name uses one.
+ *
+ * Nothing else is rejected. Claude Code's docs describe names as "lowercase
+ * letters and hyphens", but that is guidance — the only stated load failure is
+ * the colon, so `name: Code Reviewer` must work here too. (The stricter
+ * letters/digits/underscore/hyphen regex in Claude Code applies to the Agent
+ * tool's spawn-time `name` parameter, which is a different field.) Mixed case
+ * has to be allowed regardless: the built-in types `Explore` and `Plan` use it,
+ * and a file must be able to override one.
+ */
+const RESERVED_IN_TYPE = ":"
 
 /**
  * Scan for custom agent .md files from multiple locations.
@@ -31,6 +39,12 @@ const warningHistoryByCwd = new Map<string, Set<string>>()
  * between the two project locations, .pi/agents wins — .pi stays the project
  * authority; .agents/agents is an additional read location.
  * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ *
+ * An agent's type comes from its frontmatter `name:`, falling back to the
+ * filename — Claude Code's rule, where "the filename doesn't have to match".
+ * Because the type is now declared rather than derived from a unique path, two
+ * files can claim the same one; the later load wins, as it always has for a
+ * filename clash, and `warnSkippedOverride` reports the substitution.
  */
 export function loadCustomAgents(
   cwd: string,
@@ -41,27 +55,12 @@ export function loadCustomAgents(
   const projectDir = join(cwd, ".pi", "agents")
 
   const agents = new Map<string, AgentConfig>()
-  const skippedOverrides = new Set<string>()
-  const warnings: WarningState = {
-    previous: warningHistoryByCwd.get(cwd) ?? new Set(),
-    current: new Set(),
-  }
+  loadFromDir(globalDir, agents, "global", strict) // lowest priority
+  loadFromDir(workspaceProjectDir, agents, "project", strict) // shared workspace
+  loadFromDir(projectDir, agents, "project", strict) // highest priority (overwrites)
 
-  loadFromDir(globalDir, agents, "global", strict, warnings, skippedOverrides) // lowest priority
-  loadFromDir(
-    workspaceProjectDir,
-    agents,
-    "project",
-    strict,
-    warnings,
-    skippedOverrides,
-  ) // shared workspace
-  loadFromDir(projectDir, agents, "project", strict, warnings, skippedOverrides) // highest priority (overwrites)
-
-  for (const name of skippedOverrides) {
-    warnSkippedOverride(name, agents, warnings)
-  }
-  warningHistoryByCwd.set(cwd, warnings.current)
+  warnedLastLoad = warnedThisLoad
+  warnedThisLoad = new Set()
   return agents
 }
 
@@ -71,8 +70,6 @@ function loadFromDir(
   agents: Map<string, AgentConfig>,
   source: "project" | "global",
   strict: boolean,
-  warnings: WarningState,
-  skippedOverrides: Set<string>,
 ): void {
   if (!existsSync(dir)) return
 
@@ -84,22 +81,48 @@ function loadFromDir(
   }
 
   for (const file of files) {
-    const name = basename(file, ".md")
+    const filenameType = basename(file, ".md")
+
     const path = join(dir, file)
 
-    const parsed = readAgentFile(path, strict, warnings)
+    const parsed = readAgentFile(path, strict)
     if (!parsed) {
-      skippedOverrides.add(name)
+      warnSkippedOverride(filenameType, agents)
       continue
     }
-    skippedOverrides.delete(name)
     const { frontmatter: fm, body } = parsed
 
+    // Claude Code's rule: `name:` IS the agent type, and the filename need not
+    // match. Absent, the filename stands in — Claude Code requires the field,
+    // but most files here predate it and must keep loading.
+    const declared = str(fm.name)?.trim()
+    if (declared?.includes(RESERVED_IN_TYPE)) {
+      // Refusing beats silently substituting: the file would otherwise load
+      // under its filename, so `Agent({subagent_type})` would succeed against
+      // an agent whose declared identity nothing honoured.
+      warnIfNew(
+        `Agent file ${path} declares name "${declared}", which contains "${RESERVED_IN_TYPE}" — reserved for ` +
+          "plugin-scoped identifiers. Rename it, or move the label to `display_name:`. Skipping.",
+      )
+      // No `warnSkippedOverride`: this file would have registered under its
+      // *declared* name, which nothing else can hold (a colon keeps it out of
+      // the registry), so it shadowed nothing. Passing the filename instead
+      // would report a substitution of an unrelated agent that never happened.
+      continue
+    }
+    // `||`, not `??`: a quoted empty or all-whitespace `name:` would otherwise
+    // register the agent under the empty type — unspawnable, and it takes the
+    // filename-derived one down with it.
+    const name = declared || filenameType
+
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools)
 
     agents.set(name, {
       name,
-      displayName: str(fm.display_name) ?? str(fm.name),
+      // Only `display_name` now: `name` is the type, and `getConfig` already
+      // falls back to the type when no label is set — so a Claude Code file
+      // with `name: code-reviewer` still badges as "code-reviewer".
+      displayName: str(fm.display_name),
       color: str(fm.color),
       description: str(fm.description) ?? name,
       builtinToolNames,
@@ -139,7 +162,30 @@ function loadFromDir(
 
 /**
  * Read and parse one agent file, or warn and return undefined for the caller to
- * skip. Under strict mode the same failure aborts startup while naming the file.
+ * skip. One bad file must not take the whole extension down with it — an
+ * unparseable `.md` used to abort activation, so pi exited before the TUI.
+ *
+ * The path is as much of the fix as the recovery: a bare YAML error ("line 2,
+ * column 14") is unactionable when agents come from three directories at once,
+ * and the only other symptom is `Unknown agent type`, which reads like a typo.
+ *
+ * Under `strict` the same failure rethrows, still naming the path, so callers
+ * that opted into failing closed stop rather than run a substituted agent.
+ */
+/**
+ * Parse an agent file's frontmatter, tolerating a leading UTF-8 BOM.
+ *
+ * Editors across the Windows/CJK world write UTF-8 with a BOM by default, and
+ * pi's parser did not look past one before 0.84.3: the fence never matched, so
+ * the frontmatter came back empty and the *whole file* — YAML and all — became
+ * the body. An agent authored that way silently lost every field. `tools: none`
+ * going missing is the sharp edge: the agent registers with the default
+ * toolset rather than none, which is a wider grant than its author wrote.
+ *
+ * Stripped here rather than detected per pi version, because this is the only
+ * place agent files are read and the BOM is a file-encoding artifact, not
+ * content — normalising it at the boundary keeps one behaviour across the whole
+ * supported peer range instead of forking on what happens to be installed.
  */
 export function parseAgentFrontmatter<T extends Record<string, unknown>>(
   content: string,
@@ -152,7 +198,6 @@ export function parseAgentFrontmatter<T extends Record<string, unknown>>(
 function readAgentFile(
   path: string,
   strict: boolean,
-  warnings: WarningState,
 ): { frontmatter: Record<string, unknown>; body: string } | undefined {
   try {
     return parseAgentFrontmatter<Record<string, unknown>>(
@@ -161,30 +206,39 @@ function readAgentFile(
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err)
     if (strict) throw new Error(`${path}: ${reason}`)
-    warnIfNew(`Skipping agent file ${path}: ${reason}`, warnings)
+    warnIfNew(`Skipping agent file ${path}: ${reason}`)
     return undefined
   }
 }
 
-/** Warn when a broken higher-priority file exposes an earlier definition. */
+/**
+ * A skipped file that was overriding an already-loaded agent leaves the name
+ * pointing at a *different* file — its own prompt, model and tools. Nothing
+ * downstream can flag that: unlike an unknown type, the `Agent` call succeeds.
+ */
 function warnSkippedOverride(
   name: string,
   agents: Map<string, AgentConfig>,
-  warnings: WarningState,
 ): void {
   const surviving = agents.get(name)
+  // Nothing shadowed, or what it shadowed is disabled: dispatch refuses the type
+  // either way (see resolveEnabledTypeIn), so there is no substitution to report.
   if (!surviving?.sourcePath || surviving.enabled === false) return
-  warnIfNew(
-    `Agent "${name}" now loads from ${surviving.sourcePath} instead`,
-    warnings,
-  )
+  warnIfNew(`Agent "${name}" now loads from ${surviving.sourcePath} instead`)
 }
 
-/** Warn once while an error is unchanged, but report it again after recovery. */
-function warnIfNew(message: string, warnings: WarningState): void {
-  if (warnings.current.has(message)) return
-  warnings.current.add(message)
-  if (warnings.previous.has(message)) return
+let warnedLastLoad = new Set<string>()
+let warnedThisLoad = new Set<string>()
+
+/**
+ * Agents reload on activation and again on every `Agent` call, so an unchanged
+ * problem would re-warn all session — over a painted TUI, since pi does not
+ * redirect console output. Compare against the previous load rather than every
+ * load ever, so a file that is fixed and then broken again still reports.
+ */
+function warnIfNew(message: string): void {
+  warnedThisLoad.add(message)
+  if (warnedLastLoad.has(message)) return
   console.warn(`[pi-subagents] ${message}`)
 }