@quintinshaw/pi-dynamic-workflows 1.4.0 → 1.6.0

package/README.md

@@ -55,9 +55,19 @@ Ask for a background workflow (the model passes `background: true`) and it runs
 /workflows status <id>     # show a run's progress
 /workflows stop <id>       # abort a running run
 /workflows pause <id>      # pause a running run
+/workflows resume <id>     # resume an interrupted run (replays cached results)
 /workflows rm <id>         # remove a run from the list
 ```
 
+### Bundled workflows
+
+```text
+/deep-research <question>      # web-researched, source-cross-checked report
+/adversarial-review <task>     # findings cross-checked by skeptical reviewers
+```
+
+`/deep-research` fans out web searches across several angles, fetches the top sources with real `web_search` / `web_fetch` tools, keeps only claims supported by multiple sources, and writes a cited report.
+
 ## Workflow script shape
 
 A workflow is plain JavaScript. The first statement must export literal metadata:
@@ -99,6 +109,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.
@@ -134,7 +145,9 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 - **Real token & cost accounting** — read from each subagent's SDK session (input / output / total / cost), with a character estimate only as fallback when a provider reports no usage; `budget` gates on the real total
 - **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
+- **Bundled `/deep-research` & `/adversarial-review`** — `/deep-research` runs real web searches (via built-in `web_search` / `web_fetch` tools), extracts claims, cross-checks them across sources, and reports only what survived; `/adversarial-review` investigates a task then has independent skeptics try to refute each finding, keeping only those that clear an agreement threshold
 - **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 +156,8 @@ 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`**
 - **Saved workflows** as `/<name>` slash commands
+- **Nested `workflow()`** to compose saved workflows inline
 
 ## How it works
 

package/dist/adversarial-review.d.ts

@@ -11,9 +11,14 @@ export interface AdversarialReviewConfig {
     agreementThreshold: number;
 }
 /**
- * Generate an adversarial review workflow script.
+ * Generate an adversarial-review workflow. The script is static and reads its
+ * inputs from `args` (task/reviewers/threshold) — no string interpolation.
+ *
+ * Each finding is judged independently by N reviewers who are told to REFUTE it;
+ * a finding survives only when the share of reviewers calling it real meets the
+ * agreement threshold.
  */
-export declare function generateAdversarialReviewWorkflow(taskDescription: string, config?: Partial<AdversarialReviewConfig>): string;
+export declare function generateAdversarialReviewWorkflow(): string;
 /**
  * Generate a multi-perspective analysis workflow.
  */

package/dist/adversarial-review.js

@@ -2,56 +2,64 @@
  * Adversarial review mode for workflows.
  * Agents cross-check each other's findings for higher quality results.
  */
-const DEFAULT_CONFIG = {
-    reviewerCount: 2,
-    filterContested: true,
-    agreementThreshold: 0.5,
-};
 /**
- * Generate an adversarial review workflow script.
+ * Generate an adversarial-review workflow. The script is static and reads its
+ * inputs from `args` (task/reviewers/threshold) — no string interpolation.
+ *
+ * Each finding is judged independently by N reviewers who are told to REFUTE it;
+ * a finding survives only when the share of reviewers calling it real meets the
+ * agreement threshold.
  */
