@herbertgao/pi-subagents 0.17.1 → 0.18.0

package/examples/workflows/gated-fix.js

@@ -0,0 +1,60 @@
+/**
+ * gated-fix.js — verify by running a command, not by asking a second opinion.
+ *
+ * Demonstrates: `gate` (a shell command that must pass, or the agent is failed
+ * and its call returns null), and `resume` to hand the failure back to the same
+ * child instead of re-paying for the context it already built.
+ *
+ * Two constraints this example is shaped around, both worth knowing:
+ *
+ *   1. `gate` cannot be combined with `resume`. A resumed child keeps the agent
+ *      type, model, tree and tools it was started with, so the corrective pass
+ *      is NOT itself gated — re-verification needs its own gated call.
+ *   2. `isolation: "worktree"` is deliberately not used here. An isolated child's
+ *      worktree is committed to a branch and removed when it settles, so a later
+ *      agent would verify the main tree and could pass while the fix it was
+ *      checking lives somewhere else. Isolation is for parallel writers that
+ *      would collide; a serial fix-then-verify chain wants one shared tree.
+ *
+ * args: { task?: string, test?: string }
+ *
+ * Run: ask the model — "run the workflow at examples/workflows/gated-fix.js
+ * with the test command npm test". Needs a real test command to be useful.
+ */
+export const meta = {
+  name: "gated-fix",
+  description: "Fix a failing test, then prove it passes by running the suite",
+  phases: [{ title: "Fix" }, { title: "Verify" }],
+}
+
+const task = args?.task ?? "Find and fix the failing test."
+const testCommand = args?.test ?? "npm test"
+
+phase("Fix")
+
+// The gate runs after the agent finishes. A non-zero exit fails the agent and
+// folds the command's output into its error, so `fixed` is null exactly when
+// the suite did not pass — no need to ask a model whether the fix worked.
+let fixed = await agent(task, { label: "fix", gate: testCommand })
+
+if (fixed === null) {
+  log(`${testCommand} failed — handing the output back to the same child`)
+
+  // Resume, not a fresh spawn: the child still has everything it learned on the
+  // first pass, so it is told what broke rather than rediscovering it.
+  fixed = await agent(
+    `\`${testCommand}\` is still failing. Read the failure above, fix the cause, and stop.`,
+    { label: "fix", resume: "fix" },
+  )
+
+  // The resume could not carry the gate, so verify separately. This child works
+  // in the same tree, which is what makes the check meaningful.
+  phase("Verify")
+  const verified = await agent(
+    `Run \`${testCommand}\` and report the result. Change nothing.`,
+    { label: "verify", gate: testCommand, effort: "low" },
+  )
+  return { passed: verified !== null, summary: fixed }
+}
+
+return { passed: true, summary: fixed }

package/examples/workflows/lib/count-child.js

@@ -0,0 +1,30 @@
+/**
+ * lib/count-child.js — a nested workflow, invoked by compose.js.
+ *
+ * A child is an ordinary workflow: it needs its own `export const meta =`
+ * declaration, which is exactly what marks a file in a workflows directory as
+ * runnable rather than as some unrelated script that happens to live there.
+ *
+ * args: { root?: string }
+ */
+export const meta = {
+  name: "count-child",
+  description: "Count the source files under a directory",
+}
+
+const root = args?.root ?? "src/"
+
+const found = await agent(
+  `List every source file under ${root}. One path per line, nothing else.`,
+  {
+    label: "scan",
+    schema: {
+      type: "object",
+      properties: { files: { type: "array", items: { type: "string" } } },
+      required: ["files"],
+    },
+  },
+)
+
+// A schema call can still return null if the child never complied.
+return found === null ? 0 : found.files.length

package/examples/workflows/review-panel.js

