@quintinshaw/pi-dynamic-workflows 1.0.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@quintinshaw/pi-dynamic-workflows",
+  "version": "1.0.0",
+  "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "extensions/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "npm run check && npm run build && npm run test:unit",
+    "test:unit": "tsx --test tests/**/*.test.ts",
+    "check": "biome check .",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "workflow",
+    "agents"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/workflow.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuintinShaw/pi-dynamic-workflows.git"
+  },
+  "author": "QuintinShaw",
+  "contributors": [
+    "michaelliv (original author)"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "acorn": "^8.16.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@earendil-works/pi-ai": "latest",
+    "@earendil-works/pi-coding-agent": "latest",
+    "@earendil-works/pi-tui": "latest",
+    "tsx": "latest",
+    "typebox": "latest",
+    "typescript": "latest"
+  }
+}

package/src/adversarial-review.ts

@@ -0,0 +1,107 @@
+/**
+ * Adversarial review mode for workflows.
+ * Agents cross-check each other's findings for higher quality results.
+ */
+
+export interface AdversarialReviewConfig {
+  /** Number of independent reviewers per finding. */
+  reviewerCount: number;
+  /** Whether to filter out findings that don't survive cross-checking. */
+  filterContested: boolean;
+  /** Minimum agreement threshold (0-1). */
+  agreementThreshold: number;
+}
+
+const DEFAULT_CONFIG: AdversarialReviewConfig = {
+  reviewerCount: 2,
+  filterContested: true,
+  agreementThreshold: 0.5,
+};
+
+/**
+ * Generate an adversarial review workflow script.
+ */
+export function generateAdversarialReviewWorkflow(
+  taskDescription: string,
+  config: Partial<AdversarialReviewConfig> = {},
+): string {
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+
+  return `export const meta = {
+  name: 'adversarial_review',
+  description: 'Adversarial review with ${cfg.reviewerCount} independent reviewers',
+  phases: [
+    { title: 'Initial Investigation' },
+    { title: 'Independent Review' },
+    { title: 'Cross-Check' },
+    { title: 'Consensus' },
+  ],
+};
+
+phase('Initial Investigation');
+const findings = await agent(
+  'Investigate and document findings for: ${taskDescription.replace(/'/g, "\\'").slice(0, 80)}',
+  { label: 'investigator' }
+);
+
+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('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('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' }
+);
+
+return { findings, reviews, crossCheck, consensus };`;
+}
+
+/**
+ * Generate a multi-perspective analysis workflow.
+ */
+export function generateMultiPerspectiveWorkflow(topic: string, perspectives: string[]): string {
+  const perspectiveAgents = perspectives
+    .map(
+      (p, _i) =>
+        `  () => agent('Analyze from ${p} perspective: ' + topic, { label: '${p.toLowerCase().replace(/\\s+/g, "-")}' }),`,
+    )
+    .join("\n");
+
+  return `export const meta = {
+  name: 'multi_perspective_analysis',
+  description: 'Analyze from ${perspectives.length} different perspectives',
+  phases: [
+    { title: 'Perspective Analysis' },
+    { title: 'Synthesis' },
+  ],
+};
+
+phase('Perspective Analysis');
+const topic = '${topic.replace(/'/g, "\\'")}';
+const analyses = await parallel([
+${perspectiveAgents}
+]);
+
+phase('Synthesis');
+const synthesis = await agent(
+  'Synthesize these different perspectives into a balanced analysis:\\n' +
+  'Analyses: ' + JSON.stringify(analyses) + '\\n' +
+  'Topic: ' + topic,
+  { label: 'synthesizer' }
+);
+
+return { analyses, synthesis };`;
+}

package/src/agent.ts

