@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/@herbertgao/pi-subagents/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`
+}

package/node_modules/@herbertgao/pi-subagents/src/agent-manager.ts

@@ -144,6 +144,38 @@ interface SpawnOptions {
   rootSessionId?: string
 }
 
+interface ResumeOptions {
+  /**
+   * Run the resumed turn detached in the background: return immediately with
+   * the record still "running" (or "queued" at the concurrency limit) and
+   * notify on completion via onComplete, exactly like a background spawn.
+   * Default (false/undefined) runs the resume inline and returns the settled
+   * record — the historical behavior.
+   */
+  isBackground?: boolean
+  /** Called on tool start/end with activity info (for streaming progress to UI). */
+  onToolActivity?: (activity: ToolActivity) => void
+  /** Called at the end of each resumed agentic turn with the cumulative count. */
+  onTurnEnd?: (turnCount: number) => void
+  /** Called once per assistant message_end with that message's usage delta. */
+  onAssistantUsage?: (usage: {
+    input: number
+    output: number
+    cacheWrite: number
+  }) => void
+  /** Called when the session successfully compacts. */
+  onCompaction?: (info: CompactionInfo) => void
+  /**
+   * Background resume only: called synchronously when the run actually starts —
+   * immediately, or later from drainQueue. Callers wire per-run side effects
+   * (output-file streaming) here rather than at the call site, so a resume that
+   * is stopped while still queued never leaves a subscription behind: `abort()`
+   * drops a queued record without reaching `settle()`, which is what would have
+   * torn that subscription down.
+   */
+  onStarted?: () => void
+}
+
 export class AgentManager {
   private agents = new Map<string, AgentRecord>()
   private cleanupInterval: ReturnType<typeof setInterval>
@@ -156,7 +188,7 @@ export class AgentManager {
   private worktreeRepos = new Set<string>()
 
   /** Queue of background agents waiting to start. */
-  private queue: { id: string; args: SpawnArgs }[] = []
+  private queue: { id: string; start: () => void }[] = []
   /** Number of currently running background agents. */
   private runningBackground = 0
 
@@ -236,7 +268,7 @@ export class AgentManager {
       this.runningBackground >= this.maxConcurrent
     ) {
       // Queue it — will be started when a running agent completes
-      this.queue.push({ id, args })
+      this.queue.push({ id, start: () => this.startAgent(id, record, args) })
       return id
     }
 
@@ -508,7 +540,7 @@ export class AgentManager {
       const record = this.agents.get(next.id)
       if (record?.status !== "queued") continue
       try {
-        this.startAgent(next.id, record, next.args)
+        next.start()
       } catch (err) {
         // Late failure (e.g. strict worktree-isolation) — surface on the record
         // so the user/agent can see it via /agents, then keep draining.
@@ -570,10 +602,51 @@ export class AgentManager {
     id: string,
     prompt: string,
     signal?: AbortSignal,
+    options?: ResumeOptions,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id)
     if (!record?.session) return undefined
 
+    // Background resume: settle asynchronously and notify on completion exactly
+    // like a background spawn, returning immediately with the record still
+    // "running" — or "queued" when at the concurrency limit. Previously
+    // run_in_background was ignored on resume (the Agent tool's resume branch
+    // returned before its background branch, and resume() only ever awaited
+    // inline), so a resumed agent always blocked the caller until it finished.
+    if (options?.isBackground) {
+      // Never re-enter a run that is still in flight. Detaching means the caller
+      // gets control back while the record stays "running", so nothing stops the
+      // model from resuming the same agent again. Starting a second run would
+      // overwrite record.abortController — orphaning the live run beyond the
+      // reach of `/agents` stop and abortAll() — double-count the pool slot, and
+      // then reject from session.prompt() with "Agent is already processing",
+      // whose settle path would abort the LIVE run's children and report a
+      // failure for a run that is still going. Refuse instead, leaving the
+      // record untouched; the caller decides whether to wait or steer.
+      if (record.status === "running" || record.status === "queued")
+        return undefined
+
+      record.isBackground = true
+      record.resultConsumed = false
+      record.result = undefined
+      record.error = undefined
+      record.completedAt = undefined
+      record.status = "queued"
+
+      const start = () => this.startResume(id, record, prompt, signal, options)
+      if (
+        occupiesPoolSlot(record) &&
+        this.runningBackground >= this.maxConcurrent
+      ) {
+        // At the concurrency limit — queue it, drains when a slot frees.
+        this.queue.push({ id, start })
+      } else {
+        start()
+      }
+      return record
+    }
+
+    // Foreground resume: run inline and return the settled record.
     record.status = "running"
     record.startedAt = Date.now()
     record.completedAt = undefined
@@ -584,13 +657,17 @@ export class AgentManager {
       const { text, failure } = await resumeAgent(record.session, prompt, {
         onToolActivity: (activity) => {
           if (activity.type === "end") record.toolUses++
+          options?.onToolActivity?.(activity)
         },
+        onTurnEnd: options?.onTurnEnd,
         onAssistantUsage: (usage) => {
           addUsage(record.lifetimeUsage, usage)
+          options?.onAssistantUsage?.(usage)
         },
         onCompaction: (info) => {
           record.compactionCount++
           this.onCompact?.(record, info)
+          options?.onCompaction?.(info)
         },
         signal,
       })
@@ -613,6 +690,117 @@ export class AgentManager {
     return record
   }
 
+  /**
+   * Start a background resume run: detached, settling and notifying like
+   * startAgent's background path. Invoked immediately, or from drainQueue when
+   * a concurrency slot frees. The session already exists (resume reuses it), so
+   * there is no onSessionCreated to hang per-run wiring off — callers use
+   * `options.onStarted`, which fires on both the immediate and the drained path.
+   */
+  private startResume(
+    id: string,
+    record: AgentRecord,
+    prompt: string,
+    parentSignal: AbortSignal | undefined,
+    options: ResumeOptions,
+  ) {
+    if (!record.session) return
+
+    record.status = "running"
+    record.startedAt = Date.now()
+    if (occupiesPoolSlot(record)) this.runningBackground++
+    this.onStart?.(record)
+
+    // Fresh abort controller so /agents stop and steering target THIS run rather
+    // than the previous one's settled controller.
+    const abortController = new AbortController()
+    record.abortController = abortController
+    // Optional, and NOT what the Agent tool passes for a detached resume: a
+    // parent signal aborts on the parent's own interrupt (user Esc), which is
+    // right for a foreground run whose result the caller is awaiting, and wrong
+    // for a detached one — background spawns omit it for exactly this reason.
+    let detachParentSignal: (() => void) | undefined
+    if (parentSignal) {
+      const onParentAbort = () => this.abort(id)
+      parentSignal.addEventListener("abort", onParentAbort, { once: true })
+      detachParentSignal = () =>
+        parentSignal.removeEventListener("abort", onParentAbort)
+    }
+
+    // Per-run side effects (output streaming) — see ResumeOptions.onStarted.
+    // After the record is in its running shape, before the run is kicked off.
+    try {
+      options.onStarted?.()
+    } catch {
+      /* ignore caller wiring errors */
+    }
+
+    const settle = () => {
+      detachParentSignal?.()
+      detachParentSignal = undefined
+      // Final flush of streaming output file
+      if (record.outputCleanup) {
+        try {
+          record.outputCleanup()
+        } catch {
+          /* ignore */
+        }
+        record.outputCleanup = undefined
+      }
+      // Children spawned during the resumed turn must not outlive it.
+      this.abortOwnedChildren(id)
+      if (occupiesPoolSlot(record)) this.runningBackground--
+      try {
+        this.onComplete?.(record)
+      } catch {
+        /* ignore completion side-effect errors */
+      }
+      this.drainQueue()
+    }
+
+    const promise = resumeAgent(record.session, prompt, {
+      onToolActivity: (activity) => {
+        if (activity.type === "end") record.toolUses++
+        options.onToolActivity?.(activity)
+      },
+      onTurnEnd: options.onTurnEnd,
+      onAssistantUsage: (usage) => {
+        addUsage(record.lifetimeUsage, usage)
+        options.onAssistantUsage?.(usage)
+      },
+      onCompaction: (info) => {
+        record.compactionCount++
+        this.onCompact?.(record, info)
+        options.onCompaction?.(info)
+      },
+      signal: abortController.signal,
+    })
+      .then(({ text, failure }) => {
+        // Don't overwrite status if externally stopped via abort().
+        if (record.status !== "stopped") {
+          // Same contract as the spawn path (#144): a failed final turn is an
+          // error, not a completion — but the resumed text stays available.
+          record.status = failure ? "error" : "completed"
+          if (failure) record.error = failure
+        }
+        record.result = text
+        record.completedAt ??= Date.now()
+        settle()
+        return text
+      })
+      .catch((err) => {
+        if (record.status !== "stopped") {
+          record.status = "error"
+          record.error = err instanceof Error ? err.message : String(err)
+        }
+        record.completedAt ??= Date.now()
+        settle()
+        return ""
+      })
+
+    record.promise = promise
+  }
+
   /**
    * Send a steering message to an agent from the UI (mirrors the steer_subagent
    * tool). A live session delivers it now — it interrupts the agent after its

package/node_modules/@herbertgao/pi-subagents/src/agent-runner.ts

@@ -365,7 +365,7 @@ export function setGraceTurns(n: number): void {
  * Try to find the right model for an agent type.
  * Priority: explicit option > config.model > parent model.
  */
-function resolveDefaultModel(
+export function resolveDefaultModel(
   parentModel: Model<any> | undefined,
   registry: {
     find(provider: string, modelId: string): Model<any> | undefined
@@ -946,6 +946,9 @@ export async function runAgent(
     ? SessionManager.create(
         effectiveCwd,
         configuredSessionDir ?? defaultSessionDir,
+        {
+          parentSession: ctx.sessionManager.getSessionFile(),
+        },
       )
     : SessionManager.inMemory(effectiveCwd)
 
@@ -1125,6 +1128,8 @@ export async function resumeAgent(
   prompt: string,
   options: {
     onToolActivity?: (activity: ToolActivity) => void
+    /** Called at the end of each resumed agentic turn with the 1-based count. */
+    onTurnEnd?: (turnCount: number) => void
     onAssistantUsage?: (usage: {
       input: number
       output: number
@@ -1143,10 +1148,18 @@ export async function resumeAgent(
   const startLen = session.messages.length
   const collector = collectResponseText(session)
   const cleanupAbort = forwardAbortSignal(session, options.signal)
+  let turnCount = 0
 
   const unsubEvents =
-    options.onToolActivity || options.onAssistantUsage || options.onCompaction
+    options.onToolActivity ||
+    options.onTurnEnd ||
+    options.onAssistantUsage ||
+    options.onCompaction
       ? session.subscribe((event: AgentSessionEvent) => {
+          if (event.type === "turn_end") {
+            turnCount++
+            options.onTurnEnd?.(turnCount)
+          }
           if (event.type === "tool_execution_start")
             options.onToolActivity?.({
               type: "start",