@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/shared/worktree-pool.ts

@@ -0,0 +1,103 @@
+/**
+ * Worktree Pool — manages a set of per-PR git worktrees for a review session.
+ *
+ * Runtime-agnostic. Uses ReviewGitRuntime for all git operations.
+ * Both Bun and Pi servers import this module (Pi via vendor.sh).
+ *
+ * Each PR visited during a session gets its own worktree, created on first
+ * access and cached for the session lifetime. Agents run in their PR's
+ * worktree undisturbed by PR switches.
+ */
+
+import { join } from "node:path";
+import type { ReviewGitRuntime } from "./review-core";
+import type { PRMetadata } from "./pr-types";
+import { createWorktree, removeWorktree, fetchRef, ensureObjectAvailable } from "./worktree";
+
+export interface PoolEntry {
+  path: string;
+  prUrl: string;
+  number: number;
+  ready: boolean;
+}
+
+export interface WorktreePoolConfig {
+  sessionDir: string;
+  repoDir: string;
+  isSameRepo: boolean;
+}
+
+export interface WorktreePool {
+  get(prUrl: string): PoolEntry | undefined;
+  has(prUrl: string): boolean;
+  resolve(prUrl: string): string | undefined;
+  ensure(runtime: ReviewGitRuntime, metadata: PRMetadata): Promise<PoolEntry>;
+  entries(): IterableIterator<PoolEntry>;
+  cleanup(runtime: ReviewGitRuntime): Promise<void>;
+}
+
+export function createWorktreePool(config: WorktreePoolConfig, initial?: PoolEntry): WorktreePool {
+  const pool = new Map<string, PoolEntry>();
+  const pending = new Map<string, Promise<PoolEntry>>();
+  if (initial) pool.set(initial.prUrl, initial);
+
+  return {
+    get(prUrl) { return pool.get(prUrl); },
+    has(prUrl) { return pool.has(prUrl); },
+    resolve(prUrl) {
+      const entry = pool.get(prUrl);
+      return entry?.ready ? entry.path : undefined;
+    },
+
+    async ensure(runtime, metadata) {
+      const existing = pool.get(metadata.url);
+      if (existing?.ready) return existing;
+
+      const inflight = pending.get(metadata.url);
+      if (inflight) return inflight;
+
+      if (!config.isSameRepo) {
+        throw new Error("Cross-repo pool cannot create worktrees for other PRs");
+      }
+
+      const promise = (async (): Promise<PoolEntry> => {
+        const number = metadata.platform === "github" ? metadata.number : metadata.iid;
+        const worktreePath = join(config.sessionDir, "pool", `pr-${number}`);
+        const refSpec = metadata.platform === "github"
+          ? `refs/pull/${number}/head`
+          : `refs/merge-requests/${number}/head`;
+
+        await fetchRef(runtime, metadata.baseBranch, { cwd: config.repoDir });
+        await ensureObjectAvailable(runtime, metadata.baseSha, { cwd: config.repoDir });
+        await fetchRef(runtime, refSpec, { cwd: config.repoDir });
+
+        await createWorktree(runtime, {
+          ref: "FETCH_HEAD",
+          path: worktreePath,
+          detach: true,
+          cwd: config.repoDir,
+        });
+
+        const entry: PoolEntry = { path: worktreePath, prUrl: metadata.url, number, ready: true };
+        pool.set(metadata.url, entry);
+        return entry;
+      })();
+
+      pending.set(metadata.url, promise);
+      try {
+        return await promise;
+      } finally {
+        pending.delete(metadata.url);
+      }
+    },
+
+    entries() { return pool.values(); },
+
+    async cleanup(runtime) {
+      for (const entry of pool.values()) {
+        await removeWorktree(runtime, entry.path, { force: true, cwd: config.repoDir });
+      }
+      pool.clear();
+    },
+  };
+}

package/3p/pi-plannotator/packages/shared/worktree.ts

