pi-workflow-engine 0.10.0 → 0.10.2

package/.pi/extensions/pi-workflow-engine/index.ts

@@ -358,6 +358,8 @@ Use the workflow tool with a script argument, not a saved workflow name.
 The script must start with export const meta = { ... } and default-export an async workflow function.
 Use the injected Type object for schemas. Do not import anything or use dynamic import().
 Set thinkingLevel explicitly on each agent() call.
+Always pass a plain string as the first api.agent() argument; build prompts with template strings before calling agent().
+If using \`isolation: "worktree"\`, remember api.agent() returns \`{ result, patch, changed }\`; read \`.result\` for the agent answer and \`.patch\` for the diff.
 When the run is budgeted, guard expensive loops with \`while (api.budget.total && api.budget.remaining() > N) { ... }\`; api.agent() throws once the budget is spent.
 Subagents receive no skills by default. When the brief asks for a skill or a stage clearly benefits from one, pass \`skills: ["skill-name"]\` on that agent call only.
 Do not edit files unless the user explicitly requested edits.`;
@@ -566,6 +568,8 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       "Inline workflow scripts must use the injected `Type` object for schemas and must not contain imports or dynamic import().",
       "Inline scripts may compose registered workflows in-process via `api.workflow(\"<name>\", args)` (e.g. `await api.workflow(\"code-review\", \"HEAD~3\")`); it returns the sub-workflow's result and nests one level only.",
       "Subagents receive no skills by default. In inline workflows, pass `skills: [\"skill-name\"]` per `agent()` call when the user asks for a skill or a stage should use one; grant only the needed skills.",
+      "Always pass a plain string as the first `api.agent()` argument; build prompts with template strings before calling agent().",
+      "When using `isolation: \"worktree\"`, `api.agent()` returns `{ result, patch, changed }`; use `.result` for the answer and `.patch` for the isolated diff.",
       "If an inline subagent needs grep/find/code-search helpers, use `tools: [\"read\", \"bash\", \"grep\", \"find\", \"ls\"]` plus `toolHints: [\"search\"]` so installed tools such as ast-grep, mgrep, ffgrep, or fffind are discovered dynamically.",
       "`api.budget` exposes `{ total, spent(), remaining() }` (output tokens). When the run is budgeted, scale fleets from `budget.total` and guard loops with `while (budget.total && budget.remaining() > N) { await api.agent(...) }`; `api.agent()` throws once the ceiling is reached.",
       "Every workflow tool call must provide exactly one of `name` or `script`, never both.",

package/.pi/extensions/pi-workflow-engine/src/agent-runner.ts

