pi-workflow-engine 0.11.0 → 0.12.0

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -2,13 +2,14 @@ import { Type } from "typebox";
 import {
   AdvisoryReportSchema,
   type AdvisoryCandidate,
-  type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
 import {
   backfillAdvisoryFindings,
+  emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
+  publishVerifiedKeptProgress,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
@@ -79,11 +80,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect repository structure, the target path or module, and relevant AGENTS.md / project docs conventions. " +
       "Return the concrete files that should be considered, a short summary, and any conventions that affect refactor advice. " +
       `This workflow will fan out across ${REFACTOR_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
-    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope || scope.files.length === 0) {
-    return emptyReport(
+    return emptyAdvisoryReport(
       "No files were identified for refactor scouting.",
       ["Provide a target path, module, or subsystem to scout for refactor opportunities."],
       makeStats(0, 0),
@@ -136,14 +137,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const verified = pipelineResult.verified;
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
-  progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
-  progress({ type: "counter", key: "kept", label: "kept", value: surviving.length });
-  progress({ type: "summary", key: "verified", value: verified.length });
-  progress({ type: "summary", key: "kept", value: surviving.length });
-  log(`${verified.length} verified → ${surviving.length} kept`);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return emptyReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], stats);
+    return emptyAdvisoryReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], stats);
   }
 
   phase("Synthesize");
@@ -166,13 +163,13 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       phase: "Synthesize",
       label: "synthesize",
       tools: [],
-      thinkingLevel: "medium",
+      profile: "medium",
       resume: "read-only",
       schema: AdvisoryReportSchema,
     },
   );
 
-  if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun the workflow with a narrower target."], stats);
+  if (!report) return emptyAdvisoryReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun the workflow with a narrower target."], stats);
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Impact not restated by synthesis.",
@@ -181,10 +178,6 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   return { ...report, findings, stats };
 }
 
-function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunStats): AdvisoryReport & { stats: WorkflowRunStats } {
-  return { summary, findings: [], nextSteps, stats };
-}
-
 function rank(finding: Verified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const categoryRank = finding.category === "dead-code" || finding.category === "conventions" ? 2 : 0;

package/.pi/extensions/pi-workflow-engine/workflows/research.ts

@@ -0,0 +1,170 @@
+import { compactResults } from "../src/concurrency.ts";
+import {
+  MAX_RESEARCH_LANES,
+  ResearchLaneResultSchema,
+  ResearchPlanSchema,
+  ResearchReportSchema,
+  ResearchVerificationSchema,
+  type ResearchClaimCandidate,
+  type ResearchReport,
+  type ResearchVerification,
+} from "../src/research-contract.ts";
+import {
+  buildClaimCandidates,
+  fallbackResearchReport,
+  normalizeResearchLanes,
+  sanitizeLaneResults,
+  sanitizeResearchReport,
+  sanitizeVerification,
+  unavailableResearchReport,
+  unavailableVerification,
+} from "../src/research-evidence.ts";
+import { WorkflowToolHintUnavailableError } from "../src/tool-capabilities.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "research",
+  description: "Source-grounded external research: decompose → gather direct-page evidence → independently verify claims → cited synthesis.",
+  phases: [{ title: "Plan" }, { title: "Gather" }, { title: "Verify" }, { title: "Synthesize" }],
+};
+
+const EXTERNAL_TOOLS: string[] = [];
+const EXTERNAL_TOOL_HINTS = ["external-search"] as const;
+
+export default async function run(api: WorkflowApi): Promise<ResearchReport> {
+  const { agent, parallel, phase, log, progress, args } = api;
+  const question = args.trim();
+  if (!question) return unavailableResearchReport("empty-question");
+
+  phase("Plan");
+  let plan;
+  try {
+    plan = await agent(
+      `Plan bounded, source-grounded research for the user's question and any scope constraints embedded in it.\n\n` +
+        `Question and constraints (verbatim):\n${question}\n\n` +
+        `Create at most ${MAX_RESEARCH_LANES} non-overlapping lanes. Each lane needs a stable short id, title, objective, and 1-4 concrete search queries. ` +
+        "Separate primary-source discovery, current status, counterevidence, or jurisdiction/timeframe only when relevant. " +
+        "Do not claim exhaustive coverage. Structured output only.",
+      {
+        phase: "Plan",
+        label: "plan",
+        tools: EXTERNAL_TOOLS,
+        toolHints: EXTERNAL_TOOL_HINTS,
+        requireToolHints: true,
+        profile: "medium",
+        resume: "off",
+        schema: ResearchPlanSchema,
+      },
+    );
+  } catch (error) {
+    if (error instanceof WorkflowToolHintUnavailableError) return unavailableResearchReport("missing-capability");
+    throw error;
+  }
+
+  if (!plan) return unavailableResearchReport("no-evidence");
+  const lanes = normalizeResearchLanes(plan);
+  if (lanes.length === 0) return unavailableResearchReport("no-evidence");
+  progress({ type: "counter", key: "research.lanes", label: "research lanes", value: lanes.length });
+  progress({ type: "summary", key: "research.question", value: question });
+
+  phase("Gather");
+  const gathered = compactResults(
+    await parallel(
+      lanes.map((lane) => async () => {
+        const result = await agent(
+          `Research one bounded lane using only installed external web-search, browsing, or URL-extraction tools.\n\n` +
+            `Question: ${question}\n` +
+            `Scope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n` +
+            `Lane id: ${lane.id}\nLane: ${lane.title}\nObjective: ${lane.objective}\n` +
+            `Queries:\n${lane.queries.map((query) => `- ${query}`).join("\n")}\n\n` +
+            "Open the supporting pages instead of citing a search-results page. Prefer primary and authoritative sources; use independent sources when useful. " +
+            "Return concrete claims with importance, whether each page supports or conflicts with the claim, a short passage or precise paraphrase, and the exact page title and URL. " +
+            "State evidence gaps. Never invent a URL or claim that the opened page does not support. Structured output only.",
+          {
+            phase: "Gather",
+            label: `gather:${lane.id}`,
+            tools: EXTERNAL_TOOLS,
+            toolHints: EXTERNAL_TOOL_HINTS,
+            requireToolHints: true,
+            profile: "small",
+            resume: "off",
+            schema: ResearchLaneResultSchema,
+          },
+        );
+        if (!result) return null;
+        progress({ type: "counter_delta", key: "research.evidence", label: "evidence items", delta: result.evidence.length });
+        progress({
+          type: "lane_item",
+          lane: "Research lanes",
+          title: lane.title,
+          subtitle: `${result.evidence.length} evidence item(s)`,
+          status: result.evidence.length > 0 ? "success" : "warning",
+          details: result.gaps.join("; ") || lane.objective,
+        });
+        return result;
+      }),
+    ),
+  );
+
+  const laneResults = sanitizeLaneResults(gathered);
+  const candidates = buildClaimCandidates(laneResults);
+  if (candidates.length === 0) return unavailableResearchReport("no-evidence");
+  progress({ type: "counter", key: "research.claims", label: "claims to verify", value: candidates.length });
+  log(`${candidates.length} bounded claim(s) selected for independent verification`);
+
+  phase("Verify");
+  const verificationResults = await parallel(
+    candidates.map((candidate, index) => async () => {
+      const result = await agent(verificationPrompt(question, candidate), {
+        phase: "Verify",
+        label: `verify:${index + 1}`,
+        tools: EXTERNAL_TOOLS,
+        toolHints: EXTERNAL_TOOL_HINTS,
+        requireToolHints: true,
+        profile: "medium",
+        resume: "off",
+        schema: ResearchVerificationSchema,
+      });
+      return result ? sanitizeVerification(result, candidate) : null;
+    }),
+  );
+  const verifications = verificationResults.map((result, index) => result ?? unavailableVerification(candidates[index]!));
+  for (const verification of verifications) {
+    progress({ type: "counter_delta", key: `research.${verification.verdict.toLowerCase()}`, label: verification.verdict.toLowerCase(), delta: 1 });
+  }
+  const synthesisInputs = verifications.filter((verification) => verification.verdict !== "REJECTED");
+
+  phase("Synthesize");
+  const synthesis = await agent(
+    `Answer the research question using only the independently verified handoff below.\n\n` +
+      `Question: ${question}\nScope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n\n` +
+      `Verified claims JSON:\n${JSON.stringify(synthesisInputs)}\n\n` +
+      "Keep SUPPORTED claims, CONFLICTED evidence, UNCERTAIN claims, and model INFERENCE in their separate fields. Exclude REJECTED claims. " +
+      "Copy each verified claim string exactly so its citations remain bound to that claim during validation. " +
+      "Every supported or conflicting claim must cite exact title/URL objects from its verification; do not add URLs, cite search-results pages, or turn inference into fact. " +
+      "Answer concisely, disclose limited coverage, and provide useful next steps. Structured output only.",
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "off",
+      schema: ResearchReportSchema,
+    },
+  );
+
+  return sanitizeResearchReport(
+    synthesis ?? fallbackResearchReport(synthesisInputs, "The model did not return a structured synthesis."),
+    synthesisInputs,
+  );
+}
+
+function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {
+  return `Independently verify one important research claim using installed external web-search, browsing, or URL-extraction tools.\n\n` +
+    `Question: ${question}\nClaim: ${candidate.claim}\nImportance: ${candidate.importance}\n\n` +
+    `Gather-stage evidence (context only; do not treat it as verified):\n${JSON.stringify(candidate.evidence)}\n\n` +
+    "Search independently and open direct supporting pages. Prefer primary/authoritative sources and actively look for credible counterevidence. " +
+    "Return SUPPORTED only when direct pages substantiate the claim, CONFLICTED when credible sources disagree, UNCERTAIN when evidence is insufficient, " +
+    "INFERENCE when the conclusion is reasoned rather than directly stated, or REJECTED when evidence refutes it. " +
+    "Include exact page titles and direct HTTP(S) URLs, never search-results URLs. Structured output only.";
+}

