@herbertgao/pi-subagents 0.19.0 → 0.22.0-local.1

package/src/custom-agents.ts

@@ -1,11 +1,17 @@
 /**
- * custom-agents.ts — Load user-defined agents from project (.pi/agents/, plus the shared .agents/agents/ workspace) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/, plus the shared .agents/agents/ workspace) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations, plus any installed pi package that declares them (see package-resources.ts).
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
 import { basename, join } from "node:path"
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent"
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js"
+import {
+  isPackageResourceExcluded,
+  MAX_PACKAGE_RESOURCE_BYTES,
+  packageAgentDirs,
+  packageAgentFiles,
+} from "./package-resources.js"
 import type {
   AgentConfig,
   IsolationMode,
@@ -28,18 +34,45 @@ import type {
  */
 const RESERVED_IN_TYPE = ":"
 
+/** Where an agent file was found. Widens `AgentConfig.source` for the loader. */
+type AgentSource = "project" | "global" | "package"
+
+/** Answers whether a `!` entry in some package manifest excludes this path. */
+type Excluder = (path: string) => boolean
+
+/**
+ * Overrides for the package tier. The gate and project-trust state normally come
+ * from the session values in package-resources.ts, so these exist for tests and
+ * for a caller that has to pin a scan it already performed.
+ */
+export interface LoadCustomAgentsOptions {
+  /** Explicit package directories, bypassing discovery. */
+  packageDirs?: string[]
+  /** Explicit package files, bypassing discovery. */
+  packageFiles?: string[]
+  /** Explicit `!` exclusion predicate, bypassing discovery. */
+  packageExcluded?: Excluder
+}
+
 /**
  * Scan for custom agent .md files from multiple locations.
  * Discovery hierarchy (higher priority wins):
  *   1. Project:   <cwd>/.pi/agents/*.md (authoritative — also where /agents writes)
  *   2. Workspace: <cwd>/.agents/agents/*.md (shared cross-tool .agents workspace, read-only)
  *   3. Global:    $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *   4. Package:   paths declared by an installed pi package (read-only)
  *
  * Project-level agents override global ones with the same name. On a name clash
  * 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.
  *
+ * Package agents load *first*, so everything the user or project wrote outranks
+ * them. That is what makes them safe to adopt: a package can offer a `reviewer`,
+ * and a `.pi/agents/reviewer.md` silently takes it back. It mirrors pi's own
+ * resource precedence, where package-provided skills rank below every user and
+ * project one, and Claude Code's, where a plugin agent is the lowest tier.
+ *
  * 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
@@ -49,13 +82,25 @@ const RESERVED_IN_TYPE = ":"
 export function loadCustomAgents(
   cwd: string,
   strict = false,
+  opts: LoadCustomAgentsOptions = {},
 ): Map<string, AgentConfig> {
   const globalDir = join(getAgentDir(), "agents")
   const workspaceProjectDir = join(cwd, ".agents", "agents")
   const projectDir = join(cwd, ".pi", "agents")
 
+  const pkgDirs = opts.packageDirs ?? packageAgentDirs(cwd)
+  const pkgFiles = opts.packageFiles ?? packageAgentFiles(cwd)
+  // `!./agents/wip.md` alongside `./agents` excludes one file out of a directory
+  // that is only enumerated here, so the check has to run per file.
+  const excluded: Excluder =
+    opts.packageExcluded ??
+    ((path) => isPackageResourceExcluded(path, cwd, "agents"))
+
   const agents = new Map<string, AgentConfig>()
-  loadFromDir(globalDir, agents, "global", strict) // lowest priority
+  for (const dir of pkgDirs)
+    loadFromDir(dir, agents, "package", strict, excluded) // lowest priority
+  for (const file of pkgFiles) loadOneFile(file, agents, "package", strict)
+  loadFromDir(globalDir, agents, "global", strict)
   loadFromDir(workspaceProjectDir, agents, "project", strict) // shared workspace
   loadFromDir(projectDir, agents, "project", strict) // highest priority (overwrites)
 
@@ -64,12 +109,13 @@ export function loadCustomAgents(
   return agents
 }
 
-/** Load agent configs from a directory into the map. */
+/** Load agent configs from a directory into the map, skipping any `excluded` path. */
 function loadFromDir(
   dir: string,
   agents: Map<string, AgentConfig>,
-  source: "project" | "global",
+  source: AgentSource,
   strict: boolean,
+  excluded?: Excluder,
 ): void {
   if (!existsSync(dir)) return
 
@@ -81,82 +127,128 @@ function loadFromDir(
   }
 
   for (const file of files) {
-    const filenameType = basename(file, ".md")
-
     const path = join(dir, file)
+    if (excluded?.(path)) continue
+    loadOneFile(path, agents, source, strict)
+  }
+}
+
+/**
+ * Load one agent file into the map.
+ *
+ * Split out of `loadFromDir` because a package manifest may name an individual
+ * `.md` rather than a directory, and because the size guard below has to apply
+ * to both paths.
+ */
+function loadOneFile(
+  path: string,
+  agents: Map<string, AgentConfig>,
+  source: AgentSource,
+  strict: boolean,
+): void {
+  const filenameType = basename(path, ".md")
 
-    const parsed = readAgentFile(path, strict)
-    if (!parsed) {
-      warnSkippedOverride(filenameType, agents)
-      continue
-    }
-    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,
-      // 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,
-      extSelectors,
-      disallowedTools: csvListOptional(fm.disallowed_tools),
-      extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
-      excludeExtensions: csvListOptional(fm.exclude_extensions),
-      skills: inheritField(fm.skills ?? fm.inherit_skills),
-      model: str(fm.model),
-      thinking: str(fm.thinking) as ThinkingLevel | undefined,
-      maxTurns: nonNegativeInt(fm.max_turns),
-      persistSession:
-        fm.persist_session != null ? fm.persist_session === true : undefined,
-      outputTranscript:
-        fm.output_transcript != null
-          ? fm.output_transcript !== false
-          : undefined,
-      sessionDir: str(fm.session_dir),
-      allowedSubagents: parseAllowedSubagents(fm.allowed_subagents),
-      systemPrompt: body.trim(),
-      promptMode: fm.prompt_mode === "append" ? "append" : "replace",
-      inheritContext:
-        fm.inherit_context != null ? fm.inherit_context === true : undefined,
-      runInBackground:
-        fm.run_in_background != null
-          ? fm.run_in_background === true
-          : undefined,
-      isolated: fm.isolated != null ? fm.isolated === true : undefined,
-      memory: parseMemory(fm.memory),
-      isolation: parseIsolation(fm.isolation),
-      enabled: fm.enabled !== false, // default true; explicitly false disables
-      source,
-      sourcePath: path,
-    })
+  // Package files are third-party content read on every `Agent` call, so a
+  // pathological one is skipped rather than pulled into the session. Claude
+  // Code applies the same 1 MB ceiling to plugin-provided agents. Local files
+  // are the user's own and stay unbounded, as they always have been.
+  if (source === "package" && !withinSizeLimit(path)) {
+    warnIfNew(
+      `Skipping package agent ${path}: not a regular file, or larger than ${MAX_PACKAGE_RESOURCE_BYTES} bytes.`,
+    )
+    return
+  }
+
+  // `strict` is deliberately not passed for a package file. Failing activation
+  // over a broken agent file is right for a checked-in `.pi/agents/` — the point
+  // is that a repo's own file cannot silently fall through to a same-named one
+  // elsewhere. A file inside a third-party package is not the user's to fix, and
+  // one bad `.md` in any installed package would otherwise stop pi from
+  // starting at all. Warn and skip, as for a non-strict local file.
+  const parsed = readAgentFile(path, strict && source !== "package")
+  if (!parsed) {
+    warnSkippedOverride(filenameType, agents)
+    return
+  }
+  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.
+    return
+  }
+  // `||`, 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,
+    // 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,
+    extSelectors,
+    disallowedTools: csvListOptional(fm.disallowed_tools),
+    extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+    excludeExtensions: csvListOptional(fm.exclude_extensions),
+    skills: inheritField(fm.skills ?? fm.inherit_skills),
+    model: str(fm.model),
+    thinking: str(fm.thinking) as ThinkingLevel | undefined,
+    maxTurns: nonNegativeInt(fm.max_turns),
+    persistSession:
+      fm.persist_session != null ? fm.persist_session === true : undefined,
+    outputTranscript:
+      fm.output_transcript != null ? fm.output_transcript !== false : undefined,
+    sessionDir: str(fm.session_dir),
+    allowedSubagents: parseAllowedSubagents(fm.allowed_subagents),
+    systemPrompt: body.trim(),
+    promptMode: fm.prompt_mode === "append" ? "append" : "replace",
+    inheritContext:
+      fm.inherit_context != null ? fm.inherit_context === true : undefined,
+    runInBackground:
+      fm.run_in_background != null ? fm.run_in_background === true : undefined,
+    isolated: fm.isolated != null ? fm.isolated === true : undefined,
+    memory: parseMemory(fm.memory),
+    isolation: parseIsolation(fm.isolation),
+    enabled: fm.enabled !== false, // default true; explicitly false disables
+    source,
+    sourcePath: path,
+  })
+}
+
+/**
+ * True when `path` is a regular file within the package-resource size ceiling.
+ *
+ * Only applied to package-provided files: they arrive from a third party and are
+ * re-read on every `Agent` call, so a 500 MB `.md` — or a fifo that never ends —
+ * must not be reachable from a spawn. A stat failure counts as "not within",
+ * because the alternative is reading something we could not describe.
+ */
+function withinSizeLimit(path: string): boolean {
+  try {
+    const stat = statSync(path)
+    return stat.isFile() && stat.size <= MAX_PACKAGE_RESOURCE_BYTES
+  } catch {
+    return false
   }
 }