@@ -0,0 +1,119 @@
+/**
+ * Worktree — runtime-agnostic git worktree primitives.
+ *
+ * Uses ReviewGitRuntime so both Bun and Node runtimes can use the same logic.
+ * Lives in packages/shared/ and gets vendored to Pi via vendor.sh.
+ *
+ * Designed as composable primitives, not tied to any specific use case.
+ * PR local checkout, agent sandboxes, parallel sessions — all compose from these.
+ */
+
+import type { ReviewGitRuntime } from "./review-core";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CreateWorktreeOptions {
+  /** Git ref to check out (branch name, SHA, FETCH_HEAD, etc.) */
+  ref: string;
+  /** Absolute path where the worktree will be created. */
+  path: string;
+  /** Create in detached HEAD mode (no branch). Default: false. */
+  detach?: boolean;
+  /** CWD of the source repository. Defaults to process.cwd(). */
+  cwd?: string;
+}
+
+export interface RemoveWorktreeOptions {
+  /** Force removal even if the worktree has modifications. Default: false. */
+  force?: boolean;
+  /** CWD of the source repository. Required if the worktree was created from a different cwd. */
+  cwd?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a ref from origin.
+ * Runs: `git fetch origin <ref>`
+ * Throws on failure.
+ */
+export async function fetchRef(
+  runtime: ReviewGitRuntime,
+  ref: string,
+  options?: { cwd?: string },
+): Promise<void> {
+  const result = await runtime.runGit(["fetch", "origin", "--", ref], { cwd: options?.cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git fetch origin ${ref} failed: ${result.stderr.trim() || `exit code ${result.exitCode}`}`);
+  }
+}
+
+/**
+ * Ensure a git object (commit SHA) is available locally.
+ * Checks with `git cat-file -t`, fetches from origin if missing.
+ * Returns true if the object is available after the attempt.
+ */
+export async function ensureObjectAvailable(
+  runtime: ReviewGitRuntime,
+  sha: string,
+  options?: { cwd?: string },
+): Promise<boolean> {
+  const check = await runtime.runGit(["cat-file", "-t", sha], { cwd: options?.cwd });
+  if (check.exitCode === 0) return true;
+
+  // Object missing locally — try fetching it
+  const fetch = await runtime.runGit(["fetch", "origin", "--", sha], { cwd: options?.cwd });
+  if (fetch.exitCode !== 0) return false;
+
+  // Verify it's now available
+  const recheck = await runtime.runGit(["cat-file", "-t", sha], { cwd: options?.cwd });
+  return recheck.exitCode === 0;
+}
+
+/**
+ * Create a git worktree.
+ * Runs: `git worktree add [--detach] <path> <ref>`
+ * Throws on failure with a descriptive error.
+ */
+export async function createWorktree(
+  runtime: ReviewGitRuntime,
+  options: CreateWorktreeOptions,
+): Promise<{ worktreePath: string }> {
+  const args = ["worktree", "add"];
+  if (options.detach) args.push("--detach");
+  args.push(options.path, options.ref);
+
+  const result = await runtime.runGit(args, { cwd: options.cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git worktree add failed: ${result.stderr.trim() || `exit code ${result.exitCode}`}`);
+  }
+
+  return { worktreePath: options.path };
+}
+
+/**
+ * Remove a git worktree. Best-effort — logs errors but does not throw.
+ * Runs: `git worktree remove [--force] <path>`
+ */
+export async function removeWorktree(
+  runtime: ReviewGitRuntime,
+  worktreePath: string,
+  options?: RemoveWorktreeOptions,
+): Promise<void> {
+  const args = ["worktree", "remove"];
+  if (options?.force) args.push("--force");
+  args.push(worktreePath);
+
+  try {
+    const result = await runtime.runGit(args, { cwd: options?.cwd });
+    if (result.exitCode !== 0) {
+      console.error(`Warning: git worktree remove failed for ${worktreePath}: ${result.stderr.trim()}`);
+    }
+  } catch (err) {
+    console.error(`Warning: worktree cleanup error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/3p/pi-subagents/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tintinweb/pi-subagents",
+  "version": "0.5.2",
+  "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
+  "author": "tintinweb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tintinweb/pi-subagents.git"
+  },
+  "homepage": "https://github.com/tintinweb/pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/tintinweb/pi-subagents/issues"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous"
+  ],
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.75.5",
+    "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@earendil-works/pi-tui": "^0.75.5",
+    "@sinclair/typebox": "latest"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --fix src/ test/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.5",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "video": "https://github.com/tintinweb/pi-subagents/raw/master/media/demo.mp4",
+    "image": "https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png"
+  }
+}

package/3p/pi-subagents/src/agent-manager.ts

@@ -0,0 +1,413 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+
+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 { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.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: SubagentType;
+  prompt: string;
+  options: SpawnOptions;
+}
+
+interface SpawnOptions {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+  isolation?: IsolationMode;
+  /** Called on tool start/end with activity info (for streaming progress to UI). */
+  onToolActivity?: (activity: ToolActivity) => void;
+  /** Called on streaming text deltas from the assistant response. */
+  onTextDelta?: (delta: string, fullText: string) => void;
+  /** Called when the agent session is created (for accessing session stats). */
+  onSessionCreated?: (session: AgentSession) => void;
+  /** Called at the end of each agentic turn with the cumulative count. */
+  onTurnEnd?: (turnCount: number) => void;
+  validateCompletion?: () => string | undefined;
+  maxValidationRetries?: number;
+}
+
+export class AgentManager {
+  private agents = new Map<string, AgentRecord>();
+  private cleanupInterval: ReturnType<typeof setInterval>;
+  private onComplete?: OnAgentComplete;
+  private onStart?: OnAgentStart;
+  private maxConcurrent: number;
+
+  /** 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;
+    // Cleanup completed agents after 10 minutes (but keep sessions for resume)
+    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+  }
+
+  /** Update the max concurrent background agents limit. */
+  setMaxConcurrent(n: number) {
+    this.maxConcurrent = Math.max(1, n);
+    // Start queued agents if the new limit allows
+    this.drainQueue();
+  }
+
+  getMaxConcurrent(): number {
+    return this.maxConcurrent;
+  }
+
+  /**
+   * Spawn an agent and return its ID immediately (for background use).
+   * If the concurrency limit is reached, the agent is queued.
+   */
+  spawn(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: SubagentType,
+    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,
+    };
+    this.agents.set(id, record);
+
+    const args: SpawnArgs = { pi, ctx, type, prompt, options };
+
+    if (options.isBackground && this.runningBackground >= this.maxConcurrent) {
+      // Queue it — will be started when a running agent completes
+      this.queue.push({ id, args });
+      return id;
+    }
+
+    this.startAgent(id, record, args);
+    return id;
+  }
+
+  /** Actually start an agent (called immediately or from queue drain). */
+  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);
+
+    // Worktree isolation: create a temporary git worktree if requested
+    let worktreeCwd: string | undefined;
+    let worktreeWarning = "";
+    if (options.isolation === "worktree") {
+      const wt = createWorktree(ctx.cwd, id);
+      if (wt) {
+        record.worktree = wt;
+        worktreeCwd = wt.path;
+      } else {
+        worktreeWarning = "\n\n[WARNING: Worktree isolation was requested but failed (not a git repo, or no commits yet). Running in the main working directory instead.]";
+      }
+    }
+
+    // Prepend worktree warning to prompt if isolation failed
+    const effectivePrompt = worktreeWarning ? worktreeWarning + "\n\n" + prompt : prompt;
+
+    const promise = runAgent(ctx, type, effectivePrompt, {
+      pi,
+      model: options.model,
+      maxTurns: options.maxTurns,
+      isolated: options.isolated,
+      inheritContext: options.inheritContext,
+      thinkingLevel: options.thinkingLevel,
+      cwd: worktreeCwd,
+      signal: record.abortController!.signal,
+      onToolActivity: (activity) => {
+        if (activity.type === "end") record.toolUses++;
+        options.onToolActivity?.(activity);
+      },
+      onTurnEnd: options.onTurnEnd,
+      onTextDelta: options.onTextDelta,
+      validateCompletion: options.validateCompletion,
+      maxValidationRetries: options.maxValidationRetries,
+      onSessionCreated: (session) => {
+        record.session = session;
+        // Flush any steers that arrived before the session was ready
+        if (record.pendingSteers?.length) {
+          for (const msg of record.pendingSteers) {
+            session.steer(msg).catch(() => {});
+          }
+          record.pendingSteers = undefined;
+        }
+        options.onSessionCreated?.(session);
+      },
+    })
+      .then(({ responseText, session, aborted, steered }) => {
+        // Don't overwrite status if externally stopped via abort()
+        if (record.status !== "stopped") {
+          record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+        }
+        record.result = responseText;
+        record.session = session;
+        record.completedAt ??= Date.now();
+
+        // Final flush of streaming output file
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
+        // Clean up worktree if used
+        if (record.worktree) {
+          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          record.worktreeResult = wtResult;
+          if (wtResult.hasChanges && wtResult.branch) {
+            record.result = (record.result ?? "") +
+              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+          }
+        }
+
+        if (options.isBackground) {
+          this.runningBackground--;
+          this.onComplete?.(record);
+          this.drainQueue();
+        }
+        return responseText;
+      })
+      .catch((err) => {
+        // Don't overwrite status if externally stopped via abort()
+        if (record.status !== "stopped") {
+          record.status = "error";
+        }
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt ??= Date.now();
+
+        // Final flush of streaming output file on error
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
+        // Best-effort worktree cleanup on error
+        if (record.worktree) {
+          try {
+            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            record.worktreeResult = wtResult;
+          } catch { /* ignore cleanup errors */ }
+        }
+
+        if (options.isBackground) {
+          this.runningBackground--;
+          this.onComplete?.(record);
+          this.drainQueue();
+        }
+        return "";
+      });
+
+    record.promise = promise;
+  }
+
+  /** Start queued agents up to the 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 an agent and wait for completion (foreground use).
+   * Foreground agents bypass the concurrency queue.
+   */
+  async spawnAndWait(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: SubagentType,
+    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;
+  }
+
+  /**
+   * Resume an existing agent session with a new prompt.
+   */
+  async resume(
+    id: string,
+    prompt: string,
+    signal?: AbortSignal,
+  ): Promise<AgentRecord | undefined> {
+    const record = this.agents.get(id);
+    if (!record?.session) return undefined;
+
+    record.status = "running";
+    record.startedAt = Date.now();
+    record.completedAt = undefined;
+    record.result = undefined;
+    record.error = undefined;
+
+    try {
+      const responseText = await resumeAgent(record.session, prompt, {
+        onToolActivity: (activity) => {
+          if (activity.type === "end") record.toolUses++;
+        },
+        signal,
+      });
+      record.status = "completed";
+      record.result = responseText;
+      record.completedAt = Date.now();
+    } catch (err) {
+      record.status = "error";
+      record.error = err instanceof Error ? err.message : String(err);
+      record.completedAt = Date.now();
+    }
+
+    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;
+
+    // Remove from queue if queued
+    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();
+    return true;
+  }
+
+  /** Dispose a record's session and remove it from the map. */
+  private removeRecord(id: string, record: AgentRecord): void {
+    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;
+      this.removeRecord(id, record);
+    }
+  }
+
+  /**
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   */
+  clearCompleted(): void {
+    for (const [id, record] of this.agents) {
+      if (record.status === "running" || record.status === "queued") continue;
+      this.removeRecord(id, record);
+    }
+  }
+
+  /** Whether any agents are still running or queued. */
+  hasRunning(): boolean {
+    return [...this.agents.values()].some(
+      r => r.status === "running" || r.status === "queued",
+    );
+  }
+
+  /** Abort all running and queued agents immediately. */
+  abortAll(): number {
+    let count = 0;
+    // Clear queued agents first
+    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 = [];
+    // Abort running agents
+    for (const record of this.agents.values()) {
+      if (record.status === "running") {
+        record.abortController?.abort();
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /** Wait for all running and queued agents to complete (including queued ones). */
+  async waitForAll(): Promise<void> {
+    // Loop because drainQueue respects the concurrency limit — as running
+    // agents finish they start queued ones, which need awaiting too.
+    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);
+    }
+  }
+
+  dispose() {
+    clearInterval(this.cleanupInterval);
+    // Clear queue
+    this.queue = [];
+    for (const record of this.agents.values()) {
+      record.session?.dispose();
+    }
+    this.agents.clear();
+    // Prune any orphaned git worktrees (crash recovery)
+    try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+  }
+}