-export function generateAdversarialReviewWorkflow(taskDescription, config = {}) {
-    const cfg = { ...DEFAULT_CONFIG, ...config };
+export function generateAdversarialReviewWorkflow() {
     return `export const meta = {
   name: 'adversarial_review',
-  description: 'Adversarial review with ${cfg.reviewerCount} independent reviewers',
+  description: 'Adversarial review: findings cross-checked by independent skeptics',
   phases: [
-    { title: 'Initial Investigation' },
-    { title: 'Independent Review' },
-    { title: 'Cross-Check' },
+    { title: 'Investigate' },
+    { title: 'Refute' },
     { title: 'Consensus' },
   ],
-};
+}
 
-phase('Initial Investigation');
-const findings = await agent(
-  'Investigate and document findings for: ${taskDescription.replace(/'/g, "\\'").slice(0, 80)}',
-  { label: 'investigator' }
-);
+const task = (args && args.task) || ''
+const reviewers = (args && args.reviewers) || 2
+const threshold = (args && args.threshold) || 0.5
 
-phase('Independent Review');
-const reviews = await parallel(Array.from({ length: ${cfg.reviewerCount} }, (_, i) => () =>
-  agent(
-    'Independently review these findings. Agree or disagree with each point, and explain why:\\n\\n' + findings,
-    { label: 'reviewer-' + (i + 1) }
-  )
-));
+phase('Investigate')
+const investigation = await agent(
+  'Investigate the following and list concrete, individually-checkable findings:\\n' + task,
+  { label: 'investigate', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
+)
+const findings = investigation.findings || []
 
-phase('Cross-Check');
-const crossCheck = await agent(
-  'Compare these independent reviews and identify points of agreement and disagreement:\\n' +
-  'Reviews: ' + JSON.stringify(reviews) + '\\n' +
-  'Original findings: ' + findings,
-  { label: 'cross-checker' }
-);
+phase('Refute')
+const judged = await parallel(findings.map((f, i) => () =>
+  parallel(Array.from({ length: reviewers }, (_, r) => () =>
+    agent(
+      'You are a skeptical reviewer. Try to REFUTE this finding for the task below. ' +
+      'Default to real=false when uncertain. Investigate with the available tools if needed.\\n\\n' +
+      'TASK: ' + task + '\\nFINDING: ' + f,
+      { label: 'refute ' + (i + 1) + '.' + (r + 1), schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
+    )
+  )).then((votes) => {
+    const valid = votes.filter(Boolean)
+    const realCount = valid.filter((v) => v && v.real).length
+    const ratio = valid.length ? realCount / valid.length : 0
+    return { finding: f, realVotes: realCount, totalVotes: valid.length, survives: ratio >= threshold }
+  })
+))
 
-phase('Consensus');
-const consensus = await agent(
-  'Based on the cross-check, produce a final verified report. Only include findings that survived independent review:\\n' + crossCheck,
-  { label: 'consensus-builder' }
-);
+const survivors = judged.filter((j) => j && j.survives)
+
+phase('Consensus')
+const report = await agent(
+  'Write a final review report. Include ONLY the findings that survived adversarial review (listed below), ' +
+  'each with a short justification. Note how many were discarded.\\n\\n' +
+  'SURVIVING FINDINGS JSON:\\n' + JSON.stringify(survivors),
+  { label: 'consensus' }
+)
 
-return { findings, reviews, crossCheck, consensus };`;
+return { total: findings.length, survivors, report }`;
 }
 /**
  * Generate a multi-perspective analysis workflow.

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/builtin-commands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bundled workflow commands: `/deep-research` and `/adversarial-review`.
+ * They run a generated workflow script and print the final report.
+ */
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerBuiltinWorkflows(pi: ExtensionAPI, opts: {
+    cwd: string;
+}): void;

package/dist/builtin-commands.js

@@ -0,0 +1,77 @@
+/**
+ * Bundled workflow commands: `/deep-research` and `/adversarial-review`.
+ * They run a generated workflow script and print the final report.
+ */
+import { createCodingTools } from "@earendil-works/pi-coding-agent";
+import { generateAdversarialReviewWorkflow } from "./adversarial-review.js";
+import { generateDeepResearchWorkflow } from "./deep-research.js";
+import { createWebTools } from "./web-tools.js";
+import { runWorkflow } from "./workflow.js";
+function alreadyRegistered(pi, name) {
+    try {
+        return (pi.getCommands?.() ?? []).some((c) => c.name === name);
+    }
+    catch {
+        return false;
+    }
+}
+function reportText(result) {
+    const r = result.result;
+    if (r && typeof r.report === "string" && r.report.trim())
+        return r.report;
+    return JSON.stringify(result.result, null, 2);
+}
+export function registerBuiltinWorkflows(pi, opts) {
+    const cwd = opts.cwd;
+    if (!alreadyRegistered(pi, "deep-research")) {
+        pi.registerCommand("deep-research", {
+            description: "Research a question across the web with cross-checked sources",
+            async handler(args, ctx) {
+                const question = args.trim();
+                if (!question)
+                    return ctx.ui.notify("Usage: /deep-research <question>", "warning");
+                ctx.ui.notify("Researching — running web searches across several angles…", "info");
+                try {
+                    const result = await runWorkflow(generateDeepResearchWorkflow(), {
+                        cwd,
+                        args: { question },
+                        // Research agents need real web access on top of the coding tools.
+                        tools: [...createCodingTools(cwd), ...createWebTools()],
+                        onPhase: (title) => ctx.ui.setStatus("deep-research", `research: ${title}`),
+                    });
+                    ctx.ui.setStatus("deep-research", undefined);
+                    await pi.sendMessage({ customType: "deep-research", content: reportText(result), display: true });
+                }
+                catch (error) {
+                    ctx.ui.setStatus("deep-research", undefined);
+                    ctx.ui.notify(`deep-research failed: ${error instanceof Error ? error.message : error}`, "error");
+                }
+            },
+        });
+    }
+    if (!alreadyRegistered(pi, "adversarial-review")) {
+        pi.registerCommand("adversarial-review", {
+            description: "Investigate a task, then cross-check each finding with skeptical reviewers",
+            async handler(args, ctx) {
+                const task = args.trim();
+                if (!task)
+                    return ctx.ui.notify("Usage: /adversarial-review <task or question>", "warning");
+                ctx.ui.notify("Reviewing — investigating then refuting each finding…", "info");
+                try {
+                    const result = await runWorkflow(generateAdversarialReviewWorkflow(), {
+                        cwd,
+                        args: { task },
+                        tools: createCodingTools(cwd),
+                        onPhase: (title) => ctx.ui.setStatus("adversarial-review", `review: ${title}`),
+                    });
+                    ctx.ui.setStatus("adversarial-review", undefined);
+                    await pi.sendMessage({ customType: "adversarial-review", content: reportText(result), display: true });
+                }
+                catch (error) {
+                    ctx.ui.setStatus("adversarial-review", undefined);
+                    ctx.ui.notify(`adversarial-review failed: ${error instanceof Error ? error.message : error}`, "error");
+                }
+            },
+        });
+    }
+}

package/dist/deep-research.d.ts

@@ -3,19 +3,19 @@
  * Built-in workflow for comprehensive research across multiple sources.
  */
 export interface DeepResearchConfig {
-    /** Number of search angles to explore. */
-    searchAngles: number;
-    /** Number of sources to fetch per angle. */
-    sourcesPerAngle: number;
-    /** Whether to cross-check claims across sources. */
-    crossCheck: boolean;
-    /** Maximum number of agents to use. */
-    maxAgents: number;
+    /** Number of distinct search angles/queries to explore. */
+    angles: number;
+    /** Minimum distinct sources required for a claim to survive cross-checking. */
+    minSupport: number;
 }
 /**
- * Generate a deep research workflow script.
+ * Generate a deep-research workflow that uses the real web_search/web_fetch tools.
+ *
+ * The script is static and reads its inputs from `args` (question/angles/minSupport),
+ * so the question is never string-interpolated into source — no escaping hazards.
+ * Inject the web tools at run time via the agent's `tools` option.
  */
-export declare function generateDeepResearchWorkflow(question: string, config?: Partial<DeepResearchConfig>): string;
+export declare function generateDeepResearchWorkflow(): string;
 /**
  * Generate a codebase audit workflow.
  */

package/dist/deep-research.js

@@ -2,66 +2,66 @@
  * Deep research workflow.
  * Built-in workflow for comprehensive research across multiple sources.
  */
-const DEFAULT_CONFIG = {
-    searchAngles: 4,
-    sourcesPerAngle: 3,
-    crossCheck: true,
-    maxAgents: 20,
-};
 /**
- * Generate a deep research workflow script.
+ * Generate a deep-research workflow that uses the real web_search/web_fetch tools.
+ *
+ * The script is static and reads its inputs from `args` (question/angles/minSupport),
+ * so the question is never string-interpolated into source — no escaping hazards.
+ * Inject the web tools at run time via the agent's `tools` option.
  */
-export function generateDeepResearchWorkflow(question, config = {}) {
-    const cfg = { ...DEFAULT_CONFIG, ...config };
-    const escapedQuestion = question.replace(/'/g, "\\'").slice(0, 80);
-    const crossCheckPhase = cfg.crossCheck
-        ? `phase('Cross-Check');
-const crossCheck = await agent(
-  'Cross-check these research findings. Identify claims that are supported by multiple sources vs. claims that appear in only one source:\\n' +
-  'Sources: ' + JSON.stringify(sources),
-  { label: 'cross-checker' }
-);`
-        : "";
-    const crossCheckRef = cfg.crossCheck ? "'Cross-check: ' + crossCheck + '\\n' + " : "";
-    const crossCheckReturn = cfg.crossCheck ? "crossCheck, " : "";
+export function generateDeepResearchWorkflow() {
     return `export const meta = {
   name: 'deep_research',
-  description: 'Deep research: ${escapedQuestion}',
+  description: 'Deep research with real web search and cross-checked claims',
   phases: [
-    { title: 'Search Planning' },
-    { title: 'Source Gathering' },
-    { title: 'Cross-Check' },
+    { title: 'Queries' },
+    { title: 'Gather' },
+    { title: 'Verify' },
     { title: 'Report' },
   ],
-};
+}
 
-phase('Search Planning');
-const question = '${escapedQuestion}';
-const searchPlan = await agent(
-  'Plan ${cfg.searchAngles} different search angles to research this question comprehensively: ' + question,
-  { label: 'search-planner' }
-);
+const question = (args && args.question) || ''
+const angles = (args && args.angles) || 4
+const minSupport = (args && args.minSupport) || 2
 
-phase('Source Gathering');
-const sources = await parallel(Array.from({ length: ${cfg.searchAngles} }, (_, i) => () =>
+phase('Queries')
+const plan = await agent(
+  'You are planning web research for this question:\\n' + question +
+  '\\n\\nProduce ' + angles + ' diverse, specific search queries that together cover the question from different angles.',
+  { label: 'plan queries', schema: { type: 'object', properties: { queries: { type: 'array', items: { type: 'string' } } }, required: ['queries'] } }
+)
+const queries = (plan.queries || []).slice(0, angles)
+
+phase('Gather')
+const gathered = await parallel(queries.map((q, i) => () =>
   agent(
-    'Research angle ' + (i + 1) + ' for this question: ' + question + '\\n\\nPlan: ' + searchPlan + '\\n\\nFind and summarize ${cfg.sourcesPerAngle} relevant sources.',
-    { label: 'researcher-' + (i + 1) }
+    'Research this query using the web_search and web_fetch tools.\\nQuery: ' + q +
+    '\\n\\nSteps: (1) call web_search with the query; (2) web_fetch the 2 most relevant result URLs; ' +
+    '(3) extract concrete, verifiable factual claims, each tagged with the exact source URL it came from. ' +
+    'Do NOT invent sources or claims — report only what the fetched pages actually say.',
+    { label: 'research ' + (i + 1), schema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, claims: { type: 'array', items: { type: 'string' } } }, required: ['url', 'claims'] } } }, required: ['sources'] } }
   )
