@herbertgao/pi-subagents 0.18.5 → 0.22.0-local.1

package/src/agent-file-toggle.ts

@@ -61,7 +61,7 @@ export function findAgentFile(
 }
 
 /**
- * Find the file behind a *loaded* agent, preferring the path the loader
+ * Find the *editable* 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
@@ -73,13 +73,22 @@ export function findAgentFile(
  *
  * 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.
+ *
+ * **A package agent has no editable file.** Its `sourcePath` points inside pi's
+ * install root, where an edit is lost on the next `pi update` and a delete is
+ * undone by the next `pi install`. Passing `source` lets that rule live here
+ * rather than at each `/agents` call site: the package path is ignored, and the
+ * name probe runs instead — which finds the local stub shadowing it, if one
+ * exists, and otherwise nothing. Callers then take their no-file branch, which
+ * is the Eject-or-shadow behaviour a not-yet-ejected builtin already gets.
  */
 export function locateAgentFile(
   name: string,
   sourcePath: string | undefined,
   cwd: string = process.cwd(),
+  source?: AgentConfig["source"],
 ): { path: string; location: AgentFileLocation } | undefined {
-  if (sourcePath && existsSync(sourcePath)) {
+  if (source !== "package" && sourcePath && existsSync(sourcePath)) {
     return { path: sourcePath, location: classifyAgentDir(sourcePath, cwd) }
   }
   return findAgentFile(name, cwd)
@@ -87,9 +96,11 @@ export function locateAgentFile(
 
 /**
  * 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.
+ * a directory in a confirmation prompt, so an unrecognized parent reports as
+ * personal rather than widening the type for a case that has no better answer.
+ *
+ * Package-provided paths never reach here: `locateAgentFile` drops them above,
+ * because none of the three locations this classifies is where they live.
  */
 function classifyAgentDir(path: string, cwd: string): AgentFileLocation {
   if (path.startsWith(projectAgentsDir(cwd) + sep)) return "project"
@@ -251,11 +262,29 @@ ${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(", ")
+/**
+ * Rebuild the `tools:` CSV from the two halves the loader split it into.
+ *
+ * `extSelectors` has to come back with the built-ins: `parseToolsField` splits
+ * `tools: read, ext:mcp/github` into `["read"]` and `["ext:mcp/github"]`, so
+ * writing only the first half hands the ejected copy a *narrower* toolset than
+ * the file it came from. That was invisible while Eject only ever ran on
+ * built-in defaults, which carry no selectors; a package agent can.
+ *
+ * Zero built-ins with selectors present is not `none` — `none` means no tools at
+ * all, while `ext:` entries alone mean "extension tools only", which the loader
+ * reads back from a `tools:` line carrying just those entries.
+ */
+function formatToolsField(
+  tools: string[] | undefined,
+  extSelectors?: string[],
+): string {
+  const selectors = extSelectors ?? []
+  if (tools === undefined)
+    return selectors.length > 0 ? ["*", ...selectors].join(", ") : "all"
+  if (tools.length === 0)
+    return selectors.length > 0 ? selectors.join(", ") : "none"
+  return [...tools, ...selectors].join(", ")
 }
 
 /** Serialize an AgentConfig to a full .md file (frontmatter + system prompt) for eject. */
@@ -267,7 +296,9 @@ export function serializeAgentFile(cfg: AgentConfig): string {
   // 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)}`)
+  fmFields.push(
+    `tools: ${formatToolsField(cfg.builtinToolNames, cfg.extSelectors)}`,
+  )
   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}`)
@@ -290,15 +321,21 @@ export function serializeAgentFile(cfg: AgentConfig): string {
   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.
+  // foreground and is no longer interchangeable with absence. Reachable since
+  // package agents became ejectable — a built-in default omits the field.
   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}`)
+  // Also only reachable through a package agent: no built-in default sets
+  // either. Omitting them would have the ejected copy silently stop persisting
+  // its session, or write it somewhere else.
+  if (cfg.persistSession !== undefined)
+    fmFields.push(`persist_session: ${cfg.persistSession}`)
+  if (cfg.sessionDir)
+    fmFields.push(`session_dir: ${JSON.stringify(cfg.sessionDir)}`)
 
   return `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`
 }

package/src/agent-manager.ts

@@ -24,6 +24,7 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent"
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js"
+import { getAgentConfig } from "./agent-types.js"
 import { assignHandle, handleBase } from "./mention.js"
 import { describeModel } from "./model-resolver.js"
 import type {
@@ -32,6 +33,7 @@ import type {
   AgentTombstone,
   IsolationMode,
   MentionResolution,
+  Pool,
   SubagentType,
   ThinkingLevel,
 } from "./types.js"
@@ -191,9 +193,6 @@ function occupiesForegroundSlot(
   return !!record.blocking && isTopLevelAgent(record)
 }
 
-/** Which concurrency pool a spawn is charged to, if any. */
-type Pool = "background" | "foreground"
-
 interface SpawnArgs {
   pi: ExtensionAPI
   ctx: ExtensionContext
@@ -658,10 +657,9 @@ export class AgentManager {
    * an aborted signal, so a `spawnAndWait` on it would wait forever — pi has no
    * tool-execution timeout to bail it out.
    *
-   * The listener is left in place when the agent starts. `startAgent` adds its
-   * own, so both fire on a later abort, but `abort()` on an already-stopped
-   * record is a no-op — so detaching would only be tidiness, and tidiness the
-   * `abortAll`/`dispose` paths could not offer anyway.
+   * The listener is removable (`record.detachParentAbort`): `startAgent`
+   * replaces it with its own, and `sendToBackground` must be able to take it
+   * off, or the caller that armed it could stop a run it no longer owns.
    */
   private armQueuedAbort(id: string, signal?: AbortSignal): boolean {
     if (signal === undefined) return true
@@ -673,10 +671,39 @@ export class AgentManager {
       }
       return false
     }
-    signal.addEventListener("abort", () => this.abort(id), { once: true })
+    const record = this.agents.get(id)
+    if (record) this.armParentAbort(record, signal)
     return true
   }
 
+  /**
+   * Stop `record` when its caller's `signal` aborts, replacing any listener an
+   * earlier stage armed — at most one is live per record, so one call to
+   * `detachParentAbort` cuts the run loose from its caller.
+   */
+  private armParentAbort(
+    record: AgentRecord,
+    signal: AbortSignal | undefined,
+  ): void {
+    this.detachParentAbort(record)
+    if (signal === undefined) return
+    const onParentAbort = () => this.abort(record.id)
+    signal.addEventListener("abort", onParentAbort, { once: true })
+    record.detachParentAbort = () =>
+      signal.removeEventListener("abort", onParentAbort)
+  }
+
+  private detachParentAbort(record: AgentRecord): void {
+    record.detachParentAbort?.()
+    record.detachParentAbort = undefined
+  }
+
+  /** Add `delta` to the running count of `pool`; no pool, no count. */
+  private chargePool(pool: Pool | undefined, delta: 1 | -1): void {
+    if (pool === "background") this.runningBackground += delta
+    else if (pool === "foreground") this.runningForeground += delta
+  }
+
   /**
    * Kick off an agent's startup and register it under `startups`. The returned
    * promise never rejects — the failure is delivered through `awaitStartup`,
@@ -762,23 +789,19 @@ export class AgentManager {
     // still copying its repo. Claiming "running" here also keeps abort() and
     // abortAll() able to reach an agent whose worktree is still being created.
     //
-    // The pool is resolved ONCE, here, and carried to `settleRun` below:
+    // The pool is resolved ONCE, here, and recorded for `settleRun`:
     // `poolFor` reads `maxConcurrentForeground`, which the user can change from
     // `/agents → Settings` mid-run, so recomputing it at settle time would
     // decrement a pool this run never charged (counter underflow, limit
     // silently lifted) or skip the decrement for one it did (leaked slot —
-    // every later blocking spawn queues forever). The two startup exits below
-    // never reach `settleRun`, so they hand the slot back themselves.
-    const pool = this.poolFor(record)
-    const releaseSlot = () => {
-      if (pool === "background") this.runningBackground--
-      else if (pool === "foreground") this.runningForeground--
-    }
+    // every later blocking spawn queues forever). Only `sendToBackground`
+    // changes it afterwards, moving the counters with it. The two startup exits
+    // below never reach `settleRun`, so they hand the slot back themselves.
+    record.chargedPool = this.poolFor(record)
     record.status = "running"
     record.startedAt = Date.now()
     record.startGate = undefined
-    if (pool === "background") this.runningBackground++
-    else if (pool === "foreground") this.runningForeground++
+    this.chargePool(record.chargedPool, 1)
 
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done BEFORE
@@ -786,11 +809,19 @@ export class AgentManager {
     // The project switch is enforced here as well as at the tool boundary
     // because cross-extension RPC forwards its options unvalidated — a schema
     // that omits the field can't stop a caller that never saw the schema.
+    // The agent file's `isolation:` is resolved here too, not by each caller:
+    // mentions pass none, and RPC forwards only its caller's value. Workflow
+    // children are the exception, as in Claude Code, whose workflow agent()
+    // reads only the script's option and ignores the definition's.
+    const isolation =
+      options.workflowId !== undefined
+        ? options.isolation
+        : (getAgentConfig(type)?.isolation ?? options.isolation)
     let worktreeCwd: string | undefined
-    if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
+    if (isolation === "worktree" && isWorktreeIsolationEnabled()) {
       const wt = await createWorktree(pi, baseCwd, id)
       if (!wt) {
-        releaseSlot()
+        this.chargePool(record.chargedPool, -1)
         throw new Error(
           'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
             "Initialize git and commit at least once, or omit `isolation`.",
@@ -805,6 +836,10 @@ export class AgentManager {
       // subdirectory, silently dropping extensions/skills.
       worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path
       this.worktreeRepos.add(baseCwd)
+      // The widget's "worktree" tag reads this; only callers that resolve the
+      // agent file themselves seed it.
+      record.invocation ??= {}
+      record.invocation.isolation = "worktree"
 
       // No longer "running" means a stop landed while the copy was being made
       // (abort(), abortAll()) — a window that did not exist when creation was
@@ -812,7 +847,7 @@ export class AgentManager {
       // burn tokens on work nobody is waiting for: discard the fresh (and by
       // definition unchanged) worktree instead.
       if (record.status !== "running") {
-        releaseSlot()
+        this.chargePool(record.chargedPool, -1)
         record.worktreeResult = await cleanupWorktree(
           pi,
           baseCwd,
@@ -829,24 +864,13 @@ export class AgentManager {
 
     this.onStart?.(record)
 
-    // Wire parent abort signal to stop the subagent when the parent is interrupted
-    let detachParentSignal: (() => void) | undefined
-    if (options.signal) {
-      // A queued spawn can start minutes after the caller handed us its signal,
-      // by which time it may already be aborted — and `addEventListener` would
-      // never fire, leaving a child the parent can no longer reach.
-      if (options.signal.aborted) this.abort(id)
-      else {
-        const onParentAbort = () => this.abort(id)
-        options.signal.addEventListener("abort", onParentAbort, { once: true })
-        detachParentSignal = () =>
-          options.signal!.removeEventListener("abort", onParentAbort)
-      }
-    }
-    const detach = () => {
-      detachParentSignal?.()
-      detachParentSignal = undefined
-    }
+    // Wire parent abort signal to stop the subagent when the parent is interrupted.
+    // A queued spawn can start minutes after the caller handed us its signal,
+    // by which time it may already be aborted — and `addEventListener` would
+    // never fire, leaving a child the parent can no longer reach.
+    if (options.signal?.aborted) this.abort(id)
+    else this.armParentAbort(record, options.signal)
+    const detach = () => this.detachParentAbort(record)
 
     const promise = runAgent(ctx, type, prompt, {
       pi,
@@ -1019,7 +1043,7 @@ export class AgentManager {
 
           this.abortOwnedChildren(id)
 
-          this.settleRun(record, true, pool)
+          this.settleRun(record, true)
           return responseText
         },
       )
@@ -1061,7 +1085,7 @@ export class AgentManager {
 
         this.abortOwnedChildren(id)
 
-        this.settleRun(record, false, pool)
+        this.settleRun(record, false)
         return ""
       })
 
@@ -1089,18 +1113,19 @@ export class AgentManager {
    *
    * @param guardCallback swallow a throwing `onComplete` (the success path does;
    *   the error path historically did not, and keeps not doing so).
-   * @param pool the pool this run was CHARGED TO at start time — passed in, not
-   *   recomputed, so a mid-run change to `maxConcurrentForeground` can't make
-   *   the release disagree with the acquire.
+   *
+   * Releases `record.chargedPool` — the pool the run was charged to at start
+   * (or moved to by `sendToBackground`), never a recomputed one, so a mid-run
+   * change to `maxConcurrentForeground` can't make the release disagree with
+   * the acquire.
    */
-  private settleRun(
-    record: AgentRecord,
-    guardCallback: boolean,
-    pool: Pool | undefined,
-  ): void {
+  private settleRun(record: AgentRecord, guardCallback: boolean): void {
     if (!record.isBackground) record.resultConsumed = true
-    if (pool === "background") this.runningBackground--
-    else if (pool === "foreground") this.runningForeground--
+    // Nobody waits on a settled run; a later foreground resume must not look
+    // like a spawn `sendToBackground` could hand off.
+    record.blocking = false
+    const pool = record.chargedPool
+    this.chargePool(pool, -1)
 
     if (guardCallback) {
       try {
@@ -1222,10 +1247,10 @@ export class AgentManager {
     // The run promise only exists once startup is past its awaited repo copy —
     // without this the call would return before the agent had started at all.
     // A startup failure (strict worktree isolation) rejects here, which is what
-    // the immediate path owes its caller: pi only marks a tool result failed
-    // when `execute` throws. A queued spawn's failure landed on the record
-    // instead (nobody was awaiting `startups` at drain time) and is rethrown
-    // below, so the contract is the same either way.
+    // the immediate path owes its caller: the Agent tool reports failure by
+    // letting this throw out of `execute`. A queued spawn's failure landed on
+    // the record instead (nobody was awaiting `startups` at drain time) and is
+    // rethrown below, so the contract is the same either way.
     await this.awaitStartup(id)
 
     // undefined when it was aborted while queued, or stopped mid-copy, and so
@@ -1243,6 +1268,49 @@ export class AgentManager {
     return { id, record }
   }
 
+  /**
+   * Hand a live run to the background without restarting it. The session,
+   * promise, in-flight turn, transcript and worktree all continue under the
+   * same id; what changes is who answers for it. The caller's parent-abort
+   * listener comes off (its Esc no longer reaches the run — `abort()` and
+   * `/agents` still do), the slot moves to the background pool, and the run
+   * then settles through the ordinary background path, since `settleRun`
+   * reads the live `isBackground` and `chargedPool`.
+   *
+   * Releasing the caller is the caller's job — the `Agent` tool races its own
+   * wake-up against `spawnAndWait`. This only refuses what it can see: a run
+   * nobody is blocking on (a background or detached spawn, one already handed
+   * off, or a foreground RESUME — `blocking` is cleared when the spawned run
+   * settles, and a resume never charged the slot this would move), and one
+   * that reports through something other than the session (a nested child, a
+   * workflow's agent).
+   *
+   * The background slot is taken even when the pool is full: suspending a
+   * live run is not an option, so it runs over the limit and queued
+   * background work waits for the count to drop, as with `bypassQueue`.
+   */
+  sendToBackground(id: string): boolean {
+    const record = this.agents.get(id)
+    if (
+      !record?.blocking ||
+      !isTopLevelAgent(record) ||
+      record.status !== "running" ||
+      !record.promise
+    )
+      return false
+
+    this.detachParentAbort(record)
+    this.chargePool(record.chargedPool, -1)
+    record.chargedPool = "background"
+    this.chargePool(record.chargedPool, 1)
+    record.blocking = false
+    record.isBackground = true
+    record.resultConsumed = false
+    // A freed foreground slot may have unblocked a queued blocking spawn.
+    this.drainQueue()
+    return true
+  }
+
   /**
    * Resume an existing agent session with a new prompt.
    */