@quintinshaw/pi-dynamic-workflows 1.4.0 → 1.5.0

package/README.md

@@ -99,6 +99,7 @@ return { inventory, summary }
 | `phase` | string | Override the current phase for this agent |
 | `schema` | object | JSON Schema for structured output |
 | `model` | string | Run this agent on a specific model — `provider/modelId` or a bare `modelId` |
+| `isolation` | `"worktree"` | Run this agent in its own throwaway git worktree (parallel edits without conflict) |
 | `timeoutMs` | number | Override the default 5-minute agent timeout |
 
 Models can also be set per phase via `meta.phases[].model`. Precedence is `opts.model` > phase model > session default; an unknown model logs a warning and falls back to the default.
@@ -135,6 +136,7 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 - **Real per-agent / per-phase model routing** — `opts.model` and `meta.phases[].model` actually select the model (resolved against your authed model registry), with graceful fallback
 - **`/workflows` command** — list, inspect, stop, pause, **resume**, and remove background runs; runs started with `background: true` are reachable from the command
 - **Resume** — each agent result is journaled by a deterministic call index; resuming replays the unchanged prefix from cache (no re-run, no tokens) and runs only new or edited calls live
+- **Worktree isolation** — `isolation: "worktree"` runs an agent in its own git worktree on a throwaway branch, so parallel agents can edit the same files without conflict; the worktree is torn down after (results are not auto-merged), and it falls back to a logged no-op outside a git repo
 - **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
 - **Live progress + token/cost display**, `Esc` to abort
 - **Log persistence** to `.pi/workflows/runs/`
@@ -143,8 +145,9 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 
 Tracked toward closer parity with Claude Code dynamic workflows:
 
-- **Worktree isolation** for parallel edits, and **bundled `/deep-research`**
+- **Bundled `/deep-research`** and `/adversarial-review` workflows
 - **Saved workflows** as `/<name>` slash commands
+- **Nested `workflow()`** to compose saved workflows inline
 
 ## How it works
 

package/dist/agent.d.ts

@@ -38,6 +38,8 @@ export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefi
     model?: string;
     /** Called with the resolved model id once known (for display/telemetry). */
     onModelResolved?: (modelId: string) => void;