-));
+))
+const allSources = gathered.filter(Boolean).flatMap((g) => (g && g.sources) || [])
 
-${crossCheckPhase}
+phase('Verify')
+const verdict = await agent(
+  'Cross-check these research sources. Group claims that assert the same fact across different source URLs. ' +
+  'Keep a claim only if it is supported by at least ' + minSupport + ' distinct source URLs OR by one clearly authoritative source. ' +
+  'Discard claims found in a single weak source or that conflict with others.\\n\\nSOURCES JSON:\\n' + JSON.stringify(allSources),
+  { label: 'cross-check', schema: { type: 'object', properties: { supported: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } } }, required: ['claim', 'sources'] } }, discarded: { type: 'array', items: { type: 'string' } } }, required: ['supported'] } }
+)
 
-phase('Report');
+phase('Report')
 const report = await agent(
-  'Synthesize a comprehensive research report from these findings:\\n' +
-  'Question: ' + question + '\\n' +
-  'Sources: ' + JSON.stringify(sources) + '\\n' +
-  ${crossCheckRef}'\\n\\nProduce a well-structured report with citations and confidence levels.',
-  { label: 'report-writer' }
-);
+  'Write a concise, well-structured research report that answers the question using ONLY the supported claims below. ' +
+  'Cite source URLs inline next to each claim. If the evidence is thin, say so explicitly.\\n\\n' +
+  'QUESTION: ' + question + '\\n\\nSUPPORTED CLAIMS JSON:\\n' + JSON.stringify((verdict && verdict.supported) || []),
+  { label: 'write report' }
+)
 
