@quintinshaw/pi-dynamic-workflows 1.4.0 → 1.6.0

package/src/web-tools.ts

@@ -0,0 +1,123 @@
+/**
+ * Real web tools for research workflows. These execute in the extension host
+ * process (which has network access), not in a subagent sandbox, so they perform
+ * genuine HTTP requests via Node's fetch.
+ *
+ * - web_search: best-effort Bing HTML scrape -> result {url, title}
+ * - web_fetch:  fetch a URL and return readable text (HTML stripped, truncated)
+ */
+
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36";
+
+async function fetchText(url: string, timeoutMs = 15000): Promise<{ status: number; body: string }> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { headers: { "user-agent": UA }, signal: controller.signal, redirect: "follow" });
+    return { status: res.status, body: await res.text() };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<\/(p|div|li|h[1-6]|tr|br)>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function parseBingResults(html: string, limit: number): Array<{ url: string; title: string }> {
+  const out: Array<{ url: string; title: string }> = [];
+  const seen = new Set<string>();
+  for (const m of html.matchAll(/<h2[^>]*>\s*<a[^>]+href="(https?:\/\/[^"]+)"[^>]*>([\s\S]*?)<\/a>/g)) {
+    const url = m[1];
+    if (/\.bing\.com|go\.microsoft\.com/.test(url) || seen.has(url)) continue;
+    seen.add(url);
+    out.push({ url, title: m[2].replace(/<[^>]+>/g, "").trim() });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/** A tool that searches the web (best-effort) and returns result URLs + titles. */
+export function createWebSearchTool(): ToolDefinition {
+  return defineTool({
+    name: "web_search",
+    label: "Web Search",
+    description: "Search the web and return a list of result URLs and titles. Use before web_fetch to find sources.",
+    promptSnippet: "Search the web for sources",
+    parameters: Type.Object({
+      query: Type.String({ description: "The search query." }),
+      count: Type.Optional(Type.Number({ description: "Max results (default 6)." })),
+    }),
+    async execute(_id, params: { query: string; count?: number }) {
+      const limit = Math.min(Math.max(params.count ?? 6, 1), 10);
+      try {
+        const { status, body } = await fetchText(`https://www.bing.com/search?q=${encodeURIComponent(params.query)}`);
+        const results = parseBingResults(body, limit);
+        const text = results.length
+          ? results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}`).join("\n")
+          : `No results parsed (HTTP ${status}). Try a different query or fetch a known URL directly.`;
+        return { content: [{ type: "text", text }], details: { results } };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `web_search failed: ${error instanceof Error ? error.message : error}` }],
+          details: { results: [] as Array<{ url: string; title: string }> },
+        };
+      }
+    },
+  }) as unknown as ToolDefinition;
+}
+
+/** A tool that fetches a URL and returns readable text. */
+export function createWebFetchTool(maxChars = 6000): ToolDefinition {
+  return defineTool({
+    name: "web_fetch",
+    label: "Web Fetch",
+    description: "Fetch a URL and return its readable text content (HTML stripped, truncated).",
+    promptSnippet: "Fetch a URL's text",
+    parameters: Type.Object({
+      url: Type.String({ description: "The absolute URL to fetch." }),
+    }),
+    async execute(_id, params: { url: string }) {
+      try {
+        const { status, body } = await fetchText(params.url);
+        const text = htmlToText(body).slice(0, maxChars);
+        return {
+          content: [{ type: "text", text: `HTTP ${status} ${params.url}\n\n${text}` }],
+          details: { status, url: params.url },
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `web_fetch failed for ${params.url}: ${error instanceof Error ? error.message : error}`,
+            },
+          ],
+          details: { status: 0, url: params.url },
+        };
+      }
+    },
+  }) as unknown as ToolDefinition;
+}
+
+/** Both web tools, for injecting into a research workflow's agents. */
+export function createWebTools(): ToolDefinition[] {
+  return [createWebSearchTool(), createWebFetchTool()];
+}

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
+    }
+  }
+}