@@ -0,0 +1,68 @@
+/**
+ * review-panel.js — the case where a barrier is actually earned.
+ *
+ * Demonstrates: `parallel` used correctly, `effort` tiering (cheap reviewers,
+ * an expensive judge), and a `model` override.
+ *
+ * Most of the time `pipeline` beats `parallel`, because a barrier idles every
+ * fast agent until the slowest finishes. This is the exception: the synthesis
+ * prompt interpolates ALL of the reviews, so it genuinely cannot start until
+ * every one of them is in. That — a prompt that compares results against each
+ * other — is what justifies a barrier.
+ *
+ * args: { target?: string, lenses?: string[] }
+ *
+ * Run: ask the model — "run the workflow at examples/workflows/review-panel.js
+ * against src/auth.ts".
+ */
+export const meta = {
+  name: "review-panel",
+  description:
+    "Review one thing from several angles, then reconcile the verdicts",
+  phases: [{ title: "Review" }, { title: "Synthesize" }],
+}
+
+const target = args?.target ?? "the changed files"
+const lenses = args?.lenses ?? ["correctness", "security", "performance"]
+
+phase("Review")
+
+// Perspective diversity, not redundancy: three reviewers with DIFFERENT briefs
+// catch failure modes that three identical ones cannot.
+const reviews = await parallel(
+  lenses.map(
+    (lens) => () =>
+      agent(
+        `Review ${target} through the lens of ${lens} alone. Be specific and brief.`,
+        {
+          label: `review:${lens}`,
+          // Cheap for the survey work; the judge below gets the depth.
+          effort: "low",
+        },
+      ),
+  ),
+)
+
+// A thunk that throws becomes null without taking its siblings down.
+const usable = reviews
+  .map((text, i) => ({ lens: lenses[i], text }))
+  .filter((r) => r.text !== null)
+
+if (usable.length === 0) {
+  log("every reviewer failed — nothing to synthesize")
+  return { reviewed: 0, verdict: null }
+}
+
+phase("Synthesize")
+
+// This is the barrier's payoff: one prompt that sees all of them at once and can
+// weigh them against each other.
+const verdict = await agent(
+  [
+    `Reconcile these reviews of ${target}. Where they disagree, say which is right and why.`,
+    ...usable.map((r) => `\n## ${r.lens}\n${r.text}`),
+  ].join("\n"),
+  { label: "synthesize", effort: "high", agentType: "Plan" },
+)
+
+return { reviewed: usable.length, verdict }

package/examples/workflows/structured-findings.js

@@ -0,0 +1,81 @@
+/**
+ * structured-findings.js — get objects back, not prose.
+ *
+ * Demonstrates: `schema` on every agent call, so the script manipulates
+ * validated objects instead of parsing text it hopes is well-formed.
+ *
+ * Reach for this whenever the script has to *do* something with the results —
+ * sort, count, filter, compare — rather than hand them straight to you.
+ *
+ * args: { dimensions?: string[] }  — review angles, default bugs + perf
+ *
+ * Run: ask the model — "run the workflow at
+ * examples/workflows/structured-findings.js".
+ */
+export const meta = {
+  name: "structured-findings",
+  description: "Review changed files across dimensions and verify each finding",
+  phases: [{ title: "Review" }, { title: "Verify" }],
+}
+
+const FINDINGS = {
+  type: "object",
+  properties: {
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          file: { type: "string" },
+          severity: { type: "string" },
+        },
+        required: ["title", "file"],
+      },
+    },
+  },
+  required: ["findings"],
+}
+
+const VERDICT = {
+  type: "object",
+  properties: { isReal: { type: "boolean" }, why: { type: "string" } },
+  required: ["isReal"],
+}
+
+const dimensions = args?.dimensions ?? ["bugs", "performance"]
+
+const reviewed = await pipeline(
+  dimensions,
+  (dim) =>
+    agent(`Review the changed files for ${dim}. Report every finding.`, {
+      label: `review:${dim}`,
+      phase: "Review",
+      // With a schema the call resolves to the validated object, so `.findings`
+      // below is a real array rather than something scraped out of prose.
+      schema: FINDINGS,
+    }),
+  // A barrier is earned here only per-dimension: each dimension's findings are
+  // verified concurrently, but dimensions never wait for each other.
+  (review) =>
+    parallel(
+      review.findings.map(
+        (f) => () =>
+          agent(`Try to REFUTE this finding: ${f.title} (${f.file})`, {
+            label: `verify:${f.file}`,
+            phase: "Verify",
+            schema: VERDICT,
+          }).then((verdict) => ({ ...f, verdict })),
+      ),
+    ),
+)
+
+// filter(Boolean) twice: once for a whole dimension that failed, once for an
+// individual verification that did. A schema call can still return null.
+const confirmed = reviewed
+  .filter(Boolean)
+  .flat()
+  .filter(Boolean)
+  .filter((f) => f.verdict?.isReal)
+
+return { confirmed: confirmed.length, findings: confirmed }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.17.1",
-  "description": "Claude Code-style autonomous subagents for Pi, with HerbertGao-maintained UI extensions.",
+  "version": "0.18.0",
+  "description": "Claude Code-style autonomous subagents and workflow orchestration for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
     "autonomous",
@@ -26,7 +26,8 @@
   },
   "files": [
     "src/**/*.ts",
-    "examples/**/*.md",
+    "examples/**/*",
+    "docs/**/*.md",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
@@ -46,15 +47,16 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "croner": "^10.0.1",
-    "nanoid": "^5.1.16"
+    "nanoid": "^5.1.16",
+    "typebox": "^1.3.7"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.1.10"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.81.0",
-    "@earendil-works/pi-coding-agent": ">=0.81.0",
-    "@earendil-works/pi-tui": ">=0.81.0"
+    "@earendil-works/pi-ai": ">=0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
+    "@earendil-works/pi-tui": ">=0.84.0"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -68,9 +70,9 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.18.2",
+    "version": "0.19.0",
     "reviewedVersion": "0.19.0",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "ad81024825b315577692b785831262874e66be95"
+    "commit": "95d10867f391636e6563e3885e972618083f306b"
   }
 }