package/README.md

@@ -4,63 +4,48 @@
 [![npm](https://img.shields.io/npm/v/pi-workflow-engine)](https://www.npmjs.com/package/pi-workflow-engine)
 [![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**A multi-agent workflow engine for [pi](https://pi.dev).**
+**Multi-agent workflows for [pi](https://pi.dev).**
 
-One coding agent is usually enough. When a task needs independent opinions,
-competing hypotheses, or a verifier that did not write the first answer, this
-extension lets pi fan the work out and bring the evidence back together.
-
-The process is simple: **scope → fan out → verify → synthesize**. You see the work
-live in the TUI, concurrency stays bounded, and the final answer includes the
-subagents' combined usage and estimated cost when the provider exposes enough
-data to calculate them.
+When a task benefits from independent review, competing hypotheses, or separate
+verification, pi-workflow-engine fans it out to subagents and synthesizes one
+result. Run a built-in workflow or add `dynamax` to a prompt so pi can compose a
+one-off workflow for the task.
 
 ![A lead agent coordinating subagents](assets/preview.png)
 
 ## Quick start
 
+Requires **pi 0.80.10 or newer**.
+
 ```bash
 pi install npm:pi-workflow-engine
 ```
 
-Restart pi or run `/reload`, then add `dynamax` to a prompt:
+Restart pi or run `/reload`, then try either style:
 
 ```text
 dynamax investigate why typecheck started failing on this branch
-```
-
-`dynamax` is a one-shot opt-in. It lets the host agent choose a saved workflow
-or author a temporary one for this task. Use `/workflow:dynamax on` when you
-want that permission to remain active for the session.
-
-Saved workflows are available directly:
 
-```text
 /workflow code-review
 /workflow refactor-scout src/
 /workflow diagnose "the schema migration broke typecheck"
-/workflow perf-review "workflow startup latency"
 ```
 
-The package uses pi's bundled SDK and core packages; it does not install or
-bundle a second agent runtime.
-
-## What it gives you
-
-- **Independent passes.** Different agents can inspect correctness, tests,
-  coupling, performance, or any lenses you define.
-- **Typed handoffs.** A TypeBox schema becomes the agent's terminating tool
-  contract—there is no JSON scraping.
-- **Live progress.** Phases, agents, findings, and logs are visible in the TUI,
-  alongside usage and estimated cost when provider data is available.
-- **Bounded execution.** One semaphore covers nested fan-out, pipelines, and
-  sub-workflows.
-- **Evidence before action.** Built-in workflows inspect and report by default;
-  they do not edit your working tree.
-- **Reviewable mutation.** An author can opt a mutating agent into a disposable
-  git worktree and receive its patch.
-- **Safe replay.** Interrupted runs reuse a completed call only when every
-  captured observable surface and its effective execution identity still match.
+Built-in workflows inspect and report by default; they do not edit your working
+tree.
+
+## What you get
+
+- **Independent analysis.** Give correctness, testing, performance, or other
+  concerns to separate agents instead of asking one agent to cover everything.
+- **Verified results.** Workflows can check and rank findings before presenting
+  a single synthesis.
+- **Live visibility.** Follow phases and agents in the TUI, with usage and cost
+  totals when the provider reports them.
+- **Controlled execution.** Concurrency, timeouts, agent counts, and token
+  budgets keep fan-out bounded.
+- **Safe follow-up.** Advisory runs leave the checkout alone, while selected
+  review fixes can return isolated patch previews.
 
 ## Built-in workflows
 
@@ -69,115 +54,63 @@ bundle a second agent runtime.
 | `code-review` | PRs, branch diffs, ref ranges, or focused targets |
 | `refactor-scout` | Small, defensible refactors without broad rewrites |
 | `diagnose` | Competing explanations for bugs or failing commands |
-| `perf-review` | Measured bottlenecks versus performance guesses |
+| `perf-review` | Measured bottlenecks rather than performance guesses |
+| `research` | Cited external evidence with independent claim verification |
 
-These are starting points, not a fixed menu. Dynamax can author a one-off
-workflow when the question needs different lenses or an adaptive second pass.
+The `research` workflow needs an installed pi tool that can search or browse the
+web. See the [built-in workflow guide](USAGE.md#built-in-workflows) for behavior
+and requirements.
 
-## The review experience
+## Use Dynamax for one-off workflows
 
-When reviewing a PR, `code-review` uses its cumulative diff, so superseded code
-from earlier commits does not become a finding. Candidate issues are
-independently verified, deduplicated, and ranked before synthesis.
+Use `dynamax` when no saved workflow quite fits and independent passes are
+likely to change the answer:
 
-Add `--result-viewer` to open the interactive findings view. It exposes a findings list for follow-up. Reopen the current session's latest review
-with `/workflow:results` or `ctrl+shift+r`—it does not rerun the workflow.
+```text
+dynamax review this branch for correctness, tests, and maintainability; verify every finding
+dynamax investigate this flaky test using separate timing, fixture, diff, and external-state hypotheses
+dynamax argue both implementation options, then have another agent challenge the recommendation
+```
 
-The **Fix** action creates one disposable worktree per selected finding and
-returns separate patch previews without touching the active checkout. GitHub
-comments are available only for a verified PR target; the engine checks the
-snapshot and PR head again and skips exact duplicates before posting.
+The token enables Dynamax for one turn. Sticky mode remains active for the pi
+session:
 
-## Prompts that benefit from Dynamax
+```text
+/workflow:dynamax on
+/workflow:dynamax off
+/workflow:dynamax status
+```
 
-- **Review:** `dynamax` review this branch from correctness, test,
-  security-boundary, and maintainability angles; verify every finding.
-- **Debug:** `dynamax` investigate this flaky test using separate hypotheses for
-  timing, fixtures, recent diffs, and external state.
-- **Decide:** `dynamax` argue both implementation options, then have another
-  agent attack the recommendation.
-- **Refactor:** `dynamax` find the smallest safe path through this module and
-  identify what should not change.
+In the TUI, a standalone `dynamax` token receives a short moving-shine sweep and
+then stays highlighted. Use `PI_DYNAMAX_EFFECT=static` or
+`PI_DYNAMAX_EFFECT=off` to reduce or disable the cue; the
+[prompt editor guide](USAGE.md#prompt-editor-cue) has the full details.
 
 Tiny edits and straightforward questions are still better handled by one agent.
-Dynamax earns its cost when independence or breadth changes the answer.
-
-## Write a workflow
-
-A saved workflow is a TypeScript module with metadata and one async function.
-The injected API supplies agents, concurrency primitives, phases, progress,
-budgets, cancellation, and sub-workflow composition.
-
-```ts
-import { Type } from "typebox";
-import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
-
-export const meta: WorkflowMeta = {
-  name: "two-angle-review",
-  description: "Find issues independently, then synthesize.",
-};
-
-const Finding = Type.Object({
-  summary: Type.String(),
-  evidence: Type.Array(Type.String()),
-});
-const reviewTools = ["read", "grep", "find", "ls"];
-
-export default async function run(
-  { agent, parallel, phase, args }: WorkflowApi,
-) {
-  phase("Find");
-  const findings = await parallel([
-    () => agent(`Review correctness: ${args}`, {
-      schema: Finding,
-      tools: reviewTools,
-      thinkingLevel: "low",
-      resume: "read-only",
-    }),
-    () => agent(`Review edge cases: ${args}`, {
-      schema: Finding,
-      tools: reviewTools,
-      thinkingLevel: "low",
-      resume: "read-only",
-    }),
-  ]);
-
-  phase("Synthesize");
-  return agent(`Merge and rank these findings: ${JSON.stringify(findings)}`, {
-    tools: [],
-    thinkingLevel: "medium",
-    resume: "read-only",
-  });
-}
+Dynamax is useful when independence or breadth materially improves the result.
+
+## Review and inspect results
+
+`code-review` verifies, deduplicates, and ranks candidate findings. Open the
+interactive findings view for follow-up, or bring back the latest result without
+rerunning the workflow:
+
+```text
+/workflow code-review --result-viewer
+/workflow:results
+/workflow:inspector
 ```
 
-Set `thinkingLevel` on fan-out agents so they do not all inherit an expensive
-global setting. The [usage guide](USAGE.md#author-a-saved-workflow) covers
-schemas, tools, skills, pipelines, settled results, worktree isolation, inline
-workflows, and registration.
-
-## Design choices
-
-- **Agent sessions:** each call uses an in-process pi `AgentSession` with an
-  in-memory session manager.
-- **Structured output:** the schema is a terminating tool definition validated
-  by pi.
-- **Recoverable failures:** a failed parallel branch becomes `null`; surviving
-  work continues.
-- **Fatal failures:** cancellation aborts siblings and drains submitted work
-  before rejection.
-- **Mutating agents:** disposable worktrees isolate edits and return
-  baseline-relative patches.
-- **Resume:** journals bind workspace-aware calls to repository state and all
-  calls to workflow, model, prompt, skill, and tool identity.
-- **Dependencies:** pi and TypeBox remain host-provided peers; the package ships
-  no duplicate runtime stack.
-
-The replay contract deliberately fails closed. For workspace-aware calls,
-changed commits, dirty state, and declared ignored inputs invalidate a hit.
-Workflow source, effective model or prompt, selected skills, and executable
-tools remain part of the relevant identity; unsafe or unbounded surfaces run
-live instead.
+The viewer can produce isolated patch previews for selected findings without
+changing the active checkout. The [usage guide](USAGE.md#workflow-results)
+covers review actions and recent run history.
+
+## Create your own workflows
+
+Saved workflows are TypeScript modules for repeatable orchestration; inline
+workflows are useful for one-off Dynamax tasks. The
+[workflow authoring guide](USAGE.md#author-a-saved-workflow) covers the API,
+typed handoffs, model profiles, tool access, composition, and registration.
 
 ## Develop locally
 
@@ -192,11 +125,9 @@ pi -ne -e .
 `pi -ne -e .` loads the working copy without also loading an installed global
 copy. There is no build step; pi loads the TypeScript extension directly.
 
-For the complete command reference, runtime controls, authoring rules, and
-troubleshooting, see [USAGE.md](USAGE.md). The public API lives in
-[types.ts](.pi/extensions/pi-workflow-engine/src/types.ts), and the built-in
-[code-review workflow](.pi/extensions/pi-workflow-engine/workflows/code-review.ts)
-is the most complete example.
+For the complete command reference, model configuration, workflow authoring,
+runtime controls, resume behavior, and troubleshooting, see
+[USAGE.md](USAGE.md).
 
 Questions and ideas are welcome in
 [GitHub Issues](https://github.com/timbrinded/pi-workflow-engine/issues).