@quintinshaw/pi-dynamic-workflows 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# pi-dynamic-workflows
+
+> Claude-Code-style dynamic workflows for [Pi](https://github.com/earendil-works/pi).
+
+A Pi extension that adds a `workflow` tool. Instead of one assistant doing everything sequentially, the model writes a small JavaScript script that fans out the work across many isolated subagents, then synthesizes the results.
+
+Great for codebase audits, multi-perspective review, large refactors, and fan-out research. Inspired by Anthropic's [dynamic workflows in Claude Code](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code).
+
+Fork of [Michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows), updated for `@earendil-works/*` packages with a subagent settings-inheritance fix.
+
+## Install
+
+```bash
+pi install @quintinshaw/pi-dynamic-workflows
+```
+
+Then `/reload` in Pi. The extension registers a `workflow` tool and activates it on session start.
+
+<details>
+<summary>From source (for development)</summary>
+
+```bash
+git clone git@github.com:QuintinShaw/pi-dynamic-workflows.git
+pi install /path/to/pi-dynamic-workflows
+```
+</details>
+
+## Usage
+
+Ask Pi for a workflow in plain language:
+
+```text
+Run a workflow to inspect this repository and summarize the main modules.
+```
+
+The model writes a workflow script and calls the `workflow` tool. Live progress streams inline:
+
+```text
+◆ Workflow: inspect_project (3/3 done · 12,480 tokens)
+  ✓ Scan 1/1
+    #1 ✓ repo inventory
+  ✓ Analyze 2/2
+    #2 ✓ source modules
+    #3 ✓ final summary
+```
+
+Press `Esc` to cancel a running run; active subagents are aborted and surfaced as skipped.
+
+## Workflow script shape
+
+A workflow is plain JavaScript. The first statement must export literal metadata:
+
+```js
+export const meta = {
+  name: 'inspect_project',
+  description: 'Inspect a repository and summarize the main modules',
+  phases: [{ title: 'Scan' }, { title: 'Analyze' }],
+}
+
+phase('Scan')
+const inventory = await agent('Inspect the repository structure.', { label: 'repo inventory' })
+
+phase('Analyze')
+const summary = await agent('Summarize the main modules:\n' + inventory, { label: 'module summary' })
+
+return { inventory, summary }
+```
+
+### Globals
+
+| Global | Description |
+| --- | --- |
+| `agent(prompt, opts)` | Spawn an isolated subagent. Returns its final text, or a validated object with `opts.schema`. |
+| `parallel(thunks)` | Run an array of `() => agent(...)` thunks concurrently. Results returned in input order. |
+| `pipeline(items, ...stages)` | Fan items out through sequential stages. Each stage receives `(prev, original, index)`. |
+| `phase(title)` | Mark the current phase for the live progress view. |
+| `log(message)` | Append a workflow-level log line. |
+| `args` | Optional JSON value passed via the tool's `args` parameter. |
+| `budget` | `{ total, spent(), remaining() }` token-budget tracker. |
+| `cwd`, `process.cwd()` | Working directory for subagents. |
+
+### Agent options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `label` | string | Human-readable label for progress display |
+| `phase` | string | Override the current phase for this agent |
+| `schema` | object | JSON Schema for structured output |
+| `timeoutMs` | number | Override the default 5-minute agent timeout |
+
+### Structured output
+
+Pass a JSON Schema via `opts.schema` and the subagent returns a validated object:
+
+```js
+const finding = await agent('Find security-sensitive files.', {
+  label: 'security scan',
+  schema: {
+    type: 'object',
+    properties: {
+      paths: { type: 'array', items: { type: 'string' } },
+      reason: { type: 'string' },
+    },
+    required: ['paths', 'reason'],
+  },
+})
+```
+
+Backed by a Pi `structured_output` tool with `terminate: true`, so the subagent ends on that call.
+
+### Determinism rules
+
+Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`, `new Date()`, `Math.random()`, `require`/`import`/`fs`/network, and (inside `meta`) spreads, computed keys, template interpolation, and function calls. This keeps `meta` parseable and runs reproducible.
+
+## What works today
+
+- **Core runtime** — `agent` / `parallel` / `pipeline` / `phase` / `log` / `budget` in a sandboxed script
+- **Structured output** — JSON-Schema-validated subagent results
+- **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
+- **Live progress + token display**, `Esc` to abort
+- **Log persistence** to `.pi/workflows/runs/`
+
+## Roadmap
+
+Tracked toward closer parity with Claude Code dynamic workflows:
+
+- **Real per-agent / per-phase model routing** (`opts.model`, `meta.phases[].model`)
+- **Real token accounting** via the SDK's session stats (today's display uses an estimate)
+- **Command surface** — `/workflows` (list / status / stop) and reachable background runs
+- **Resume** — journaled results, replay the unchanged prefix, run the rest live
+- **Worktree isolation** for parallel edits, and **bundled `/deep-research`**
+- **Saved workflows** as `/<name>` slash commands
+
+## How it works
+
+```text
+user prompt
+  → Pi model writes a workflow script
+  → workflow tool parses + runs it in a vm sandbox
+  → script calls agent() / parallel() / pipeline()
+  → each agent() spawns a fresh in-memory Pi subagent session
+  → snapshots stream back as compact progress
+  → final structured result returns to the parent assistant
+```
+
+Subagents run in fresh in-memory Pi sessions with the standard coding tools (read, bash, edit, write, grep, find, ls), so they work exactly like a normal Pi turn.
+
+## Development
+
+```bash
+npm install
+npm test     # biome check + tsc + unit tests
+```
+
+Parser unit tests live in `tests/workflow-parser.test.ts`.
+
+## License
+
+MIT

package/dist/adversarial-review.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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;
+}
+/**
+ * Generate an adversarial review workflow script.
+ */
+export declare function generateAdversarialReviewWorkflow(taskDescription: string, config?: Partial<AdversarialReviewConfig>): string;
+/**
+ * Generate a multi-perspective analysis workflow.
+ */
+export declare function generateMultiPerspectiveWorkflow(topic: string, perspectives: string[]): string;

package/dist/adversarial-review.js

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+export function generateAdversarialReviewWorkflow(taskDescription, config = {}) {
+    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, perspectives) {
+    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/dist/agent.d.ts

@@ -0,0 +1,29 @@
+import { type CreateAgentSessionOptions, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+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 declare class WorkflowAgent {
+    private readonly cwd;
+    private readonly baseTools;
+    private readonly sessionOptions;
+    private readonly instructions?;
+    constructor(options?: WorkflowAgentOptions);
+    run<TSchemaDef extends TSchema | undefined = undefined>(prompt: string, options?: AgentRunOptions<TSchemaDef>): Promise<AgentRunResult<TSchemaDef>>;
+    private buildPrompt;
+    private lastAssistantText;
+}

package/dist/agent.js

@@ -0,0 +1,90 @@
+import { createAgentSession, createCodingTools, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createStructuredOutputTool } from "./structured-output.js";
+export class WorkflowAgent {
+    cwd;
+    baseTools;
+    sessionOptions;
+    instructions;
+    constructor(options = {}) {
+        this.cwd = options.cwd ?? process.cwd();
+        this.baseTools = options.tools ?? createCodingTools(this.cwd);
+        this.sessionOptions = options.session ?? {};
+        this.instructions = options.instructions;
+    }
+    async run(prompt, options = {}) {
+        const capture = { called: false, value: undefined };
+        const customTools = [...this.baseTools, ...(options.tools ?? [])];
+        if (options.schema) {
+            customTools.push(createStructuredOutputTool({ schema: options.schema, capture }));
+        }
+        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;
+        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, 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;
+            }
+            return this.lastAssistantText(session.messages);
+        }
+        finally {
+            removeAbortListener?.();
+            session.dispose();
+        }
+    }
+    buildPrompt(prompt, options, structured) {
+        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");
+    }
+    lastAssistantText(messages) {
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const message = messages[i];
+            if (message?.role !== "assistant" || !Array.isArray(message.content))
+                continue;
+            const text = message.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("");
+            if (text.trim())
+                return text;
+        }
+        return "";
+    }
+}

package/dist/auto-workflow.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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;
+}
+/**
+ * Analyze a task description and determine if it should use a workflow.
+ */
+export declare function shouldUseWorkflow(taskDescription: string, config?: Partial<AutoWorkflowConfig>): {
+    useWorkflow: boolean;
+    confidence: number;
+    reason: string;
+};
+/**
+ * Generate a workflow script suggestion from a task description.
+ */
+export declare function suggestWorkflowScript(taskDescription: string): string;

package/dist/auto-workflow.js

@@ -0,0 +1,121 @@
+/**
+ * Auto-workflow mode (ultracode equivalent).
+ * Automatically decides when to use workflows based on task complexity.
+ */
+const DEFAULT_CONFIG = {
+    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, config = { enabled: true }) {
+    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) {
+    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/dist/config.d.ts

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

package/dist/config.js

@@ -0,0 +1,17 @@
+/**
+ * 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/dist/deep-research.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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;
+}
+/**
+ * Generate a deep research workflow script.
+ */
+export declare function generateDeepResearchWorkflow(question: string, config?: Partial<DeepResearchConfig>): string;
+/**
+ * Generate a codebase audit workflow.
+ */
+export declare function generateCodebaseAuditWorkflow(scope: string, checks: string[]): string;