-return { searchPlan, sources, ${crossCheckReturn}report };`;
+return { question, queries, supported: (verdict && verdict.supported) || [], report }`;
 }
 /**
  * Generate a codebase audit workflow.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./ag
 export { WorkflowAgent } from "./agent.js";
 export type { AutoWorkflowConfig } from "./auto-workflow.js";
 export { shouldUseWorkflow, suggestWorkflowScript } from "./auto-workflow.js";
+export { registerBuiltinWorkflows } from "./builtin-commands.js";
 export * from "./config.js";
 export type { DeepResearchConfig } from "./deep-research.js";
 export { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
@@ -18,7 +19,8 @@ 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 { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.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 +29,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

@@ -1,6 +1,7 @@
 export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
 export { WorkflowAgent } from "./agent.js";
 export { shouldUseWorkflow, suggestWorkflowScript } from "./auto-workflow.js";
+export { registerBuiltinWorkflows } from "./builtin-commands.js";
 export * from "./config.js";
 export { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
 export { createToolUpdateWorkflowDisplay, createWidgetWorkflowDisplay, createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display.js";
@@ -9,8 +10,10 @@ export { createWorkflowLogger } from "./logger.js";
 export { buildModelRoutingInstructions, parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
 export { createRunPersistence, generateRunId } from "./run-persistence.js";
 export { createStructuredOutputTool } from "./structured-output.js";
+export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 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/web-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/** A tool that searches the web (best-effort) and returns result URLs + titles. */
+export declare function createWebSearchTool(): ToolDefinition;
+/** A tool that fetches a URL and returns readable text. */
+export declare function createWebFetchTool(maxChars?: number): ToolDefinition;
+/** Both web tools, for injecting into a research workflow's agents. */
+export declare function createWebTools(): ToolDefinition[];

package/dist/web-tools.js

@@ -0,0 +1,119 @@
+/**
+ * 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 } 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, timeoutMs = 15000) {
+    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) {
+    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, limit) {
+    const out = [];
+    const seen = new Set();
+    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() {
+    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) {
+            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: [] },
+                };
+            }
+        },
+    });
+}
+/** A tool that fetches a URL and returns readable text. */
+export function createWebFetchTool(maxChars = 6000) {
+    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) {
+            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 },
+                };
+            }
+        },
+    });
+}
+/** Both web tools, for injecting into a research workflow's agents. */
+export function createWebTools() {
+    return [createWebSearchTool(), createWebFetchTool()];
+}

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;