@@ -354,6 +354,10 @@ async function recordJournalResult(rc: RunContext, label: string, key: string, v
  * no event-stream parsing is needed.
  */
 export async function runAgent(rc: RunContext, prompt: string, opts: AgentOptions = {}): Promise<unknown> {
+  if (typeof prompt !== "string") {
+    throw new Error(`agent() prompt must be a string; received ${describeAgentPrompt(prompt)}`);
+  }
+
   const label = opts.label ?? "agent";
   const phase = opts.phase ?? "Workflow";
   const tags = { label, phase };
@@ -553,6 +557,12 @@ async function isolatedResult(rc: RunContext, worktreePath: string, result: unkn
   return { result, patch: patch.patch, changed: patch.changed };
 }
 
+function describeAgentPrompt(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/.pi/extensions/pi-workflow-engine/src/worktree.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
 import { runBoundedProcess } from "./process-runner.ts";
 
 export interface WorktreeGitCommandOptions {
@@ -24,11 +25,13 @@ export interface WorktreeGitRunner {
 
 export interface WorktreeRef {
   readonly path: string;
+  readonly snapshot?: boolean;
 }
 
 export interface WorktreeAddFailure {
   readonly path: string;
   readonly error: string;
+  readonly snapshot?: boolean;
   readonly cleanup?: WorktreeGitCommandResult;
 }
 
@@ -67,6 +70,7 @@ let pathCounter = 0;
 
 export class WorktreeRegistry {
   private readonly paths = new Set<string>();
+  private readonly snapshots = new Set<string>();
   private readonly runner: WorktreeGitRunner;
   private readonly patchCapture: WorktreePatchCapture;
   private readonly timeoutMs: number;
@@ -92,6 +96,7 @@ export class WorktreeRegistry {
   async add(signal?: AbortSignal): Promise<WorktreeRef | WorktreeAddFailure> {
     const added = await addWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs });
     this.register(added.path);
+    if (added.snapshot === true) this.snapshots.add(added.path);
     if ("error" in added) {
       const cleanup = await this.remove(added.path);
       return { ...added, cleanup };
@@ -104,13 +109,16 @@ export class WorktreeRegistry {
   }
 
   async remove(path: string): Promise<WorktreeGitCommandResult> {
-    const result = await removeWorktree({ repoCwd: this.repoCwd, path, runner: this.runner, timeoutMs: this.timeoutMs }).catch((error: unknown) => ({
+    const result = await removeWorktree({ repoCwd: this.repoCwd, path, runner: this.runner, timeoutMs: this.timeoutMs, snapshot: this.snapshots.has(path) }).catch((error: unknown) => ({
       ok: false,
       stdout: "",
       stderr: "",
       error: formatError(error),
     }));
-    if (result.ok) this.paths.delete(path);
+    if (result.ok) {
+      this.paths.delete(path);
+      this.snapshots.delete(path);
+    }
     return result;
   }
 
@@ -163,8 +171,16 @@ export async function addWorktree(options: {
       timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
     })
     .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
-  if (!result.ok) return { path, error: result.error ?? (result.stderr.trim() || "git worktree add failed") };
-  return { path };
+  if (result.ok) return { path };
+
+  const message = result.error ?? (result.stderr.trim() || "git worktree add failed");
+  if (!isInvalidHeadError(message)) return { path, error: message };
+
+  const snapshotError = await createUnbornRepoSnapshot({ repoCwd: options.repoCwd, path, timeoutMs: options.timeoutMs, signal: options.signal })
+    .then(() => undefined)
+    .catch((error: unknown) => formatError(error));
+  if (snapshotError !== undefined) return { path, snapshot: true, error: `git worktree add failed (${message}); unborn-repo snapshot fallback failed: ${snapshotError}` };
+  return { path, snapshot: true };
 }
 
 export async function removeWorktree(options: {
@@ -172,7 +188,12 @@ export async function removeWorktree(options: {
   readonly path: string;
   readonly runner?: WorktreeGitRunner;
   readonly timeoutMs?: number;
+  readonly snapshot?: boolean;
 }): Promise<WorktreeGitCommandResult> {
+  if (options.snapshot === true) {
+    await rm(options.path, { recursive: true, force: true });
+    return { ok: true, stdout: "", stderr: "" };
+  }
   return await (options.runner ?? spawnGitRunner).runGit({
     cwd: options.repoCwd,
     args: ["worktree", "remove", "--force", options.path],
@@ -211,6 +232,38 @@ export async function captureWorktreePatch(options: {
   return { patch: diff.stdout, changed: diff.stdout.trim().length > 0 };
 }
 
+async function createUnbornRepoSnapshot(options: {
+  readonly repoCwd: string;
+  readonly path: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<void> {
+  const targetRoot = resolve(options.path);
+  await rm(options.path, { recursive: true, force: true });
+  await mkdir(options.path, { recursive: true });
+  await cp(options.repoCwd, options.path, {
+    recursive: true,
+    force: true,
+    filter: (source) => {
+      const resolvedSource = resolve(source);
+      if (resolvedSource === targetRoot || resolvedSource.startsWith(`${targetRoot}${sep}`)) return false;
+      return !resolvedSource.split(/[\\/]/).includes(".git");
+    },
+  });
+  await runGitCommand({ cwd: options.path, args: ["init"], signal: options.signal, timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS });
+  await runGitCommand({ cwd: options.path, args: ["add", "-A"], signal: options.signal, timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS });
+  await runGitCommand({
+    cwd: options.path,
+    args: ["-c", "user.name=pi-workflow", "-c", "user.email=pi-workflow@example.invalid", "commit", "--allow-empty", "-m", "pi workflow baseline"],
+    signal: options.signal,
+    timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+  });
+}
+
+function isInvalidHeadError(message: string): boolean {
+  return /invalid reference:\s*HEAD/i.test(message) || /ambiguous argument ['"]?HEAD/i.test(message) || /unknown revision or path.*HEAD/i.test(message);
+}
+
 export const spawnGitRunner: WorktreeGitRunner = {
   async runGit(options) {
     return await runGitCommand(options);
@@ -218,11 +271,14 @@ export const spawnGitRunner: WorktreeGitRunner = {
 };
 
 async function runGitCommand(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult> {
+  const env = { ...process.env };
+  delete env.GIT_EXTERNAL_DIFF;
+  delete env.GIT_DIFF_OPTS;
   return await runBoundedProcess({
     file: "git",
     args: options.args,
     cwd: options.cwd,
-    env: { ...process.env, GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" },
+    env,
     signal: options.signal,
     timeoutMs: options.timeoutMs,
     maxBufferBytes: options.maxBufferBytes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [