pi-fast-subagent 0.2.0 → 0.4.0

package/README.md

@@ -8,6 +8,7 @@ Runs subagents with `createAgentSession()` in same process instead of spawning `
 
 - Single mode: `{ agent, task }`
 - Parallel mode: `{ tasks: [...] }`
+- Background mode: `{ agent, task, background: true }` — fire-and-forget with poll/cancel
 - Per-call model override
 - User + project agent discovery
 - Project agents override user agents
@@ -59,6 +60,24 @@ model: anthropic/claude-haiku-4-5
 You are code exploration specialist. Read relevant files, trace data flow, summarize findings clearly.
 ```
 
+## Slash Commands
+
+### `/agent`
+
+List all available agents:
+
+```
+/agent
+```
+
+Show details for a specific agent (description, file path, model, tools, system prompt):
+
+```
+/agent scout
+```
+
+Tab-completion is supported for agent names.
+
 ## Usage
 
 ### List agents

package/background-job-manager.ts

@@ -0,0 +1,178 @@
+import { randomUUID } from "node:crypto";
+import type {
+  BackgroundHandleLike,
+  BackgroundJobManagerOptions,
+  BackgroundJobResult,
+  BackgroundSubagentJob,
+} from "./background-types.js";
+
+export type { BackgroundSubagentJob } from "./background-types.js";
+
+export class BackgroundJobManager {
+  private jobs = new Map<string, BackgroundSubagentJob>();
+  private evictionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private maxRunning: number;
+  private maxTotal: number;
+  private evictionMs: number;
+  private onJobComplete?: (job: BackgroundSubagentJob) => void;
+  private isShutdown = false;
+
+  constructor(options: BackgroundJobManagerOptions = {}) {
+    this.maxRunning = options.maxRunning ?? 10;
+    this.maxTotal = options.maxTotal ?? 50;
+    this.evictionMs = options.evictionMs ?? 5 * 60 * 1000;
+    this.onJobComplete = options.onJobComplete;
+  }
+
+  adoptHandle(
+    agentName: string,
+    task: string,
+    cwd: string,
+    handle: BackgroundHandleLike,
+    resultPromise: Promise<BackgroundJobResult>,
+  ): string {
+    handle.detach?.();
+
+    const abortController = new AbortController();
+    const onAbort = () => handle.abort();
+    abortController.signal.addEventListener("abort", onAbort, { once: true });
+
+    return this.attachJob(agentName, task, cwd, abortController, resultPromise.finally(() => {
+      abortController.signal.removeEventListener("abort", onAbort);
+    }));
+  }
+
+  cancel(id: string): "cancelled" | "not_found" | "already_done" {
+    const job = this.jobs.get(id);
+    if (!job) return "not_found";
+    if (job.status !== "running") return "already_done";
+
+    job.status = "cancelled";
+    job.completedAt = Date.now();
+    job.abortController.abort();
+    this.scheduleEviction(id);
+    return "cancelled";
+  }
+
+  getJob(id: string): BackgroundSubagentJob | undefined {
+    return this.jobs.get(id);
+  }
+
+  getRunningJobs(): BackgroundSubagentJob[] {
+    return [...this.jobs.values()].filter((job) => job.status === "running");
+  }
+
+  getAllJobs(): BackgroundSubagentJob[] {
+    return [...this.jobs.values()];
+  }
+
+  shutdown(): void {
+    this.isShutdown = true;
+    for (const timer of this.evictionTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.evictionTimers.clear();
+
+    for (const job of this.jobs.values()) {
+      if (job.status === "running") {
+        job.status = "cancelled";
+        job.completedAt = Date.now();
+        job.abortController.abort();
+      }
+    }
+  }
+
+  private attachJob(
+    agentName: string,
+    task: string,
+    cwd: string,
+    abortController: AbortController,
+    resultPromise: Promise<BackgroundJobResult>,
+  ): string {
+    if (this.getRunningJobs().length >= this.maxRunning) {
+      throw new Error(`Maximum concurrent background subagents reached (${this.maxRunning}).`);
+    }
+
+    if (this.jobs.size >= this.maxTotal) {
+      this.evictOldestCompleted();
+      if (this.jobs.size >= this.maxTotal) {
+        throw new Error(`Maximum total background subagent jobs reached (${this.maxTotal}).`);
+      }
+    }
+
+    const id = `sa_${randomUUID().slice(0, 8)}`;
+    const job: BackgroundSubagentJob = {
+      id,
+      agentName,
+      task,
+      cwd,
+      status: "running",
+      startedAt: Date.now(),
+      abortController,
+      promise: undefined as unknown as Promise<void>,
+    };
+
+    job.promise = resultPromise
+      .then((result) => {
+        if (job.status === "cancelled") {
+          this.scheduleEviction(id);
+          return;
+        }
+        job.status = result.exitCode === 0 ? "completed" : "failed";
+        job.completedAt = Date.now();
+        job.exitCode = result.exitCode;
+        job.resultSummary = result.summary;
+        job.error = result.error;
+        job.model = result.model;
+        this.scheduleEviction(id);
+        this.deliverResult(job);
+      })
+      .catch((error) => {
+        if (job.status === "cancelled") {
+          this.scheduleEviction(id);
+          return;
+        }
+        job.status = "failed";
+        job.completedAt = Date.now();
+        job.exitCode = 1;
+        job.error = error instanceof Error ? error.message : String(error);
+        this.scheduleEviction(id);
+        this.deliverResult(job);
+      });
+
+    this.jobs.set(id, job);
+    return id;
+  }
+
+  private deliverResult(job: BackgroundSubagentJob): void {
+    if (!this.onJobComplete) return;
+    queueMicrotask(() => this.onJobComplete?.(job));
+  }
+
+  private scheduleEviction(id: string): void {
+    if (this.isShutdown) return;
+    const existing = this.evictionTimers.get(id);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.evictionTimers.delete(id);
+      this.jobs.delete(id);
+    }, this.evictionMs);
+
+    this.evictionTimers.set(id, timer);
+  }
+
+  private evictOldestCompleted(): void {
+    let oldest: BackgroundSubagentJob | undefined;
+    for (const job of this.jobs.values()) {
+      if (job.status === "running") continue;
+      if (!oldest || job.startedAt < oldest.startedAt) oldest = job;
+    }
+    if (!oldest) return;
+
+    const timer = this.evictionTimers.get(oldest.id);
+    if (timer) clearTimeout(timer);
+    this.evictionTimers.delete(oldest.id);
+    this.jobs.delete(oldest.id);
+  }
+}