@@ -0,0 +1,135 @@
+import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import {
+  type CreateAgentSessionOptions,
+  createAgentSession,
+  createCodingTools,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+import { createStructuredOutputTool, type StructuredOutputCapture } from "./structured-output.js";
+
+export interface WorkflowAgentOptions {
+  cwd?: string;
+  /** Extra tools available to the subagent in addition to the structured output tool. */
+  tools?: ToolDefinition[];
+  /** Override any createAgentSession option (model, authStorage, resourceLoader, etc.). */
+  session?: Partial<CreateAgentSessionOptions>;
+  /** Extra system guidance prepended to every subagent task. */
+  instructions?: string;
+}
+
+export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefined> {
+  label?: string;
+  schema?: TSchemaDef;
+  tools?: ToolDefinition[];
+  instructions?: string;
+  signal?: AbortSignal;
+}
+
+export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema
+  ? Static<TSchemaDef>
+  : string;
+
+export class WorkflowAgent {
+  private readonly cwd: string;
+  private readonly baseTools: ToolDefinition[];
+  private readonly sessionOptions: Partial<CreateAgentSessionOptions>;
+  private readonly instructions?: string;
+
+  constructor(options: WorkflowAgentOptions = {}) {
+    this.cwd = options.cwd ?? process.cwd();
+    this.baseTools = options.tools ?? createCodingTools(this.cwd);
+    this.sessionOptions = options.session ?? {};
+    this.instructions = options.instructions;
+  }
+
+  async run<TSchemaDef extends TSchema | undefined = undefined>(
+    prompt: string,
+    options: AgentRunOptions<TSchemaDef> = {},
+  ): Promise<AgentRunResult<TSchemaDef>> {
+    const capture: StructuredOutputCapture<any> = { called: false, value: undefined };
+    const customTools: ToolDefinition[] = [...this.baseTools, ...(options.tools ?? [])];
+
+    if (options.schema) {
+      customTools.push(createStructuredOutputTool({ schema: options.schema, capture }) as unknown as ToolDefinition);
+    }
+
+    const agentDir = getAgentDir();
+    const { session } = await createAgentSession({
+      cwd: this.cwd,
+      agentDir,
+      sessionManager: SessionManager.inMemory(),
+      // Use real SettingsManager to inherit user's default provider/model settings.
+      // SettingsManager.inMemory() doesn't load ~/.pi/settings.json, so subagents
+      // would fall back to the first available model (e.g. openai-codex) which may
+      // not have valid auth, causing silent empty responses.
+      settingsManager: SettingsManager.create(this.cwd, agentDir),
+      customTools,
+      ...this.sessionOptions,
+    });
+
+    let removeAbortListener: (() => void) | undefined;
+    try {
+      if (options.signal?.aborted) throw new Error("Subagent was aborted");
+      if (options.signal) {
+        const onAbort = () => void session.abort();
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () => options.signal?.removeEventListener("abort", onAbort);
+      }
+
+      await session.prompt(this.buildPrompt(prompt, options as AgentRunOptions<any>, Boolean(options.schema)));
+      if (options.signal?.aborted) throw new Error("Subagent was aborted");
+
+      if (options.schema) {
+        if (!capture.called) {
+          throw new Error("Subagent finished without calling structured_output");
+        }
+        return capture.value as AgentRunResult<TSchemaDef>;
+      }
+
+      return this.lastAssistantText(session.messages) as AgentRunResult<TSchemaDef>;
+    } finally {
+      removeAbortListener?.();
+      session.dispose();
+    }
+  }
+
+  private buildPrompt(prompt: string, options: AgentRunOptions<any>, structured: boolean): string {
+    const parts = [
+      this.instructions,
+      options.instructions,
+      options.label ? `Task label: ${options.label}` : undefined,
+      prompt,
+    ].filter(Boolean);
+
+    if (structured) {
+      parts.push(
+        [
+          "Final output contract:",
+          "- Your final action MUST be a structured_output tool call.",
+          "- The structured_output arguments are the return value of this subagent.",
+          "- Do not emit a prose final answer instead of structured_output.",
+          "- If you need to inspect files or run commands first, do so, then call structured_output exactly once.",
+        ].join("\n"),
+      );
+    }
+
+    return parts.join("\n\n");
+  }
+
+  private lastAssistantText(messages: unknown[]): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i] as Partial<AssistantMessage> | undefined;
+      if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+      const text = message.content
+        .filter((part): part is TextContent => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+      if (text.trim()) return text;
+    }
+    return "";
+  }
+}

package/src/auto-workflow.ts