package/src/agent-file-toggle.ts

@@ -20,14 +20,13 @@
  *   discarding their comments, key order, and quoting. So the edits are line-wise
  *   and preserve everything they don't touch.
  *
- * That leaves removal best-effort: it recognizes the parser's case-insensitive
- * bare `false` spellings and trailing comments, and reports `changed: false`
- * for values it cannot rewrite, so the caller refuses honestly rather than
- * announcing a change it did not make.
+ * That leaves removal best-effort: it recognizes a lowercase bare `false`, and
+ * reports `changed: false` for the spellings it cannot rewrite, so the caller
+ * refuses honestly rather than announcing a change it did not make.
  */
 
 import { existsSync } from "node:fs"
-import { join } from "node:path"
+import { join, sep } from "node:path"
 import { getAgentDir } from "@earendil-works/pi-coding-agent"
 import { parseAgentFrontmatter } from "./custom-agents.js"
 import type { AgentConfig } from "./types.js"
@@ -61,20 +60,60 @@ export function findAgentFile(
   return undefined
 }
 
+/**
+ * Find the file behind a *loaded* agent, preferring the path the loader
+ * actually read (`AgentConfig.sourcePath`) over the `<type>.md` guess.
+ *
+ * An agent's type comes from its frontmatter `name:` now, so the two can
+ * disagree: `reviewer.md` declaring `name: code-reviewer` is loaded as
+ * `code-reviewer`, and probing for `code-reviewer.md` finds nothing. That is
+ * not a harmless miss — `/agents → Disable` would then take the no-file branch
+ * and write a NEW `code-reviewer.md` stub, which loses to `reviewer.md` on
+ * load, leaving the agent enabled while reporting success.
+ *
+ * The probe stays as the fallback: a built-in that was never ejected has no
+ * `sourcePath`, and a path can go stale between a load and this call.
+ */
+export function locateAgentFile(
+  name: string,
+  sourcePath: string | undefined,
+  cwd: string = process.cwd(),
+): { path: string; location: AgentFileLocation } | undefined {
+  if (sourcePath && existsSync(sourcePath)) {
+    return { path: sourcePath, location: classifyAgentDir(sourcePath, cwd) }
+  }
+  return findAgentFile(name, cwd)
+}
+
+/**
+ * Which discovery location a loaded agent's file came from. Only ever names
+ * a directory in a confirmation prompt, so an unrecognized parent — which
+ * loadCustomAgents cannot currently produce — reports as personal rather than
+ * widening the type for a case that has no better answer.
+ */
+function classifyAgentDir(path: string, cwd: string): AgentFileLocation {
+  if (path.startsWith(projectAgentsDir(cwd) + sep)) return "project"
+  if (path.startsWith(workspaceAgentsDir(cwd) + sep)) return "workspace"
+  return "personal"
+}
+
 export type DisableOutcome = "disabled" | "already-disabled" | "no-frontmatter"
 
-/** A line that sets `enabled: false`, accepting YAML case and comments. */
-const ENABLED_FALSE = /^[ \t]*enabled:[ \t]*false[ \t]*(?:#[^\r\n]*)?$/i
+/** A line that sets `enabled: false`, ignoring trailing whitespace / CR. */
+const ENABLED_FALSE = /^enabled:[ \t]*false[ \t]*$/
 /** An opening or closing `---` fence line. */
 const FENCE = /^---[ \t]*$/
 
 /**
  * Split a file into its frontmatter lines and everything else, agreeing with
- * what `parseAgentFrontmatter` (the load side) considers a frontmatter block.
+ * what `parseAgentFrontmatter` (the load side) considers a frontmatter block —
+ * including its BOM normalisation, which is why the fence test looks past one.
+ * The BOM itself stays in `lines[0]`: it belongs to the file's encoding, not to
+ * the block, and an edit must not strip it from the user's file.
  *
  * Lines keep their terminators, so an edit preserves the file's existing line
  * endings instead of rewriting CRLF to LF. Returns undefined when there is no
- * usable block. A leading BOM stays byte-for-byte in the file.
+ * usable block.
  */
 function splitFrontmatter(
   content: string,
@@ -83,9 +122,10 @@ function splitFrontmatter(
   | undefined {
   const lines = content.split(/(?<=\n)/)
   if (lines.length === 0) return undefined
-  const first = (
-    content.startsWith("\uFEFF") ? lines[0].slice(1) : lines[0]
-  ).replace(/\r?\n$/, "")
+  // The BOM stays where it is — it belongs to the file, not the block — so the
+  // fence test looks past it and every index below is unaffected.
+  const bom = content.startsWith("\uFEFF")
+  const first = (bom ? lines[0].slice(1) : lines[0]).replace(/\r?\n$/, "")
   if (!FENCE.test(first)) return undefined
   const closeIdx = lines.findIndex(
     (l, i) => i > 0 && FENCE.test(l.replace(/\r?\n$/, "")),