@esso0428/pi-subagents 0.17.5 → 0.17.7

package/dist/custom-agents.js

@@ -5,6 +5,20 @@ import { existsSync, readdirSync, readFileSync } 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";
+/**
+ * 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.
  * Discovery hierarchy (higher priority wins):
@@ -16,19 +30,27 @@ import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
  * 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) {
+export function loadCustomAgents(cwd, strict = false) {
     const globalDir = join(getAgentDir(), "agents");
     const workspaceProjectDir = join(cwd, ".agents", "agents");
     const projectDir = join(cwd, ".pi", "agents");
     const agents = new Map();
-    loadFromDir(globalDir, agents, "global"); // lowest priority
-    loadFromDir(workspaceProjectDir, agents, "project"); // shared workspace
-    loadFromDir(projectDir, agents, "project"); // highest priority (overwrites)
+    loadFromDir(globalDir, agents, "global", strict); // lowest priority
+    loadFromDir(workspaceProjectDir, agents, "project", strict); // shared workspace
+    loadFromDir(projectDir, agents, "project", strict); // highest priority (overwrites)
+    warnedLastLoad = warnedThisLoad;
+    warnedThisLoad = new Set();
     return agents;
 }
 /** Load agent configs from a directory into the map. */
-function loadFromDir(dir, agents, source) {
+function loadFromDir(dir, agents, source, strict) {
     if (!existsSync(dir))
         return;
     let files;
@@ -39,19 +61,42 @@ function loadFromDir(dir, agents, source) {
         return;
     }
     for (const file of files) {
-        const name = basename(file, ".md");
-        let content;
-        try {
-            content = readFileSync(join(dir, file), "utf-8");
+        const filenameType = basename(file, ".md");
+        const path = join(dir, file);
+        const parsed = readAgentFile(path, strict);
+        if (!parsed) {
+            warnSkippedOverride(filenameType, agents);
+            continue;
         }
-        catch {
+        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;
         }
-        const { frontmatter: fm, body } = parseFrontmatter(content);
+        // `||`, 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,
@@ -65,18 +110,89 @@ function loadFromDir(dir, agents, source) {
             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: fm.isolation === "worktree" ? "worktree" : undefined,
+            isolation: parseIsolation(fm.isolation),
             enabled: fm.enabled !== false, // default true; explicitly false disables
             source,
+            sourcePath: path,
         });
     }
 }
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * 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(content) {
+    return parseFrontmatter(content.startsWith("\uFEFF") ? content.slice(1) : content);
+}
+function readAgentFile(path, strict) {
+    try {
+        return parseAgentFrontmatter(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        if (strict)
+            throw new Error(`${path}: ${reason}`);
+        warnIfNew(`Skipping agent file ${path}: ${reason}`);
+        return undefined;
+    }
+}
+/**
+ * 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, agents) {
+    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`);
+}
+let warnedLastLoad = new Set();
+let warnedThisLoad = new Set();
+/**
+ * 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) {
+    warnedThisLoad.add(message);
+    if (warnedLastLoad.has(message))
+        return;
+    console.warn(`[pi-subagents] ${message}`);
+}
 // ---- Field parsers ----
 // All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
 /** Extract a string or undefined. */
@@ -99,6 +215,23 @@ function parseCsvField(val) {
     const items = s.split(",").map(t => t.trim()).filter(Boolean);
     return items.length > 0 ? items : undefined;
 }
+/**
+ * Parse the nested-delegation allowlist. Single field, default-off:
+ * omitted/empty/"none"/`false` → undefined (no nested tools); "all"/"*"/`true`
+ * → "all" (any enabled agent); csv → only the listed types.
+ *
+ * Booleans are accepted because `extensions:`/`skills:` take them and users
+ * generalize: without this, YAML's `true` stringifies into an agent type
+ * literally named "true", so the tools appear and every spawn is refused.
+ */
+function parseAllowedSubagents(val) {
+    if (typeof val === "boolean")
+        return val ? "all" : undefined;
+    const items = parseCsvField(val);
+    if (!items)
+        return undefined;
+    return items.some(i => i === "*" || i.toLowerCase() === "all") ? "all" : items;
+}
 /**
  * Parse a comma-separated list field with defaults.
  * omitted → defaults; "none"/empty → []; csv → listed items.
@@ -142,6 +275,25 @@ function parseMemory(val) {
         return val;
     return undefined;
 }
+/**
+ * Parse the `isolation` frontmatter field.
+ *
+ * `off` is kept as a value rather than folded into `undefined` because the two
+ * do not mean the same thing here: agent config outranks tool-call params, so
+ * `off` vetoes a caller's `worktree` while an absent field lets it through.
+ *
+ * pi's frontmatter parser is not YAML 1.1 — bare `off` and `no` arrive as
+ * strings and only `false` becomes a boolean — so all three spellings are
+ * accepted rather than leaving an author's intent silently dropped. Anything
+ * else stays `undefined`, as before.
+ */
+function parseIsolation(val) {
+    if (val === "worktree")
+        return "worktree";
+    if (val === "off" || val === "none" || val === "no" || val === false)
+        return "off";
+    return undefined;
+}
 /**
  * Parse an inherit field (extensions, skills).
  * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.

package/dist/custom-agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"custom-agents.js","sourceRoot":"","sources":["../src/custom-agents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"custom-agents.js","sourceRoot":"","sources":["../src/custom-agents.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -11,7 +11,41 @@
  */
 import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Container } from "@earendil-works/pi-tui";
+import { type AgentConfig } from "./types.js";
 import { type Theme } from "./ui/agent-widget.js";
+import { FOREIGN_WORKFLOW_TOOL_NAMES } from "./workflow/collisions.js";
+import { WORKFLOW_ENTRY_TYPE, type WorkflowEntryData, workflowEntryData } from "./workflow/entry.js";
 export declare function renderRunningAgentStatus(frame: string, statsText: string, activity: string, theme: Pick<Theme, "fg">): Container;
+/**
+ * Format an agent's tool scope for the Agent tool description.
+ *
+ * This suffix describes BUILT-IN scope only — extension tools are resolved when
+ * the agent runs (extensions can register asynchronously), so they cannot be
+ * enumerated while the description is being built. That is why an agent with
+ * `tools: "*, ext:mcp/search"` renders "*" and always has.
+ *
+ * Two distinctions matter, both of them capability claims the orchestrator acts on:
+ *
+ * - absent vs empty. `builtinToolNames: undefined` means the agent never narrowed
+ *   its tools (the shipped defaults); `[]` is what `tools: none` and an `ext:`-only
+ *   `tools:` parse to, and the runtime really does hand those agents no built-ins.
+ *   Rendering both "*" tells the orchestrator a tool-less agent can run `bash`.
+ * - empty-with-extensions vs empty-without. Zero built-ins does NOT imply zero
+ *   tools: `tools: none` alongside `extensions:` still surfaces every extension
+ *   tool (see test/fixtures/.pi/agents/tools-none.md, which expects three). Calling
+ *   that "none" understates the agent instead of overstating it — better, but still
+ *   wrong, and it would route work away from the only agent able to do it. "none"
+ *   is therefore reserved for agents that genuinely can call nothing: `isolated`
+ *   agents and those with `extensions: false`.
+ */
+export declare function formatToolsSuffix(cfg: AgentConfig | undefined): string;
+/** CLI flag that runs a workflow script at session start. */
+export declare const WORKFLOW_FILE_FLAG = "subagents-workflow-file";
+/**
+ * Re-exported from where they now live, because this is where they were
+ * defined and a consumer (or a test) that matched a session entry on
+ * {@link WORKFLOW_ENTRY_TYPE} imports it from here.
+ */
+export { FOREIGN_WORKFLOW_TOOL_NAMES, WORKFLOW_ENTRY_TYPE, type WorkflowEntryData, workflowEntryData };
 export default function (pi: ExtensionAPI): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAc,KAAK,YAAY,EAA8G,MAAM,iCAAiC,CAAC;AAC5L,OAAO,EAAE,SAAS,EAA6E,MAAM,wBAAwB,CAAC;AAmB9H,OAAO,EAcL,KAAK,KAAK,EAEX,MAAM,sBAAsB,CAAC;AA4C9B,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GACvB,SAAS,CAKX;AAkKD,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAuvExC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAc,KAAK,YAAY,EAA0F,MAAM,iCAAiC,CAAC;AACxK,OAAO,EAAE,SAAS,EAAiE,MAAM,wBAAwB,CAAC;AAyBlH,OAAO,EAAE,KAAK,WAAW,EAAuK,MAAM,YAAY,CAAC;AAEnN,OAAO,EAeL,KAAK,KAAK,EAEX,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAA2B,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAmBrG,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GACvB,SAAS,CAKX;AAgKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAatE;AAED,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB,4BAA4B,CAAC;AAE5D;;;;GAIG;AACH,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,CAAC;AAEvG,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAkqHxC"}