@@ -0,0 +1,146 @@
+/**
+ * Auto-workflow mode (ultracode equivalent).
+ * Automatically decides when to use workflows based on task complexity.
+ */
+
+export interface AutoWorkflowConfig {
+  /** Enable auto-workflow mode. */
+  enabled: boolean;
+  /** Minimum number of subtasks to trigger a workflow. */
+  minSubtasks: number;
+  /** Keywords that suggest workflow usage. */
+  triggerKeywords: string[];
+  /** Maximum complexity score before auto-triggering. */
+  complexityThreshold: number;
+}
+
+const DEFAULT_CONFIG: AutoWorkflowConfig = {
+  enabled: false,
+  minSubtasks: 3,
+  triggerKeywords: [
+    "workflow",
+    "parallel",
+    "fan-out",
+    "audit",
+    "migrate",
+    "review",
+    "research",
+    "analyze all",
+    "check every",
+    "sweep",
+    "batch",
+    "bulk",
+  ],
+  complexityThreshold: 7,
+};
+
+/**
+ * Analyze a task description and determine if it should use a workflow.
+ */
+export function shouldUseWorkflow(
+  taskDescription: string,
+  config: Partial<AutoWorkflowConfig> = { enabled: true },
+): { useWorkflow: boolean; confidence: number; reason: string } {
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+
+  if (!cfg.enabled) {
+    return { useWorkflow: false, confidence: 0, reason: "Auto-workflow disabled" };
+  }
+
+  const lower = taskDescription.toLowerCase();
+
+  // Check for explicit workflow keywords
+  const keywordMatches = cfg.triggerKeywords.filter((kw) => lower.includes(kw));
+  if (keywordMatches.length > 0) {
+    return {
+      useWorkflow: true,
+      confidence: Math.min(0.5 + keywordMatches.length * 0.15, 1),
+      reason: `Matched keywords: ${keywordMatches.join(", ")}`,
+    };
+  }
+
+  // Analyze complexity indicators
+  const complexityIndicators = [
+    { pattern: /\b(all|every|each|entire|whole)\b/i, weight: 2 },
+    { pattern: /\b(files?|directories|folders?|modules?|components?|endpoints?)\b/i, weight: 1.5 },
+    { pattern: /\b(parallel|concurrent|simultaneously)\b/i, weight: 2 },
+    { pattern: /\b(review|audit|check|verify|validate)\b/i, weight: 1 },
+    { pattern: /\b(migrate|refactor|update|modify|change)\b/i, weight: 1.5 },
+    { pattern: /\b(research|investigate|analyze|compare)\b/i, weight: 1 },
+    { pattern: /\d+\s*(files?|items?|tasks?|components?)/i, weight: 2 },
+    { pattern: /\b(across|throughout|cross-cutting)\b/i, weight: 1.5 },
+  ];
+
+  let complexityScore = 0;
+  for (const indicator of complexityIndicators) {
+    if (indicator.pattern.test(taskDescription)) {
+      complexityScore += indicator.weight;
+    }
+  }
+
+  // Estimate subtask count
+  const subtaskIndicators = [
+    /\bfirst\b/gi,
+    /\bthen\b/gi,
+    /\bfinally\b/gi,
+    /\bafter\b/gi,
+    /\bnext\b/gi,
+    /\balso\b/gi,
+    /\bstep \d/gi,
+  ];
+
+  let estimatedSubtasks = 1;
+  for (const pattern of subtaskIndicators) {
+    const matches = taskDescription.match(pattern);
+    if (matches) estimatedSubtasks += matches.length;
+  }
+
+  if (complexityScore >= cfg.complexityThreshold || estimatedSubtasks >= cfg.minSubtasks) {
+    return {
+      useWorkflow: true,
+      confidence: Math.min(complexityScore / 10, 1),
+      reason: `Complexity score: ${complexityScore}, estimated subtasks: ${estimatedSubtasks}`,
+    };
+  }
+
+  return {
+    useWorkflow: false,
+    confidence: 0.3,
+    reason: `Below threshold (complexity: ${complexityScore}, subtasks: ${estimatedSubtasks})`,
+  };
+}
+
+/**
+ * Generate a workflow script suggestion from a task description.
+ */
+export function suggestWorkflowScript(taskDescription: string): string {
+  return `export const meta = {
+  name: 'auto_generated',
+  description: '${taskDescription.replace(/'/g, "\\'").slice(0, 100)}',
+  phases: [
+    { title: 'Analyze' },
+    { title: 'Execute' },
+    { title: 'Verify' },
+  ],
+};
+
+phase('Analyze');
+const analysis = await agent(
+  'Analyze this task and break it into subtasks: ${taskDescription.replace(/'/g, "\\'").slice(0, 80)}',
+  { label: 'task analysis' }
+);
+
+phase('Execute');
+const results = await parallel([
+  () => agent('Execute subtask 1 based on: ' + analysis, { label: 'subtask-1' }),
+  // Add more subtasks as needed
+]);
+
+phase('Verify');
+const verification = await agent(
+  'Verify these results are correct: ' + JSON.stringify(results),
+  { label: 'verification' }
+);
+
+return { analysis, results, verification };`;
+}

