@pi-unipi/subagents 2.4.0 → 2.4.1

package/src/__tests__/workflow-integration.test.ts

@@ -1,334 +0,0 @@
-/**
- * Test: Workflow integration — `/unipi:work` with subagent support
- *
- * Verifies:
- * - spawn_helper and get_helper_result tools are properly defined
- * - Agent types (explore, work) are correctly configured
- * - Concurrency limit is respected
- * - Custom agent type loading works
- * - System prompt builder generates correct prompts
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-
-// Test type definitions
-const BUILTIN_TYPES = ["explore", "work"] as const;
-
-interface AgentConfig {
-  name: string;
-  displayName?: string;
-  description: string;
-  builtinToolNames?: string[];
-  disallowedTools?: string[];
-  extensions: true | string[] | false;
-  skills: true | string[] | false;
-  model?: string;
-  thinking?: string;
-  maxTurns?: number;
-  systemPrompt: string;
-  promptMode: "replace" | "append";
-  inheritContext?: boolean;
-  runInBackground?: boolean;
-  isolated?: boolean;
-  memory?: string;
-  isDefault?: boolean;
-  enabled?: boolean;
-  source?: "builtin" | "project" | "global";
-}
-
-// Test prompt builder
-function buildAgentPrompt(
-  config: AgentConfig,
-  cwd: string,
-  env: { isGitRepo: boolean; branch: string; platform: string },
-  parentSystemPrompt: string,
-): string {
-  if (config.promptMode === "append") {
-    return [
-      parentSystemPrompt,
-      "",
-      "---",
-      "",
-      `## Agent Role: ${config.displayName ?? config.name}`,
-      config.systemPrompt,
-    ].join("\n");
-  }
-
-  return [
-    `# ${config.displayName ?? config.name}`,
-    "",
-    config.systemPrompt,
-    "",
-    "---",
-    "",
-    `Working directory: ${cwd}`,
-    `Git: ${env.isGitRepo ? `${env.branch} on ${env.platform}` : "not a git repo"}`,
-  ].join("\n");
-}
-
-// Test concurrency manager
-class ConcurrencyManager {
-  private maxConcurrent: number;
-  private running: number = 0;
-  private queue: Array<{ id: string; resolve: () => void }> = [];
-
-  constructor(maxConcurrent: number) {
-    this.maxConcurrent = maxConcurrent;
-  }
-
-  async acquire(id: string): Promise<() => void> {
-    if (this.running >= this.maxConcurrent) {
-      await new Promise<void>((resolve) => {
-        this.queue.push({ id, resolve });
-      });
-    }
-
-    this.running++;
-
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      this.running--;
-
-      // Start next in queue
-      if (this.queue.length > 0) {
-        const next = this.queue.shift()!;
-        next.resolve();
-      }
-    };
-  }
-
-  getRunning(): number {
-    return this.running;
-  }
-
-  getQueueLength(): number {
-    return this.queue.length;
-  }
-}
-
-describe("Workflow Integration", () => {
-  describe("Tool Definitions", () => {
-    it("should define spawn_helper tool with correct parameters", () => {
-      const toolDef = {
-        name: "spawn_helper",
-        description: "Launch a sub-agent for parallel work.",
-        parameters: {
-          type: "object",
-          required: ["type", "prompt", "description"],
-          properties: {
-            type: { type: "string" },
-            prompt: { type: "string" },
-            description: { type: "string" },
-            run_in_background: { type: "boolean" },
-            max_turns: { type: "number" },
-            model: { type: "string" },
-            thinking: { type: "string" },
-          },
-        },
-      };
-
-      assert.equal(toolDef.name, "spawn_helper");
-      assert.equal(toolDef.parameters.required.length, 3);
-      assert.ok(toolDef.parameters.properties.type);
-      assert.ok(toolDef.parameters.properties.prompt);
-      assert.ok(toolDef.parameters.properties.description);
-    });
-
-    it("should define get_helper_result tool with correct parameters", () => {
-      const toolDef = {
-        name: "get_helper_result",
-        description: "Check status and retrieve results from a background agent.",
-        parameters: {
-          type: "object",
-          required: ["agent_id"],
-          properties: {
-            agent_id: { type: "string" },
-            wait: { type: "boolean" },
-          },
-        },
-      };
-
-      assert.equal(toolDef.name, "get_helper_result");
-      assert.equal(toolDef.parameters.required.length, 1);
-      assert.ok(toolDef.parameters.properties.agent_id);
-    });
-  });
-
-  describe("Agent Types", () => {
-    it("should have explore and work as builtin types", () => {
-      assert.deepEqual(BUILTIN_TYPES, ["explore", "work"]);
-    });
-
-    it("should define explore agent with read-only tools", () => {
-      const exploreConfig: AgentConfig = {
-        name: "explore",
-        description: "Fast parallel codebase exploration",
-        builtinToolNames: ["read", "bash", "grep", "find", "ls"],
-        systemPrompt: "You are a read-only exploration agent.",
-        promptMode: "replace",
-        extensions: true,
-        skills: true,
-      };
-
-      assert.ok(!exploreConfig.builtinToolNames?.includes("write"));
-      assert.ok(!exploreConfig.builtinToolNames?.includes("edit"));
-      assert.ok(exploreConfig.builtinToolNames?.includes("read"));
-    });
-
-    it("should define work agent with read-write tools", () => {
-      const workConfig: AgentConfig = {
-        name: "work",
-        description: "Parallel file writes with transparent locking",
-        builtinToolNames: ["read", "write", "edit", "bash", "grep", "find", "ls"],
-        systemPrompt: "You are a read-write work agent.",
-        promptMode: "replace",
-        extensions: true,
-        skills: true,
-      };
-
-      assert.ok(workConfig.builtinToolNames?.includes("write"));
-      assert.ok(workConfig.builtinToolNames?.includes("edit"));
-      assert.ok(workConfig.builtinToolNames?.includes("read"));
-    });
-  });
-
-  describe("System Prompt Builder", () => {
-    const env = {
-      isGitRepo: true,
-      branch: "main",
-      platform: "GitHub",
-    };
-
-    it("should build replace mode prompt", () => {
-      const config: AgentConfig = {
-        name: "explore",
-        displayName: "Explorer",
-        description: "Test",
-        systemPrompt: "Find all authentication files.",
-        promptMode: "replace",
-        extensions: true,
-        skills: true,
-      };
-
-      const prompt = buildAgentPrompt(config, "/workspace", env, "Parent prompt");
-
-      assert.ok(prompt.startsWith("# Explorer"));
-      assert.ok(prompt.includes("Find all authentication files."));
-      assert.ok(prompt.includes("Working directory: /workspace"));
-      assert.ok(!prompt.includes("Parent prompt"));
-    });
-
-    it("should build append mode prompt", () => {
-      const config: AgentConfig = {
-        name: "work",
-        displayName: "Worker",
-        description: "Test",
-        systemPrompt: "Refactor the auth module.",
-        promptMode: "append",
-        extensions: true,
-        skills: true,
-      };
-
-      const prompt = buildAgentPrompt(config, "/workspace", env, "Parent prompt");
-
-      assert.ok(prompt.startsWith("Parent prompt"));
-      assert.ok(prompt.includes("## Agent Role: Worker"));
-      assert.ok(prompt.includes("Refactor the auth module."));
-    });
-  });
-
-  describe("Concurrency Limit", () => {
-    it("should respect max concurrent limit", async () => {
-      const manager = new ConcurrencyManager(2);
-      const events: string[] = [];
-
-      // Start 3 agents, only 2 should run immediately
-      const release1 = await manager.acquire("agent-1");
-      events.push("agent-1-started");
-
-      const release2 = await manager.acquire("agent-2");
-      events.push("agent-2-started");
-
-      assert.equal(manager.getRunning(), 2);
-      assert.deepEqual(events, ["agent-1-started", "agent-2-started"]);
-
-      // Third agent should queue
-      const acquire3Promise = manager.acquire("agent-3").then((release) => {
-        events.push("agent-3-started");
-        return release;
-      });
-
-      assert.equal(manager.getQueueLength(), 1);
-
-      // Release first agent
-      release1();
-      const release3 = await acquire3Promise;
-
-      assert.equal(manager.getRunning(), 2);
-      assert.deepEqual(events, ["agent-1-started", "agent-2-started", "agent-3-started"]);
-
-      release2();
-      release3();
-    });
-
-    it("should queue agents in order", async () => {
-      const manager = new ConcurrencyManager(1);
-      const events: string[] = [];
-
-      const release1 = await manager.acquire("agent-1");
-      events.push("1");
-
-      const p2 = manager.acquire("agent-2").then(r => { events.push("2"); return r; });
-      const p3 = manager.acquire("agent-3").then(r => { events.push("3"); return r; });
-
-      release1();
-      const release2 = await p2;
-      release2();
-      const release3 = await p3;
-
-      assert.deepEqual(events, ["1", "2", "3"]);
-      release3();
-    });
-  });
-
-  describe("Custom Agent Loading", () => {
-    it("should parse agent markdown frontmatter", () => {
-      const markdown = `---
-name: code-checker
-description: Code quality checker
-tools: read, grep, find, bash
-thinking: high
----
-You are a code quality checker. Review code for issues.`;
-
-      // Simple frontmatter parser
-      const match = markdown.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-      assert.ok(match);
-
-      const frontmatter = match![1];
-      const body = match![2];
-
-      assert.ok(frontmatter.includes("name: code-checker"));
-      assert.ok(frontmatter.includes("tools: read, grep, find, bash"));
-      assert.ok(body.includes("You are a code quality checker."));
-    });
-
-    it("should validate required fields", () => {
-      const validAgent = {
-        name: "test-agent",
-        description: "Test agent",
-        systemPrompt: "Do something.",
-        promptMode: "replace" as const,
-        extensions: true as const,
-        skills: true as const,
-      };
-
-      assert.ok(validAgent.name);
-      assert.ok(validAgent.description);
-      assert.ok(validAgent.systemPrompt);
-    });
-  });
-});

package/src/agent-manager.ts

@@ -1,334 +0,0 @@
-/**
- * @pi-unipi/subagents — Agent manager
- *
- * Tracks agents, manages concurrency queue, handles spawn/resume/abort.
- * Background agents subject to concurrency limit. Foreground bypass queue.
- */
-
-import { randomUUID } from "node:crypto";
-import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { runAgent, type ToolActivity } from "./agent-runner.js";
-import { resolveModel, type ModelRegistry } from "./model-resolver.js";
-import type { AgentRecord, AgentConfig, AgentType, ThinkingLevel } from "./types.js";
-import { BUILTIN_CONFIGS } from "./types.js";
-import { loadCustomAgents } from "./custom-agents.js";
-import { FileLock } from "./file-lock.js";
-
-export type OnAgentComplete = (record: AgentRecord) => void;
-export type OnAgentStart = (record: AgentRecord) => void;
-
-/** Default max concurrent background agents. */
-const DEFAULT_MAX_CONCURRENT = 4;
-
-interface SpawnArgs {
-  pi: ExtensionAPI;
-  ctx: ExtensionContext;
-  type: AgentType;
-  prompt: string;
-  options: SpawnOptions;
-}
-
-interface SpawnOptions {
-  description: string;
-  model?: Model<any>;
-  modelInput?: string;
-  modelRegistry?: ModelRegistry;
-  thinkingLevel?: ThinkingLevel;
-  maxTurns?: number;
-  isolated?: boolean;
-  inheritContext?: boolean;
-  isBackground?: boolean;
-  onToolActivity?: (activity: ToolActivity) => void;
-  onTextDelta?: (delta: string, fullText: string) => void;
-  onSessionCreated?: (session: AgentSession) => void;
-  onTurnEnd?: (turnCount: number) => void;
-}
-
-export class AgentManager {
-  private agents = new Map<string, AgentRecord>();
-  private cleanupInterval: ReturnType<typeof setInterval>;
-  private onComplete?: OnAgentComplete;
-  private onStart?: OnAgentStart;
-  private maxConcurrent: number;
-  private customAgents: Map<string, AgentConfig>;
-
-  /** Per-file transparent locking for write agents. */
-  readonly fileLock = new FileLock();
-
-  /** Queue of background agents waiting to start. */
-  private queue: { id: string; args: SpawnArgs }[] = [];
-  /** Number of currently running background agents. */
-  private runningBackground = 0;
-
-  constructor(onComplete?: OnAgentComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart?: OnAgentStart) {
-    this.onComplete = onComplete;
-    this.onStart = onStart;
-    this.maxConcurrent = maxConcurrent;
-    this.customAgents = loadCustomAgents(process.cwd());
-    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
-  }
-
-  /** Get resolved agent config for a type. */
-  getAgentConfig(type: AgentType): AgentConfig | undefined {
-    return this.customAgents.get(type) ?? BUILTIN_CONFIGS[type];
-  }
-
-  setMaxConcurrent(n: number) {
-    this.maxConcurrent = Math.max(1, n);
-    this.drainQueue();
-  }
-
-  getMaxConcurrent(): number {
-    return this.maxConcurrent;
-  }
-
-  /**
-   * Spawn an agent. Returns ID immediately for background, waits for foreground.
-   */
-  spawn(
-    pi: ExtensionAPI,
-    ctx: ExtensionContext,
-    type: AgentType,
-    prompt: string,
-    options: SpawnOptions,
-  ): string {
-    const id = randomUUID().slice(0, 17);
-    const abortController = new AbortController();
-    const record: AgentRecord = {
-      id,
-      type,
-      description: options.description,
-      status: options.isBackground ? "queued" : "running",
-      toolUses: 0,
-      startedAt: Date.now(),
-      abortController,
-      lockedFiles: new Set(),
-    };
-    this.agents.set(id, record);
-
-    const args: SpawnArgs = { pi, ctx, type, prompt, options };
-
-    if (options.isBackground && this.runningBackground >= this.maxConcurrent) {
-      this.queue.push({ id, args });
-      return id;
-    }
-
-    this.startAgent(id, record, args);
-    return id;
-  }
-
-  /** Actually start an agent. */
-  private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
-    record.status = "running";
-    record.startedAt = Date.now();
-    if (options.isBackground) this.runningBackground++;
-    this.onStart?.(record);
-
-    // Resolve model: explicit input > config model > parent model
-    let model = options.model;
-    if (options.modelInput && options.modelRegistry) {
-      const resolved = resolveModel(options.modelInput, options.modelRegistry);
-      if (typeof resolved === "string") {
-        // Error message — return early with error
-        record.status = "error";
-        record.error = resolved;
-        record.completedAt = Date.now();
-        if (options.isBackground) {
-          this.runningBackground--;
-          this.onComplete?.(record);
-        }
-        return;
-      }
-      model = resolved;
-    }
-
-    const agentConfig = this.getAgentConfig(type);
-    const promise = runAgent(ctx, type, prompt, {
-      pi,
-      model,
-      agentConfig,
-      maxTurns: options.maxTurns,
-      isolated: options.isolated,
-      inheritContext: options.inheritContext,
-      thinkingLevel: options.thinkingLevel,
-      signal: record.abortController!.signal,
-      onToolActivity: (activity) => {
-        if (activity.type === "end") record.toolUses++;
-        options.onToolActivity?.(activity);
-      },
-      onTurnEnd: options.onTurnEnd,
-      onTextDelta: options.onTextDelta,
-      onSessionCreated: (session) => {
-        record.session = session;
-        options.onSessionCreated?.(session);
-      },
-    })
-      .then(({ responseText, session, aborted, steered }) => {
-        if (record.status !== "stopped") {
-          record.status = aborted ? "aborted" : steered ? "completed" : "completed";
-        }
-        record.result = responseText;
-        record.session = session;
-        record.completedAt ??= Date.now();
-
-        // Release any held file locks
-        this.fileLock.releaseAll(id);
-        record.lockedFiles.clear();
-
-        if (options.isBackground) {
-          this.runningBackground--;
-          this.onComplete?.(record);
-          this.drainQueue();
-        }
-        return responseText;
-      })
-      .catch((err) => {
-        if (record.status !== "stopped") {
-          record.status = "error";
-        }
-        record.error = err instanceof Error ? err.message : String(err);
-        record.completedAt ??= Date.now();
-
-        // Release any held file locks
-        this.fileLock.releaseAll(id);
-        record.lockedFiles.clear();
-
-        if (options.isBackground) {
-          this.runningBackground--;
-          this.onComplete?.(record);
-          this.drainQueue();
-        }
-        return "";
-      });
-
-    record.promise = promise;
-  }
-
-  /** Start queued agents up to concurrency limit. */
-  private drainQueue() {
-    while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
-      const next = this.queue.shift()!;
-      const record = this.agents.get(next.id);
-      if (!record || record.status !== "queued") continue;
-      this.startAgent(next.id, record, next.args);
-    }
-  }
-
-  /**
-   * Spawn and wait (foreground).
-   */
-  async spawnAndWait(
-    pi: ExtensionAPI,
-    ctx: ExtensionContext,
-    type: AgentType,
-    prompt: string,
-    options: Omit<SpawnOptions, "isBackground">,
-  ): Promise<AgentRecord> {
-    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-    const record = this.agents.get(id)!;
-    await record.promise;
-    return record;
-  }
-
-  getRecord(id: string): AgentRecord | undefined {
-    return this.agents.get(id);
-  }
-
-  listAgents(): AgentRecord[] {
-    return [...this.agents.values()].sort((a, b) => b.startedAt - a.startedAt);
-  }
-
-  abort(id: string): boolean {
-    const record = this.agents.get(id);
-    if (!record) return false;
-
-    if (record.status === "queued") {
-      this.queue = this.queue.filter((q) => q.id !== id);
-      record.status = "stopped";
-      record.completedAt = Date.now();
-      return true;
-    }
-
-    if (record.status !== "running") return false;
-    record.abortController?.abort();
-    record.status = "stopped";
-    record.completedAt = Date.now();
-    this.fileLock.releaseAll(id);
-    record.lockedFiles.clear();
-    return true;
-  }
-
-  /** Abort all agents (for ESC propagation). */
-  abortAll(): number {
-    let count = 0;
-    for (const queued of this.queue) {
-      const record = this.agents.get(queued.id);
-      if (record) {
-        record.status = "stopped";
-        record.completedAt = Date.now();
-        count++;
-      }
-    }
-    this.queue = [];
-    for (const record of this.agents.values()) {
-      if (record.status === "running") {
-        record.abortController?.abort();
-        record.status = "stopped";
-        record.completedAt = Date.now();
-        count++;
-      }
-    }
-    this.fileLock.clear();
-    return count;
-  }
-
-  /** Wait for all agents. */
-  async waitForAll(): Promise<void> {
-    while (true) {
-      this.drainQueue();
-      const pending = [...this.agents.values()]
-        .filter((r) => r.status === "running" || r.status === "queued")
-        .map((r) => r.promise)
-        .filter(Boolean);
-      if (pending.length === 0) break;
-      await Promise.allSettled(pending);
-    }
-  }
-
-  /** Whether any agents running or queued. */
-  hasRunning(): boolean {
-    return [...this.agents.values()].some((r) => r.status === "running" || r.status === "queued");
-  }
-
-  /** Remove completed records. */
-  clearCompleted(): void {
-    for (const [id, record] of this.agents) {
-      if (record.status === "running" || record.status === "queued") continue;
-      record.session?.dispose?.();
-      record.session = undefined;
-      this.agents.delete(id);
-    }
-  }
-
-  private cleanup() {
-    const cutoff = Date.now() - 10 * 60_000;
-    for (const [id, record] of this.agents) {
-      if (record.status === "running" || record.status === "queued") continue;
-      if ((record.completedAt ?? 0) >= cutoff) continue;
-      record.session?.dispose?.();
-      record.session = undefined;
-      this.agents.delete(id);
-    }
-  }
-
-  dispose() {
-    clearInterval(this.cleanupInterval);
-    this.queue = [];
-    this.abortAll();
-    for (const record of this.agents.values()) {
-      record.session?.dispose();
-    }
-    this.agents.clear();
-  }
-}