+    /** Run this agent in a different working directory (e.g. an isolated worktree). */
+    cwd?: string;
 }
 export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema ? Static<TSchemaDef> : string;
 export declare class WorkflowAgent {

package/dist/agent.js

@@ -39,7 +39,11 @@ export class WorkflowAgent {
     }
     async run(prompt, options = {}) {
         const capture = { called: false, value: undefined };
-        const customTools = [...this.baseTools, ...(options.tools ?? [])];
+        // Per-call cwd (e.g. a worktree) needs coding tools bound to that directory,
+        // since tools capture their cwd at construction and can't be relocated.
+        const runCwd = options.cwd ?? this.cwd;
+        const baseTools = runCwd === this.cwd ? this.baseTools : createCodingTools(runCwd);
+        const customTools = [...baseTools, ...(options.tools ?? [])];
         if (options.schema) {
             customTools.push(createStructuredOutputTool({ schema: options.schema, capture }));
         }
@@ -57,7 +61,7 @@ export class WorkflowAgent {
         }
         const agentDir = getAgentDir();
         const { session } = await createAgentSession({
-            cwd: this.cwd,
+            cwd: runCwd,
             agentDir,
             sessionManager: SessionManager.inMemory(),
             // Use real SettingsManager to inherit user's default provider/model settings.

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export type { PersistedRunState, RunPersistence, RunStatus } from "./run-persist
 export { createRunPersistence, generateRunId } from "./run-persistence.js";
 export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
 export { createStructuredOutputTool } from "./structured-output.js";
-export type { AgentOptions, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
+export type { AgentOptions, JournalEntry, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
@@ -27,3 +27,5 @@ export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
 export { createWorkflowTool } from "./workflow-tool.js";
+export type { Worktree } from "./worktree.js";
+export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/index.js

@@ -14,3 +14,4 @@ export { registerWorkflowCommands } from "./workflow-commands.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowTool } from "./workflow-tool.js";
+export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/workflow.d.ts

@@ -51,6 +51,7 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
         phase?: string;
         result: unknown;
         tokens?: number;
+        worktree?: string;
     }) => void;
     onTokenUsage?: (usage: {
         input: number;

package/dist/workflow.js

@@ -6,6 +6,7 @@ import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from ".
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import { createWorkflowLogger } from "./logger.js";
 import { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
+import { createWorktree, removeWorktree } from "./worktree.js";
 const DETERMINISM_BLOCKLIST = /\bDate\s*\.\s*now\b|\bMath\s*\.\s*random\b|\bnew\s+Date\s*\(\s*\)/;
 export async function runWorkflow(script, options = {}) {
     const started = Date.now();
@@ -15,6 +16,7 @@ export async function runWorkflow(script, options = {}) {
     const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
     const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
     const runId = options.runId ?? `run-${started.toString(36)}`;
+    const baseCwd = options.cwd ?? process.cwd();
     // Initialize logger
     const logger = createWorkflowLogger({
         runId,
@@ -88,6 +90,14 @@ export async function runWorkflow(script, options = {}) {
             const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
             const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
             options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
+            // Optional per-agent worktree isolation (deterministic name -> stable resume keys).
+            let worktree;
+            if (agentOptions.isolation === "worktree") {
+                worktree = await createWorktree(baseCwd, `${runId}-${callIndex}-${label}`);
+                if (!worktree.isolated)
+                    log(`isolation ignored for "${label}" (${worktree.reason})`);
+            }
+            const runCwd = worktree?.isolated ? worktree.cwd : undefined;
             // Captured from the subagent's real session usage; falls back to an
             // estimate when the provider reports no usage (total === 0).
             let usage;
@@ -111,6 +121,7 @@ export async function runWorkflow(script, options = {}) {
                     signal: options.signal,
                     instructions: buildAgentInstructions(assignedPhase, agentOptions),
                     model: modelSpec,
+                    cwd: runCwd,
                     onUsage: (u) => {
                         usage = u;
                     },
@@ -118,7 +129,7 @@ export async function runWorkflow(script, options = {}) {
                 throwIfAborted();
                 const tokens = recordTokens(result);
                 options.onAgentJournal?.({ index: callIndex, hash: callHash, result });
-                options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
+                options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens, worktree: runCwd });
                 return result;
             }
             catch (error) {
@@ -127,13 +138,18 @@ export async function runWorkflow(script, options = {}) {
                 const workflowError = wrapError(error, { agentLabel: label });
                 logger.error(`agent ${label} failed: ${workflowError.message}`);
                 const tokens = recordTokens(null);
-                options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens });
+                options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens, worktree: runCwd });
                 // Return null for recoverable errors
                 if (workflowError.recoverable) {
                     return null;
                 }
                 throw workflowError;
             }
+            finally {
+                // Always tear down the worktree, even on timeout/abort.
+                if (worktree?.isolated)
+                    await removeWorktree(worktree);
+            }
         });
     };
     const parallel = async (thunks) => {

package/dist/worktree.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-agent git worktree isolation. When an agent requests `isolation: "worktree"`,
+ * it runs in a throwaway worktree on its own branch so parallel agents can edit the
+ * same files without conflict. Results are NOT auto-merged — the path is surfaced for
+ * the caller to inspect. Falls back to a logged no-op when isolation isn't possible.
+ */
+export interface Worktree {
+    /** True when a real worktree was created; false means "ran in the shared tree". */
+    isolated: boolean;
+    /** cwd the agent should run in (worktree path when isolated, else the base cwd). */
+    cwd: string;
+    branch?: string;
+    /** Repo root the worktree was added to (for teardown). */
+    repoRoot?: string;
+    /** Why isolation was skipped, when isolated === false. */
+    reason?: string;
+}
+/**
+ * Create an isolated worktree under `<repoRoot>/.pi/worktrees/<name>` on branch
+ * `pi/wf/<name>`. The `name` must be deterministic (derived from runId + call index,
+ * never wall-clock) so resume keys stay stable. Returns a no-op Worktree on any failure.
+ */
+export declare function createWorktree(baseCwd: string, name: string): Promise<Worktree>;
+/** Remove a worktree and its branch. Best-effort; safe to call on a no-op Worktree. */
+export declare function removeWorktree(wt: Worktree): Promise<void>;

package/dist/worktree.js

@@ -0,0 +1,61 @@
+/**
+ * Per-agent git worktree isolation. When an agent requests `isolation: "worktree"`,
+ * it runs in a throwaway worktree on its own branch so parallel agents can edit the
+ * same files without conflict. Results are NOT auto-merged — the path is surfaced for
+ * the caller to inspect. Falls back to a logged no-op when isolation isn't possible.
+ */
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+function slug(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 32) || "agent");
+}
+/**
+ * Create an isolated worktree under `<repoRoot>/.pi/worktrees/<name>` on branch
+ * `pi/wf/<name>`. The `name` must be deterministic (derived from runId + call index,
+ * never wall-clock) so resume keys stay stable. Returns a no-op Worktree on any failure.
+ */
+export async function createWorktree(baseCwd, name) {
+    const id = slug(name);
+    let repoRoot;
+    try {
+        const { stdout } = await exec("git", ["-C", baseCwd, "rev-parse", "--show-toplevel"]);
+        repoRoot = stdout.trim();
+    }
+    catch {
+        return { isolated: false, cwd: baseCwd, reason: "not a git repository" };
+    }
+    const path = join(repoRoot, ".pi", "worktrees", id);
+    const branch = `pi/wf/${id}`;
+    try {
+        await exec("git", ["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+        return { isolated: true, cwd: path, branch, repoRoot };
+    }
+    catch (error) {
+        return { isolated: false, cwd: baseCwd, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Remove a worktree and its branch. Best-effort; safe to call on a no-op Worktree. */
+export async function removeWorktree(wt) {
+    if (!wt.isolated || !wt.repoRoot)
+        return;
+    try {
+        await exec("git", ["-C", wt.repoRoot, "worktree", "remove", "--force", wt.cwd]);
+    }
+    catch {
+        // already gone / locked — fall through
+    }
+    if (wt.branch) {
+        try {
+            await exec("git", ["-C", wt.repoRoot, "branch", "-D", wt.branch]);
+        }
+        catch {
+            // branch already deleted
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
   "type": "module",
   "main": "./dist/index.js",

package/src/agent.ts

@@ -54,6 +54,8 @@ export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefi
   model?: string;
   /** Called with the resolved model id once known (for display/telemetry). */
   onModelResolved?: (modelId: string) => void;
+  /** Run this agent in a different working directory (e.g. an isolated worktree). */
+  cwd?: string;
 }
 
 export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema
@@ -105,7 +107,11 @@ export class WorkflowAgent {
     options: AgentRunOptions<TSchemaDef> = {},
   ): Promise<AgentRunResult<TSchemaDef>> {
     const capture: StructuredOutputCapture<any> = { called: false, value: undefined };
-    const customTools: ToolDefinition[] = [...this.baseTools, ...(options.tools ?? [])];
+    // Per-call cwd (e.g. a worktree) needs coding tools bound to that directory,
+    // since tools capture their cwd at construction and can't be relocated.
+    const runCwd = options.cwd ?? this.cwd;
+    const baseTools = runCwd === this.cwd ? this.baseTools : createCodingTools(runCwd);
+    const customTools: ToolDefinition[] = [...baseTools, ...(options.tools ?? [])];
 
     if (options.schema) {
       customTools.push(createStructuredOutputTool({ schema: options.schema, capture }) as unknown as ToolDefinition);
@@ -125,7 +131,7 @@ export class WorkflowAgent {
 
     const agentDir = getAgentDir();
     const { session } = await createAgentSession({
-      cwd: this.cwd,
+      cwd: runCwd,
       agentDir,
       sessionManager: SessionManager.inMemory(),
       // Use real SettingsManager to inherit user's default provider/model settings.

package/src/index.ts

@@ -41,6 +41,7 @@ export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./str
 export { createStructuredOutputTool } from "./structured-output.js";
 export type {
   AgentOptions,
+  JournalEntry,
   WorkflowMeta,
   WorkflowMetaPhase,
   WorkflowRunOptions,
@@ -54,3 +55,5 @@ export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
 export { createWorkflowTool } from "./workflow-tool.js";
+export type { Worktree } from "./worktree.js";
+export { createWorktree, removeWorktree } from "./worktree.js";

package/src/workflow.ts

@@ -9,6 +9,7 @@ import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from ".
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import { createWorkflowLogger } from "./logger.js";
 import { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
+import { createWorktree, removeWorktree, type Worktree } from "./worktree.js";
 
 export interface WorkflowMetaPhase {
   title: string;
@@ -54,7 +55,7 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
   onAgentStart?: (event: { label: string; phase?: string; prompt: string; model?: string }) => void;
-  onAgentEnd?: (event: { label: string; phase?: string; result: unknown; tokens?: number }) => void;
+  onAgentEnd?: (event: { label: string; phase?: string; result: unknown; tokens?: number; worktree?: string }) => void;
   onTokenUsage?: (usage: { input: number; output: number; total: number; cost: number }) => void;
 }
 
@@ -116,6 +117,7 @@ export async function runWorkflow<T = unknown>(
   const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
   const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
   const runId = options.runId ?? `run-${started.toString(36)}`;
+  const baseCwd = options.cwd ?? process.cwd();
 
   // Initialize logger
   const logger = createWorkflowLogger({
@@ -211,6 +213,14 @@ export async function runWorkflow<T = unknown>(
 
       options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
 
+      // Optional per-agent worktree isolation (deterministic name -> stable resume keys).
+      let worktree: Worktree | undefined;
+      if (agentOptions.isolation === "worktree") {
+        worktree = await createWorktree(baseCwd, `${runId}-${callIndex}-${label}`);
+        if (!worktree.isolated) log(`isolation ignored for "${label}" (${worktree.reason})`);
+      }
+      const runCwd = worktree?.isolated ? worktree.cwd : undefined;
+
       // Captured from the subagent's real session usage; falls back to an
       // estimate when the provider reports no usage (total === 0).
       let usage: AgentUsage | undefined;
@@ -237,6 +247,7 @@ export async function runWorkflow<T = unknown>(
             signal: options.signal,
             instructions: buildAgentInstructions(assignedPhase, agentOptions),
             model: modelSpec,
+            cwd: runCwd,
             onUsage: (u: AgentUsage) => {
               usage = u;
             },
@@ -249,7 +260,7 @@ export async function runWorkflow<T = unknown>(
 
         const tokens = recordTokens(result);
         options.onAgentJournal?.({ index: callIndex, hash: callHash, result });
-        options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
+        options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens, worktree: runCwd });
         return result;
       } catch (error) {
         if (options.signal?.aborted) throw error;
@@ -257,13 +268,16 @@ export async function runWorkflow<T = unknown>(
         const workflowError = wrapError(error, { agentLabel: label });
         logger.error(`agent ${label} failed: ${workflowError.message}`);
         const tokens = recordTokens(null);
-        options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens });
+        options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens, worktree: runCwd });
 
         // Return null for recoverable errors
         if (workflowError.recoverable) {
           return null;
         }
         throw workflowError;
+      } finally {
+        // Always tear down the worktree, even on timeout/abort.
+        if (worktree?.isolated) await removeWorktree(worktree);
       }
     });
   };

package/src/worktree.ts

@@ -0,0 +1,76 @@
+/**
+ * Per-agent git worktree isolation. When an agent requests `isolation: "worktree"`,
+ * it runs in a throwaway worktree on its own branch so parallel agents can edit the
+ * same files without conflict. Results are NOT auto-merged — the path is surfaced for
+ * the caller to inspect. Falls back to a logged no-op when isolation isn't possible.
+ */
+
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+
+export interface Worktree {
+  /** True when a real worktree was created; false means "ran in the shared tree". */
+  isolated: boolean;
+  /** cwd the agent should run in (worktree path when isolated, else the base cwd). */
+  cwd: string;
+  branch?: string;
+  /** Repo root the worktree was added to (for teardown). */
+  repoRoot?: string;
+  /** Why isolation was skipped, when isolated === false. */
+  reason?: string;
+}
+
+function slug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 32) || "agent"
+  );
+}
+
+/**
+ * Create an isolated worktree under `<repoRoot>/.pi/worktrees/<name>` on branch
+ * `pi/wf/<name>`. The `name` must be deterministic (derived from runId + call index,
+ * never wall-clock) so resume keys stay stable. Returns a no-op Worktree on any failure.
+ */
+export async function createWorktree(baseCwd: string, name: string): Promise<Worktree> {
+  const id = slug(name);
+  let repoRoot: string;
+  try {
+    const { stdout } = await exec("git", ["-C", baseCwd, "rev-parse", "--show-toplevel"]);
+    repoRoot = stdout.trim();
+  } catch {
+    return { isolated: false, cwd: baseCwd, reason: "not a git repository" };
+  }
+
+  const path = join(repoRoot, ".pi", "worktrees", id);
+  const branch = `pi/wf/${id}`;
+  try {
+    await exec("git", ["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+    return { isolated: true, cwd: path, branch, repoRoot };
+  } catch (error) {
+    return { isolated: false, cwd: baseCwd, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Remove a worktree and its branch. Best-effort; safe to call on a no-op Worktree. */
+export async function removeWorktree(wt: Worktree): Promise<void> {
+  if (!wt.isolated || !wt.repoRoot) return;
+  try {
+    await exec("git", ["-C", wt.repoRoot, "worktree", "remove", "--force", wt.cwd]);
+  } catch {
+    // already gone / locked — fall through
+  }
+  if (wt.branch) {
+    try {
+      await exec("git", ["-C", wt.repoRoot, "branch", "-D", wt.branch]);
+    } catch {
+      // branch already deleted
+    }
+  }
+}