@herbertgao/pi-subagents 0.15.2 → 0.15.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.15.4
+
+### Patch Changes
+
+- [#45](https://github.com/HerbertGao/pi-extensions/pull/45) [`97bad4e`](https://github.com/HerbertGao/pi-extensions/commit/97bad4e05f7398d9910786e8d614ffd4943cac8c) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Link persisted subagent sessions to their parent Pi session and advance the reviewed upstream baseline to 0.15.1.
+
+- [#52](https://github.com/HerbertGao/pi-extensions/pull/52) [`b12ab55`](https://github.com/HerbertGao/pi-extensions/commit/b12ab5597059ff2020e2108f8e8de85ce64e49c7) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Sync the applicable pi-subagents 0.16.0 fixes and advance the reviewed upstream baseline to bcbd602.
+
+## 0.15.3
+
+### Patch Changes
+
+- [#27](https://github.com/HerbertGao/pi-extensions/pull/27) [`32bb76c`](https://github.com/HerbertGao/pi-extensions/commit/32bb76c117971de27db9c2b521d19df3ba9ea322) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Keep worktree-isolated agents inside their copy, preserve real Agent tool startup errors, and render unknown or failed Agent results without misleading completion status.
+
 ## 0.15.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "Claude Code-style autonomous subagents for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
@@ -40,13 +40,17 @@
   "scripts": {
     "lint": "biome check src/ test/",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "croner": "^10.0.1",
     "nanoid": "^5.0.0"
   },
+  "devDependencies": {
+    "@vitest/coverage-istanbul": "^4.1.10"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.80.0",
     "@earendil-works/pi-coding-agent": ">=0.80.0",
@@ -64,8 +68,8 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.15.0",
+    "version": "0.16.0",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "140324c"
+    "commit": "bcbd602"
   }
 }

package/src/agent-color.ts

@@ -1,22 +1,25 @@
 /**
- * agent-color.ts — Claude Code-compatible agent name color rendering.
+ * agent-color.ts — Claude Code-compatible agent name badges.
  *
- * Claude Code defines eight named subagent colors. Agency Agents also uses
- * six-digit hex values and a small set of additional palette names, which are
- * accepted here so those definitions render without conversion.
+ * Claude Code renders a subagent's name as a badge: the configured color is the
+ * background, the text an inverse foreground. Its eight named colors are
+ * reproduced here, along with six-digit hex and the extra palette names Agency
+ * Agents uses, so those definitions render as written.
  */
 
 import { getConfig } from "./agent-types.js"
 
 const NAMED_AGENT_COLORS: Readonly<Record<string, string>> = {
-  red: "#E74C3C",
-  blue: "#3498DB",
-  green: "#2ECC71",
-  yellow: "#EAB308",
-  purple: "#9B59B6",
-  orange: "#F39C12",
-  pink: "#E84393",
-  cyan: "#00FFFF",
+  // Claude Code's eight subagent colors, as its default theme renders them.
+  red: "#DC2626",
+  blue: "#6A9BCC",
+  green: "#16A34A",
+  yellow: "#CA8A04",
+  purple: "#827DBD",
+  orange: "#D97757",
+  pink: "#C46686",
+  cyan: "#0891B2",
+  // Agency Agents palette aliases.
   amber: "#F59E0B",
   teal: "#008080",
   indigo: "#6366F1",
@@ -34,8 +37,10 @@ const NAMED_AGENT_COLORS: Readonly<Record<string, string>> = {
   navy: "#1E3A8A",
 }
 
-const CUBE_VALUES = [0, 95, 135, 175, 215, 255] as const
+const CUBE_VALUES = [0, 95, 135, 175, 215, 255]
 const GRAY_VALUES = Array.from({ length: 24 }, (_, i) => 8 + i * 10)
+const BLACK = { r: 0, g: 0, b: 0 }
+const WHITE = { r: 255, g: 255, b: 255 }
 
 type Rgb = { r: number; g: number; b: number }
 type ColorMode = "truecolor" | "256color"
@@ -72,51 +77,48 @@ function parseHex(hex: string): Rgb {
   }
 }
 
-function nearestCubeIndex(value: number): number {
-  let best = 0
-  for (let i = 1; i < CUBE_VALUES.length; i++) {
-    if (Math.abs(value - CUBE_VALUES[i]) < Math.abs(value - CUBE_VALUES[best]))
-      best = i
-  }
-  return best
+/** Index of the entry in `values` closest to `value`. */
+function nearest(values: readonly number[], value: number): number {
+  return values.reduce(
+    (best, v, i) =>
+      Math.abs(value - v) < Math.abs(value - values[best]) ? i : best,
+    0,
+  )
 }
 
+/**
+ * Quantize to the xterm-256 palette the way pi's own theme does, returning both
+ * the index to emit and the color the terminal will actually show — badge
+ * contrast is judged against the latter.
+ */
 function rgbTo256({ r, g, b }: Rgb): { index: number; rgb: Rgb } {
-  const rIndex = nearestCubeIndex(r)
-  const gIndex = nearestCubeIndex(g)
-  const bIndex = nearestCubeIndex(b)
-  const cubeRgb = {
-    r: CUBE_VALUES[rIndex],
-    g: CUBE_VALUES[gIndex],
-    b: CUBE_VALUES[bIndex],
-  }
-  const distance = (candidate: Rgb) => {
-    const dr = r - candidate.r
-    const dg = g - candidate.g
-    const db = b - candidate.b
-    return dr * dr * 0.299 + dg * dg * 0.587 + db * db * 0.114
-  }
-
-  const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b)
-  let grayIndex = 0
-  for (let i = 1; i < GRAY_VALUES.length; i++) {
-    if (
-      Math.abs(gray - GRAY_VALUES[i]) < Math.abs(gray - GRAY_VALUES[grayIndex])
-    )
-      grayIndex = i
-  }
-  const grayRgb = {
+  const [rIndex, gIndex, bIndex] = [r, g, b].map((channel) =>
+    nearest(CUBE_VALUES, channel),
+  )
+  const distance = ({ r: cr, g: cg, b: cb }: Rgb) =>
+    0.299 * (r - cr) ** 2 + 0.587 * (g - cg) ** 2 + 0.114 * (b - cb) ** 2
+  const grayIndex = nearest(
+    GRAY_VALUES,
+    Math.round(0.299 * r + 0.587 * g + 0.114 * b),
+  )
+  const gray = {
     r: GRAY_VALUES[grayIndex],
     g: GRAY_VALUES[grayIndex],
     b: GRAY_VALUES[grayIndex],
   }
+  const cube = {
+    r: CUBE_VALUES[rIndex],
+    g: CUBE_VALUES[gIndex],
+    b: CUBE_VALUES[bIndex],
+  }
+  // Only near-neutral colors may take the gray ramp; anything else keeps its tint.
   if (
     Math.max(r, g, b) - Math.min(r, g, b) < 10 &&
-    distance(grayRgb) < distance(cubeRgb)
+    distance(gray) < distance(cube)
   ) {
-    return { index: 232 + grayIndex, rgb: grayRgb }
+    return { index: 232 + grayIndex, rgb: gray }
   }
-  return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cubeRgb }
+  return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cube }
 }
 
 function ansiColor(
@@ -140,9 +142,10 @@ function relativeLuminance({ r, g, b }: Rgb): number {
 }
 
 /**
- * Render one name as a padded background badge when `color` is valid.
- * Black/white foreground is selected by WCAG contrast; invalid or omitted
- * colors preserve the caller's existing theme styling.
+ * Render one name as a padded background badge when `color` is valid. Claude
+ * Code uses one inverse color for every badge's text; black or white is picked
+ * by WCAG contrast here instead, so each palette entry stays readable. Invalid
+ * or omitted colors preserve the caller's existing theme styling.
  */
 export function renderAgentNameLabel(
   name: string,
@@ -156,32 +159,34 @@ export function renderAgentNameLabel(
     return style.fallbackColor ? theme.fg(style.fallbackColor, text) : text
   }
 
-  const backgroundRgb = parseHex(resolved)
-  const mode = theme.getColorMode?.() ?? "truecolor"
-  let background: Rgb | number = backgroundRgb
-  let effectiveBackground = backgroundRgb
-  if (mode === "256color") {
-    const quantized = rgbTo256(backgroundRgb)
-    background = quantized.index
-    effectiveBackground = quantized.rgb
-  }
-  const foregroundRgb =
-    relativeLuminance(effectiveBackground) > 0.179
-      ? { r: 0, g: 0, b: 0 }
-      : { r: 255, g: 255, b: 255 }
-  const foreground =
-    mode === "256color" ? rgbTo256(foregroundRgb).index : foregroundRgb
+  const rgb = parseHex(resolved)
+  const quantized =
+    (theme.getColorMode?.() ?? "truecolor") === "256color"
+      ? rgbTo256(rgb)
+      : undefined
+  const shown = quantized?.rgb ?? rgb
+  const contrasting = relativeLuminance(shown) > 0.179 ? BLACK : WHITE
   const label = style.bold ? theme.bold(` ${name} `) : ` ${name} `
 
   return (
-    ansiColor("background", background) +
-    ansiColor("foreground", foreground) +
+    ansiColor("background", quantized?.index ?? rgb) +
+    ansiColor(
+      "foreground",
+      quantized ? rgbTo256(contrasting).index : contrasting,
+    ) +
     label +
     "\u001b[39m" +
     (style.restoreBackground ?? "\u001b[49m")
   )
 }
 
+/** Whether an agent renders as a badge — i.e. it has a valid configured color. */
+export function hasAgentBadge(type: string | undefined): boolean {
+  return (
+    type !== undefined && resolveAgentColor(getConfig(type).color) !== undefined
+  )
+}
+
 /** Render a registered agent's display name with its configured color. */
 export function renderAgentName(
   type: string | undefined,

package/src/agent-file-toggle.ts

@@ -0,0 +1,255 @@
+/**
+ * agent-file-toggle.ts — Pure helpers for the `/agents` file-editing operations:
+ * locating an agent's .md file, toggling its `enabled:` frontmatter flag, and
+ * serializing an AgentConfig back to frontmatter for eject.
+ *
+ * These live outside src/index.ts so they can be tested directly: the `/agents`
+ * command handler is an ~890-line closure reached only through `registerCommand`,
+ * which every test mocks.
+ *
+ * The read side of this data (src/custom-agents.ts) parses frontmatter with a
+ * real YAML parser, so it honors `enabled: false` at any position in the block.
+ * This module must agree with it, and splits the work accordingly:
+ *
+ * - Deciding whether a file is disabled is a *read*, so it calls that same parser
+ *   (`isDisabledContent`) instead of mirroring it. A mirror has to be right about
+ *   YAML's boolean spellings and about pi's fence scan, and a regex was wrong
+ *   about both.
+ * - *Editing* cannot go through the parser, because re-serializing a parsed
+ *   document would reformat a file the README tells users to hand-author —
+ *   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.
+ */
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent"
+import type { AgentConfig } from "./types.js"
+
+export type AgentFileLocation = "project" | "workspace" | "personal"
+
+export const projectAgentsDir = (cwd: string = process.cwd()) =>
+  join(cwd, ".pi", "agents")
+export const workspaceAgentsDir = (cwd: string = process.cwd()) =>
+  join(cwd, ".agents", "agents")
+export const personalAgentsDir = () => join(getAgentDir(), "agents")
+
+/**
+ * Find the file path of a custom agent by name, in discovery-precedence order
+ * (project, workspace, then global). Mirrors the load-side precedence in
+ * src/custom-agents.ts — if the two drift, `/agents` edits a file the loader
+ * isn't reading.
+ */
+export function findAgentFile(
+  name: string,
+  cwd: string = process.cwd(),
+): { path: string; location: AgentFileLocation } | undefined {
+  const projectPath = join(projectAgentsDir(cwd), `${name}.md`)
+  if (existsSync(projectPath)) return { path: projectPath, location: "project" }
+  const workspacePath = join(workspaceAgentsDir(cwd), `${name}.md`)
+  if (existsSync(workspacePath))
+    return { path: workspacePath, location: "workspace" }
+  const personalPath = join(personalAgentsDir(), `${name}.md`)
+  if (existsSync(personalPath))
+    return { path: personalPath, location: "personal" }
+  return undefined
+}
+
+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
+/** An opening or closing `---` fence line. */
+const FENCE = /^---[ \t]*$/
+
+/**
+ * Split a file into its frontmatter lines and everything else, agreeing with
+ * what `parseFrontmatter` (the load side) considers a frontmatter block.
+ *
+ * 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 — notably for a BOM-prefixed file, which the parser also reads
+ * as having none, so writing a key into it would change nothing on load.
+ */
+function splitFrontmatter(
+  content: string,
+):
+  | { lines: string[]; openIdx: number; closeIdx: number; eol: string }
+  | undefined {
+  const lines = content.split(/(?<=\n)/)
+  if (lines.length === 0 || !FENCE.test(lines[0].replace(/\r?\n$/, "")))
+    return undefined
+  const closeIdx = lines.findIndex(
+    (l, i) => i > 0 && FENCE.test(l.replace(/\r?\n$/, "")),
+  )
+  if (closeIdx === -1) return undefined
+  return {
+    lines,
+    openIdx: 0,
+    closeIdx,
+    eol: lines[0].endsWith("\r\n") ? "\r\n" : "\n",
+  }
+}
+
+/**
+ * Does the loader consider this file disabled?
+ *
+ * Detection is a READ operation, so it asks the same parser the loader uses
+ * rather than mirroring it with a regex — that mirror has to be right about
+ * YAML's boolean spellings (`False`, `FALSE`, a trailing `# comment`, a quoted
+ * key) *and* about pi's fence scan, which closes the block on any line starting
+ * `---` and so ends it early on `----`. A throw means the file is already
+ * unparseable, which is what the loader sees too: it skips the agent, so there
+ * is no "disabled" state to report.
+ */
+export function isDisabledContent(content: string): boolean {
+  try {
+    return (
+      parseFrontmatter<Record<string, unknown>>(content).frontmatter.enabled ===
+      false
+    )
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Add `enabled: false` to a file's frontmatter.
+ *
+ * `outcome` distinguishes a real edit from a no-op so the caller can report
+ * honestly instead of unconditionally claiming success.
+ */
+export function disableInContent(content: string): {
+  content: string
+  outcome: DisableOutcome
+} {
+  const block = splitFrontmatter(content)
+  if (!block) return { content, outcome: "no-frontmatter" }
+  if (isDisabledContent(content))
+    return { content, outcome: "already-disabled" }
+  const lines = [...block.lines]
+  lines.splice(1, 0, `enabled: false${block.eol}`)
+  return { content: lines.join(""), outcome: "disabled" }
+}
+
+/**
+ * Remove `enabled: false` from a file's frontmatter, wherever it appears in the
+ * block — the loader honors the key at any position, so the two must agree or a
+ * hand-authored agent can be disabled and never re-enabled.
+ *
+ * `changed` is false when the key wasn't found, so the caller can avoid
+ * reporting "Enabled <name>" for a write that did nothing.
+ */
+export function enableInContent(content: string): {
+  content: string
+  changed: boolean
+} {
+  const block = splitFrontmatter(content)
+  if (!block) return { content, changed: false }
+  const kept = block.lines.filter(
+    (l, i) =>
+      !(
+        i > 0 &&
+        i < block.closeIdx &&
+        ENABLED_FALSE.test(l.replace(/\r?\n$/, ""))
+      ),
+  )
+  if (kept.length === block.lines.length) return { content, changed: false }
+  return { content: kept.join(""), changed: true }
+}
+
+/** Is this the empty stub `/agents` writes when disabling a built-in default? */
+export function isEmptyStub(content: string): boolean {
+  return content.replace(/\r\n/g, "\n").trim() === "---\n---"
+}
+
+/** The answers `/agents → Create agent → Manual` collects, before serialization. */
+export interface NewAgentInput {
+  description: string
+  /** Already-resolved `tools:` value ("none", "all", or a CSV of tool names). */
+  tools: string
+  /** `provider/modelId`, or undefined to inherit the parent's model. */
+  model?: string
+  /** A pi thinking level, or undefined to inherit. */
+  thinking?: string
+  systemPrompt: string
+}
+
+/**
+ * Build the .md file the create wizard writes.
+ *
+ * `description` and `model` come straight from a free-text prompt, so they are
+ * quoted rather than interpolated — `serializeAgentFile` above quotes the
+ * description for the same reason. An unquoted YAML scalar mishandles ordinary
+ * input in two ways, and both are silent: a colon ("Scout: find things") makes
+ * the file unparseable, and since #212 an unparseable agent file is *skipped*,
+ * so the wizard reports success for an agent that does not exist; a `#`
+ * ("audit #security") opens a comment and truncates the value. `model` can
+ * carry a colon too — pi accepts a `provider/model:thinking` suffix.
+ *
+ * `tools` and `thinking` are not quoted: both are chosen from fixed menus, and
+ * `tools` is a CSV that must stay a bare scalar for the loader's parser.
+ */
+export function buildNewAgentFile(input: NewAgentInput): string {
+  const modelLine = input.model ? `\nmodel: ${JSON.stringify(input.model)}` : ""
+  const thinkingLine = input.thinking ? `\nthinking: ${input.thinking}` : ""
+  return `---
+description: ${JSON.stringify(input.description)}
+tools: ${input.tools}${modelLine}${thinkingLine}
+prompt_mode: replace
+---
+
+${input.systemPrompt}
+`
+}
+
+/** Render a built-in tool list as a `tools:` frontmatter value. */
+function formatToolsField(tools: string[] | undefined): string {
+  if (tools === undefined) return "all"
+  if (tools.length === 0) return "none"
+  return tools.join(", ")
+}
+
+/** Serialize an AgentConfig to a full .md file (frontmatter + system prompt) for eject. */
+export function serializeAgentFile(cfg: AgentConfig): string {
+  const fmFields: string[] = []
+  fmFields.push(`description: ${JSON.stringify(cfg.description)}`)
+  if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`)
+  if (cfg.color) fmFields.push(`color: ${JSON.stringify(cfg.color)}`)
+  // Absent means "all built-ins"; an EMPTY list means explicitly zero. Writing
+  // `all` for both would hand a deliberately tool-less agent the whole toolbox
+  // the first time it is ejected.
+  fmFields.push(`tools: ${formatToolsField(cfg.builtinToolNames)}`)
+  if (cfg.model) fmFields.push(`model: ${cfg.model}`)
+  if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`)
+  if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`)
+  if (cfg.allowedSubagents !== undefined) {
+    fmFields.push(
+      `allowed_subagents: ${cfg.allowedSubagents === "all" ? "all" : cfg.allowedSubagents.join(", ")}`,
+    )
+  }
+  fmFields.push(`prompt_mode: ${cfg.promptMode}`)
+  if (cfg.extensions === false) fmFields.push("extensions: false")
+  else if (Array.isArray(cfg.extensions))
+    fmFields.push(`extensions: ${cfg.extensions.join(", ")}`)
+  if (cfg.excludeExtensions?.length)
+    fmFields.push(`exclude_extensions: ${cfg.excludeExtensions.join(", ")}`)
+  if (cfg.skills === false) fmFields.push("skills: false")
+  else if (Array.isArray(cfg.skills))
+    fmFields.push(`skills: ${cfg.skills.join(", ")}`)
+  if (cfg.disallowedTools?.length)
+    fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`)
+  if (cfg.inheritContext) fmFields.push("inherit_context: true")
+  if (cfg.runInBackground) fmFields.push("run_in_background: true")
+  if (cfg.outputTranscript === false) fmFields.push("output_transcript: false")
+  if (cfg.isolated) fmFields.push("isolated: true")
+  if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`)
+  if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`)
+
+  return `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`
+}