package/src/config.ts

@@ -0,0 +1,24 @@
+/**
+ * Configuration constants for pi-dynamic-workflows.
+ */
+
+/** Maximum number of agents allowed per workflow run. */
+export const MAX_AGENTS_PER_RUN = 1000;
+
+/** Default timeout for a single agent in milliseconds (5 minutes). */
+export const DEFAULT_AGENT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Maximum concurrent agents (matches Claude Code limit). */
+export const MAX_CONCURRENCY = 16;
+
+/** Default token budget if none specified. */
+export const DEFAULT_TOKEN_BUDGET = null;
+
+/** Directory for persisting workflow run state. */
+export const WORKFLOW_RUNS_DIR = ".pi/workflows/runs";
+
+/** Directory for saved workflow commands. */
+export const WORKFLOW_SAVED_DIR = ".pi/workflows/saved";
+
+/** User-level saved workflows directory. */
+export const USER_WORKFLOW_SAVED_DIR = "~/.pi/workflows/saved";

package/src/deep-research.ts

@@ -0,0 +1,128 @@
+/**
+ * Deep research workflow.
+ * 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;
+}
+
+const DEFAULT_CONFIG: DeepResearchConfig = {
+  searchAngles: 4,
+  sourcesPerAngle: 3,
+  crossCheck: true,
+  maxAgents: 20,
+};
+
+/**
+ * Generate a deep research workflow script.
+ */
+export function generateDeepResearchWorkflow(question: string, config: Partial<DeepResearchConfig> = {}): string {
+  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, " : "";
+
+  return `export const meta = {
+  name: 'deep_research',
+  description: 'Deep research: ${escapedQuestion}',
+  phases: [
+    { title: 'Search Planning' },
+    { title: 'Source Gathering' },
+    { title: 'Cross-Check' },
+    { 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' }
+);
+
+phase('Source Gathering');
+const sources = await parallel(Array.from({ length: ${cfg.searchAngles} }, (_, 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) }
+  )
+));
+
+${crossCheckPhase}
+
+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' }
+);
+
+return { searchPlan, sources, ${crossCheckReturn}report };`;
+}
+
+/**
+ * Generate a codebase audit workflow.
+ */
+export function generateCodebaseAuditWorkflow(scope: string, checks: string[]): string {
+  const escapedScope = scope.replace(/'/g, "\\'").slice(0, 60);
+  const checkAgents = checks
+    .map((check) => {
+      const label = check
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, 20);
+      return `  () => agent('Audit ${check} across: ' + scope, { label: '${label}' }),`;
+    })
+    .join("\n");
+
+  return `export const meta = {
+  name: 'codebase_audit',
+  description: 'Codebase audit: ${escapedScope}',
+  phases: [
+    { title: 'Individual Checks' },
+    { title: 'Cross-Validation' },
+    { title: 'Report' },
+  ],
+};
+
+phase('Individual Checks');
+const scope = '${escapedScope}';
+const findings = await parallel([
+${checkAgents}
+]);
+
+phase('Cross-Validation');
+const validated = await agent(
+  'Cross-validate these audit findings. Remove false positives and confirm real issues:\\n' +
+  JSON.stringify(findings),
+  { label: 'validator' }
+);
+
+phase('Report');
+const report = await agent(
+  'Generate a prioritized audit report with actionable recommendations:\\n' + validated,
+  { label: 'report-writer' }
+);
+
+return { findings, validated, report };`;
+}