@esso0428/pi-subagents 0.17.6 → 0.17.7

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

@@ -0,0 +1,27 @@
+/**
+ * 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,63 @@
+/**
+ * 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,78 @@
+/**
+ * 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,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.6",
+  "version": "0.17.7",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/abortable.ts

@@ -0,0 +1,43 @@
+/**
+ * abortable.ts — race a promise against an AbortSignal without cancelling the
+ * underlying work.
+ *
+ * Used by the `get_subagent_result` wait paths (top-level and nested): pressing
+ * Esc cancels only the caller's wait; the background child keeps running and its
+ * result stays unconsumed. The listener is removed on every settle path so the
+ * signal accumulates no handlers, and a late settlement of the wrapped promise
+ * after an abort is absorbed as a no-op (no unhandled rejection).
+ */
+
+/** Await a promise until it settles or the caller cancels, without aborting the underlying work. */
+export function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(signal.reason);
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}

package/src/agent-color.ts

@@ -0,0 +1,161 @@
+/**
+ * agent-color.ts — Claude Code-compatible agent name badges.
+ *
+ * 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>> = {
+  // 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",
+  gold: "#EAB308",
+  "neon-green": "#10B981",
+  "neon-cyan": "#06B6D4",
+  "metallic-blue": "#3B82F6",
+  violet: "#8B5CF6",
+  rose: "#F43F5E",
+  lime: "#84CC16",
+  gray: "#6B7280",
+  grey: "#6B7280",
+  fuchsia: "#D946EF",
+  slate: "#64748B",
+  navy: "#1E3A8A",
+};
+
+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";
+
+export interface AgentNameTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+  getColorMode?(): ColorMode;
+}
+
+export interface AgentNameStyle {
+  /** Existing theme foreground used when no valid agent color is configured. */
+  fallbackColor?: string;
+  /** Reapply an enclosing background after the badge instead of resetting it. */
+  restoreBackground?: string;
+  bold?: boolean;
+}
+
+/** Resolve Claude Code/Agency Agents color syntax to normalized #RRGGBB. */
+export function resolveAgentColor(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  const resolved = NAMED_AGENT_COLORS[normalized] ?? normalized;
+  return /^#[0-9a-f]{6}$/i.test(resolved) ? resolved.toUpperCase() : undefined;
+}
+
+function parseHex(hex: string): Rgb {
+  return {
+    r: Number.parseInt(hex.slice(1, 3), 16),
+    g: Number.parseInt(hex.slice(3, 5), 16),
+    b: Number.parseInt(hex.slice(5, 7), 16),
+  };
+}
+
+/** 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, 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(gray) < distance(cube)) {
+    return { index: 232 + grayIndex, rgb: gray };
+  }
+  return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cube };
+}
+
+function ansiColor(layer: "foreground" | "background", color: Rgb | number): string {
+  const code = layer === "foreground" ? 38 : 48;
+  return typeof color === "number"
+    ? `\u001b[${code};5;${color}m`
+    : `\u001b[${code};2;${color.r};${color.g};${color.b}m`;
+}
+
+function relativeLuminance({ r, g, b }: Rgb): number {
+  const linear = (value: number) => {
+    const channel = value / 255;
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/**
+ * 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,
+  color: string | undefined,
+  theme: AgentNameTheme,
+  style: AgentNameStyle = {},
+): string {
+  const resolved = resolveAgentColor(color);
+  if (!resolved) {
+    const text = style.bold ? theme.bold(name) : name;
+    return style.fallbackColor ? theme.fg(style.fallbackColor, text) : text;
+  }
+
+  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", 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,
+  theme: AgentNameTheme,
+  style: AgentNameStyle = {},
+): string {
+  if (!type) return renderAgentNameLabel("Agent", undefined, theme, style);
+  const config = getConfig(type);
+  return renderAgentNameLabel(config.displayName, config.color, theme, style);
+}

package/src/agent-file-toggle.ts

@@ -0,0 +1,269 @@
+/**
+ * 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 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, sep } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parseAgentFrontmatter } from "./custom-agents.js";
+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;
+}
+
+/**
+ * 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`, 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 —
+ * 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.
+ */
+function splitFrontmatter(content: string):
+  | { lines: string[]; openIdx: number; closeIdx: number; eol: string }
+  | undefined {
+  const lines = content.split(/(?<=\n)/);
+  if (lines.length === 0) return undefined;
+  // 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$/, "")));
+  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 parseAgentFrontmatter<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");
+  // Both cases, not just `true`: with `backgroundByDefault` on, omitting the
+  // field means background, so `false` is the only way to pin an agent file to
+  // foreground and is no longer interchangeable with absence. No caller can
+  // reach it yet — Eject only handles built-in defaults, which omit the field —
+  // so this keeps the writer symmetric with the loader, nothing more.
+  if (cfg.runInBackground !== undefined) fmFields.push(`run_in_background: ${cfg.runInBackground}`);
+  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`;
+}