package/background-types.ts

@@ -0,0 +1,36 @@
+export type BackgroundJobStatus = "running" | "completed" | "failed" | "cancelled";
+
+export interface BackgroundSubagentJob {
+  id: string;
+  agentName: string;
+  task: string;
+  cwd: string;
+  status: BackgroundJobStatus;
+  startedAt: number;
+  completedAt?: number;
+  exitCode?: number;
+  resultSummary?: string;
+  error?: string;
+  model?: string;
+  abortController: AbortController;
+  promise: Promise<void>;
+}
+
+export interface BackgroundJobManagerOptions {
+  maxRunning?: number;
+  maxTotal?: number;
+  evictionMs?: number;
+  onJobComplete?: (job: BackgroundSubagentJob) => void;
+}
+
+export interface BackgroundJobResult {
+  summary: string;
+  exitCode: number;
+  error?: string;
+  model?: string;
+}
+
+export interface BackgroundHandleLike {
+  abort: () => void;
+  detach?: () => void;
+}

package/index.ts

@@ -15,6 +15,8 @@ import type {
   ExtensionContext,
   ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
+import { BackgroundJobManager } from "./background-job-manager.js";
+import type { BackgroundHandleLike, BackgroundJobResult } from "./background-types.js";
 import { Theme } from "@mariozechner/pi-coding-agent";
 import { truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 import { truncateToVisualLines, keyHint } from "@mariozechner/pi-coding-agent";
@@ -94,6 +96,7 @@ function summarizeToolArgs(toolName: unknown, toolInput: unknown): string {
 
 let _authStorage: ReturnType<typeof AuthStorage.create> | null = null;
 let _modelRegistry: ReturnType<typeof ModelRegistry.create> | null = null;
+let _bgManager: BackgroundJobManager | null = null;
 
 function getAuth() {
   if (!_authStorage) _authStorage = AuthStorage.create();
@@ -101,6 +104,11 @@ function getAuth() {
   return { authStorage: _authStorage, modelRegistry: _modelRegistry };
 }
 
+function getBgManager(): BackgroundJobManager {
+  if (!_bgManager) _bgManager = new BackgroundJobManager();
+  return _bgManager;
+}
+
 // ─── In-process runner ───────────────────────────────────────────────────────
 
 const MAX_DEPTH = 2;
@@ -231,7 +239,10 @@ async function runAgent(
   const toolCalls: ToolCallEntry[] = [];
   const toolStartTimes = new Map<string, number>();
 
+  let done = false;
+
   function emitUpdate(): void {
+    if (done) return;
     onUpdate?.({
       content: [{ type: "text", text: currentDelta || lastOutput || "" }],
       details: {
@@ -354,6 +365,7 @@ async function runAgent(
     exitCode = 1;
     error = signal?.aborted ? "Aborted" : e instanceof Error ? e.message : String(e);
   } finally {
+    done = true;
     clearInterval(heartbeat);
     unsubscribe();
     session.dispose();
@@ -436,14 +448,21 @@ const SubagentParams = Type.Object({
     Type.Number({ description: "Max parallel concurrency (default: 4)", default: 4 }),
   ),
 
+  // Background
+  background: Type.Optional(Type.Boolean({ description: "Run in background, returns job ID immediately" })),
+  jobId: Type.Optional(Type.String({ description: "Job ID for poll/cancel" })),
+
   // Management
   action: Type.Optional(
     Type.Union(
       [
         Type.Literal("list"),
         Type.Literal("get"),
+        Type.Literal("status"),
+        Type.Literal("poll"),
+        Type.Literal("cancel"),
       ],
-      { description: "'list' to discover agents, 'get' to inspect one agent" },
+      { description: "'list'/'get' for agents, 'status' for bg jobs, 'poll'/'cancel' for a specific job" },
     ),
   ),
   agentScope: Type.Optional(
@@ -457,6 +476,72 @@ const SubagentParams = Type.Object({
 // ─── Extension entry point ────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
+  // ─── /agent slash command ─────────────────────────────────────────────────
+  pi.registerCommand("agent", {
+    description: "List available subagents. Usage: /agent [name] — show details for a specific agent.",
+    getArgumentCompletions(prefix: string) {
+      const agents = discoverAgents(process.cwd());
+      return agents
+        .filter((a) => a.name.startsWith(prefix))
+        .map((a) => ({ value: a.name, label: a.name, description: a.description }));
+    },
+    async handler(args: string, ctx) {
+      const agents = discoverAgents(ctx.cwd);
+      const name = args.trim();
+
+      if (name) {
+        const agent = agents.find((a) => a.name === name);
+        if (!agent) {
+          const list = agents.map((a) => a.name).join(", ") || "none";
+          ctx.ui.notify(`Unknown agent "${name}". Available: ${list}`, "warning");
+          return;
+        }
+        const lines = [
+          `## ${agent.name} [${agent.source}]`,
+          `File: ${agent.filePath}`,
+          `Description: ${agent.description}`,
+          agent.model ? `Model: ${agent.model}` : "",
+          agent.tools ? `Tools: ${agent.tools.join(", ")}` : "",
+          agent.systemPrompt ? `\nSystem prompt:\n${agent.systemPrompt}` : "",
+        ].filter(Boolean).join("\n");
+        ctx.ui.notify(lines, "info");
+        return;
+      }
+
+      if (agents.length === 0) {
+        ctx.ui.notify(
+          "No agents found.\n" +
+          "Add .md files to:\n" +
+          "  ~/.pi/agent/agents/   (user-level)\n" +
+          "  .pi/agents/           (project-level)\n" +
+          "\nFrontmatter required: name, description. Optional: model, tools.",
+          "info"
+        );
+        return;
+      }
+
+      const userAgents = agents.filter((a) => a.source === "user");
+      const projectAgents = agents.filter((a) => a.source === "project");
+
+      const lines: string[] = [`Agents (${agents.length}):`];
+      if (projectAgents.length) {
+        lines.push("\nProject (.pi/agents/):");
+        for (const a of projectAgents) {
+          lines.push(`  ${a.name}${a.model ? ` [${a.model}]` : ""} — ${a.description}`);
+        }
+      }
+      if (userAgents.length) {
+        lines.push("\nUser (~/.pi/agent/agents/):");
+        for (const a of userAgents) {
+          lines.push(`  ${a.name}${a.model ? ` [${a.model}]` : ""} — ${a.description}`);
+        }
+      }
+      lines.push("");
+      lines.push("Tip: /agent <name> for details · Add .md files to .pi/agents/ to create new agents");
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
@@ -655,7 +740,7 @@ export default function (pi: ExtensionAPI) {
       };
 
       // ── Management: list ──────────────────────────────────────────────────────
-      if (params.action === "list" || (!params.agent && !params.tasks)) {
+      if (params.action === "list" || (!params.action && !params.agent && !params.tasks)) {
         if (agents.length === 0) {
           return {
             content: [{
@@ -684,11 +769,56 @@ export default function (pi: ExtensionAPI) {
         return { content: [{ type: "text", text: info }] };
       }
 
+      // ── Background status ───────────────────────────────────────────────────
+      if (params.action === "status") {
+        const jobs = getBgManager().getAllJobs();
+        if (jobs.length === 0) return { content: [{ type: "text", text: "No background jobs." }] };
+        const lines = jobs.map((j) => {
+          const dur = j.completedAt ? formatDuration(j.completedAt - j.startedAt) : formatDuration(Date.now() - j.startedAt);
+          return `${j.id} [${j.status}] ${j.agentName} · ${dur} · ${j.task.length > 50 ? j.task.slice(0, 47) + "..." : j.task}`;
+        });
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
+      // ── Background poll ────────────────────────────────────────────────────────
+      if (params.action === "poll") {
+        if (!params.jobId) return { content: [{ type: "text", text: "Provide jobId to poll." }] };
+        const job = getBgManager().getJob(params.jobId);
+        if (!job) return { content: [{ type: "text", text: `Job ${params.jobId} not found (completed and evicted, or invalid).` }] };
+        const dur = job.completedAt ? formatDuration(job.completedAt - job.startedAt) : formatDuration(Date.now() - job.startedAt);
+        const parts = [`${job.id} [${job.status}] ${job.agentName} · ${dur}`, `Task: ${job.task}`];
+        if (job.status === "completed") parts.push(`\nResult:\n${job.resultSummary ?? "(no output)"}`);
+        if (job.status === "failed") parts.push(`\nError: ${job.error ?? "(unknown)"}`);
+        if (job.status === "running") parts.push("Still running — poll again later.");
+        return { content: [{ type: "text", text: parts.join("\n") }] };
+      }
+
+      // ── Background cancel ──────────────────────────────────────────────────────
+      if (params.action === "cancel") {
+        if (!params.jobId) return { content: [{ type: "text", text: "Provide jobId to cancel." }] };
+        const result = getBgManager().cancel(params.jobId);
+        const msg = result === "cancelled" ? `Job ${params.jobId} cancelled.`
+          : result === "already_done" ? `Job ${params.jobId} already completed.`
+          : `Job ${params.jobId} not found.`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+
       // ── Single mode ───────────────────────────────────────────────────────────
       if (params.agent && params.task) {
         const { agent, error } = findAgent(params.agent);
         if (error || !agent) return { content: [{ type: "text", text: error ?? "Not found" }] };
 
+        // Background dispatch — fire and forget
+        if (params.background) {
+          const bgAbort = new AbortController();
+          const handle: BackgroundHandleLike = { abort: () => bgAbort.abort() };
+          const resultPromise: Promise<BackgroundJobResult> = runAgent(
+            agent, params.task, cwd, params.model, bgAbort.signal, undefined
+          ).then((r) => ({ summary: r.output, exitCode: r.exitCode, error: r.error, model: r.model }));
+          const jobId = getBgManager().adoptHandle(agent.name, params.task, cwd, handle, resultPromise);
+          return { content: [{ type: "text", text: `Background job started: ${jobId}\nCheck progress: subagent({ action: "poll", jobId: "${jobId}" })` }] };
+        }
+
         const result = await runAgent(
           agent,
           params.task,

package/package.json

@@ -1,14 +1,27 @@
 {
   "name": "pi-fast-subagent",
-  "version": "0.2.0",
-  "description": "In-process subagent delegation for pi with single, parallel, and chain modes",
+  "version": "0.4.0",
+  "description": "In-process subagent delegation for pi with single, parallel, and background modes",
   "type": "module",
   "keywords": [
     "pi-package",
     "pi",
+    "pi-extension",
     "subagent",
     "agents",
-    "extension"
+    "extension",
+    "delegation",
+    "parallel",
+    "concurrent",
+    "in-process",
+    "fast",
+    "coding-agent",
+    "ai-agent",
+    "llm",
+    "task-runner",
+    "scout",
+    "workflow",
+    "automation"
   ],
   "homepage": "https://github.com/tuansondinh/pi-fast-subagent#readme",
   "repository": {
@@ -21,6 +34,8 @@
   "files": [
     "index.ts",
     "agents.ts",
+    "background-job-manager.ts",
+    "background-types.ts",
     "agents/*.md",
     "README.md"
   ],