@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.5

package/src/worktree.ts

@@ -0,0 +1,230 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ *
+ * Every git call goes through `pi.exec` (async) rather than `execFileSync`: a
+ * worktree copy can take seconds, and a session that spawns several isolated
+ * agents at once would otherwise serialize them all on the TUI's event loop.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export interface WorktreeInfo {
+  /** Absolute path to the worktree directory (the copied repo's root). */
+  path: string;
+  /** Branch name created for this worktree (if changes exist). */
+  branch: string;
+  /** Commit SHA that the worktree was created from. */
+  baseSha: string;
+  /** Resolved toplevel of the repo the worktree was created from; the result branch lands here. */
+  repoRoot: string;
+  /**
+   * Where the agent should work inside the worktree: the equivalent of the
+   * cwd the worktree was created from. Equals `path` when that cwd was the
+   * repo root; points at the copied subdirectory when it was deeper (e.g. a
+   * monorepo package), so the requested scoping survives isolation.
+   */
+  workPath: string;
+}
+
+/**
+ * Project-wide switch for worktree isolation (`worktreeIsolation` in
+ * subagents.json). Default `true` — unchanged behaviour.
+ *
+ * The `"off"` isolation value gives a model a legal way to decline a worktree,
+ * but it still depends on the model choosing it. This is the deterministic half
+ * of the same fix: on a large repo where every worktree costs real time and
+ * disk (#184), turning it off means no caller can create one, whatever it
+ * passes.
+ */
+let worktreeIsolationEnabled = true;
+
+export function setWorktreeIsolationEnabled(enabled: boolean): void {
+  worktreeIsolationEnabled = enabled;
+}
+
+export function isWorktreeIsolationEnabled(): boolean {
+  return worktreeIsolationEnabled;
+}
+
+export interface WorktreeCleanupResult {
+  /** Whether changes were found in the worktree. */
+  hasChanges: boolean;
+  /** Branch name if changes were committed. */
+  branch?: string;
+  /** Worktree path if it was kept. */
+  path?: string;
+}
+
+/**
+ * Run git and return its trimmed stdout, throwing on failure so callers keep
+ * the try/catch control flow `execFileSync` gave them.
+ *
+ * `pi.exec` never rejects — it reports failure in the result — and a command
+ * killed by its timeout comes back as `killed` with an exit code of 0, so both
+ * have to be checked to reproduce `execFileSync`'s "throws on anything but a
+ * clean exit".
+ */
+async function git(pi: ExtensionAPI, cwd: string, args: string[], timeout: number): Promise<string> {
+  const result = await pi.exec("git", args, { cwd, timeout });
+  if (result.killed) throw new GitTimeoutError(`\`git ${args.join(" ")}\` timed out after ${timeout}ms in ${cwd}`);
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || `git ${args.join(" ")} failed (exit ${result.code})`);
+  }
+  return result.stdout.trim();
+}
+
+/** A git call killed by its timeout — reported as-is, never as a repo-state cause. */
+class GitTimeoutError extends Error {}
+
+/**
+ * Why `createWorktree` could not isolate an agent. The message names the
+ * directory it tried and the specific cause, so a caller can tell "wrong
+ * directory" from "repo with no commits" from a git failure.
+ */
+export class WorktreeError extends Error {}
+
+/** Run one git step, rethrowing a failure as a `WorktreeError` whose message is `cause(detail)`. */
+async function step(run: Promise<string>, cause: (detail: string) => string): Promise<string> {
+  try {
+    return await run;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new WorktreeError(err instanceof GitTimeoutError ? detail : cause(detail));
+  }
+}
+
+/**
+ * Create a temporary git worktree for an agent, from the repo containing `cwd`
+ * (which may be any directory inside it, not just the toplevel).
+ *
+ * @throws WorktreeError — `cwd` is not inside a git work tree, the repo has no
+ * commits yet, `git worktree add` failed, or a git call timed out.
+ */
+export async function createWorktree(pi: ExtensionAPI, cwd: string, agentId: string): Promise<WorktreeInfo> {
+  const inside = await step(
+    git(pi, cwd, ["rev-parse", "--is-inside-work-tree"], 5000),
+    detail => `${cwd} is not inside a git repository (${detail})`,
+  );
+  // "false" with a clean exit: inside a `.git` dir or a bare repo.
+  if (inside !== "true") throw new WorktreeError(`${cwd} is inside a git directory but not a work tree`);
+  // realpath both sides — git emits resolved paths while cwd may arrive
+  // through a symlink (macOS /tmp).
+  const repoRoot = realpathSync(await step(
+    git(pi, cwd, ["rev-parse", "--show-toplevel"], 5000),
+    detail => `${cwd} has no git work tree toplevel (${detail})`,
+  ));
+  const baseSha = await step(
+    git(pi, cwd, ["rev-parse", "--verify", "HEAD"], 5000),
+    () => `${repoRoot} has no commits yet; commit at least once`,
+  );
+  // Where cwd sits inside the repo ("" at the root): the agent must work at
+  // the same subdirectory inside the copy, or a monorepo-package cwd would
+  // silently widen to the whole repo.
+  const subdir = relative(repoRoot, realpathSync(cwd));
+
+  const branch = `pi-agent-${agentId}`;
+  const suffix = randomUUID().slice(0, 8);
+  const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
+
+  // Create detached worktree at HEAD
+  await step(
+    git(pi, cwd, ["worktree", "add", "--detach", worktreePath, "HEAD"], 30000),
+    detail => `\`git worktree add\` failed in ${repoRoot}: ${detail}`,
+  );
+  return { path: worktreePath, branch, baseSha, repoRoot, workPath: subdir ? join(worktreePath, subdir) : worktreePath };
+}
+
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export async function cleanupWorktree(
+  pi: ExtensionAPI,
+  cwd: string,
+  worktree: WorktreeInfo,
+  agentDescription: string,
+): Promise<WorktreeCleanupResult> {
+  if (!existsSync(worktree.path)) {
+    return { hasChanges: false };
+  }
+
+  try {
+    // Check for uncommitted changes in the worktree
+    const status = await git(pi, worktree.path, ["status", "--porcelain"], 10000);
+
+    if (status) {
+      // Changes exist — stage, commit, and create a branch
+      await git(pi, worktree.path, ["add", "-A"], 10000);
+      // Truncate description for commit message (no shell sanitization needed — pi.exec uses argv)
+      const safeDesc = agentDescription.slice(0, 200);
+      const commitMsg = `pi-agent: ${safeDesc}`;
+      await git(pi, worktree.path, ["commit", "--no-verify", "-m", commitMsg], 10000);
+    } else {
+      const currentSha = await git(pi, worktree.path, ["rev-parse", "HEAD"], 5000);
+
+      if (currentSha === worktree.baseSha) {
+        // No changes — remove worktree
+        await removeWorktree(pi, cwd, worktree.path);
+        return { hasChanges: false };
+      }
+    }
+
+    // Create a branch pointing to the worktree's HEAD.
+    // If the branch already exists, append a suffix to avoid overwriting previous work.
+    let branchName = worktree.branch;
+    try {
+      await git(pi, worktree.path, ["branch", branchName], 5000);
+    } catch {
+      // Branch already exists — use a unique suffix
+      branchName = `${worktree.branch}-${Date.now()}`;
+      await git(pi, worktree.path, ["branch", branchName], 5000);
+    }
+    // Update branch name in worktree info for the caller
+    worktree.branch = branchName;
+
+    // Remove the worktree (branch persists in main repo)
+    await removeWorktree(pi, cwd, worktree.path);
+
+    return {
+      hasChanges: true,
+      branch: worktree.branch,
+      path: worktree.path,
+    };
+  } catch {
+    // Best effort cleanup on error
+    try { await removeWorktree(pi, cwd, worktree.path); } catch { /* ignore */ }
+    return { hasChanges: false };
+  }
+}
+
+/**
+ * Force-remove a worktree.
+ */
+async function removeWorktree(pi: ExtensionAPI, cwd: string, worktreePath: string): Promise<void> {
+  try {
+    await git(pi, cwd, ["worktree", "remove", "--force", worktreePath], 10000);
+  } catch {
+    // If git worktree remove fails, try pruning
+    try {
+      await git(pi, cwd, ["worktree", "prune"], 5000);
+    } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export async function pruneWorktrees(pi: ExtensionAPI, cwd: string): Promise<void> {
+  try {
+    await git(pi, cwd, ["worktree", "prune"], 5000);
+  } catch { /* ignore */ }
+}

package/src/xml.ts

@@ -0,0 +1,13 @@
+/**
+ * xml.ts — escaping for the `<task-notification>` payloads.
+ *
+ * A module of its own because both notification builders need it and they sit
+ * on opposite sides of a dependency edge: the agent one lives in `index.ts`,
+ * which imports `workflow/task.ts`, so the workflow one cannot reach back for
+ * it without a cycle.
+ */
+
+/** Escape XML special characters to prevent injection in structured notifications. */
+export function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}