pi-pipelines 0.1.0

package/extensions/subagent-bridge.ts

@@ -0,0 +1,291 @@
+/**
+ * Subagent Bridge — programmatic access to pi-subagents via the event bus
+ *
+ * Uses pi-subagents' internal event bridge to execute subagent tasks
+ * synchronously from within another extension.
+ *
+ * Events used:
+ *   subagent:slash:request   — emit to request subagent execution
+ *   subagent:slash:started   — emitted when execution starts
+ *   subagent:slash:response  — emitted with execution result
+ *   subagent:slash:cancel    — emit to cancel a running subagent
+ *
+ * This approach is cleaner than spawning child Pi processes because:
+ * - It reuses pi-subagents' existing execution pipeline
+ * - Results are returned via the same process (no IPC needed)
+ * - Parallel execution is handled natively
+ * - The extension composes with pi-subagents rather than wrapping it
+ */
+
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Request params expected by pi-subagents' slash bridge */
+interface SubagentSlashParams {
+  agent?: string;
+  task?: string;
+  chain?: SubagentChainStep[];
+  tasks?: SubagentTaskParam[];
+  async?: boolean;
+  clarify?: boolean;
+  context?: "fresh" | "fork";
+  model?: string;
+  output?: string | boolean;
+  agentScope?: string;
+  cwd?: string;
+  skill?: string | string[] | boolean;
+  progress?: boolean;
+  reads?: string[] | boolean;
+  outputMode?: "inline" | "file-only";
+  [key: string]: unknown;
+}
+
+interface SubagentChainStep {
+  agent: string;
+  task?: string;
+  phase?: string;
+  label?: string;
+  as?: string;
+  output?: string | boolean;
+  reads?: string[] | boolean;
+  model?: string;
+  skill?: string | string[] | boolean;
+  progress?: boolean;
+}
+
+interface SubagentTaskParam {
+  agent: string;
+  task: string;
+  output?: string | boolean;
+  reads?: string[] | boolean;
+  model?: string;
+  count?: number;
+}
+
+interface SlashResponse {
+  requestId: string;
+  result: {
+    content: string | Array<{ type: string; text: string }>;
+    details?: {
+      results?: Array<{
+        agent?: string;
+        exitCode?: number;
+        output?: string;
+        sessionFile?: string;
+        progress?: { status: string };
+      }>;
+    };
+    isError?: boolean;
+  };
+  isError: boolean;
+  errorText?: string;
+}
+
+/**
+ * Execute a single subagent task and wait for the result.
+ *
+ * Uses pi-subagents' slash event bridge (fast, same-process).
+ * Falls back to pi.exec() launching a child Pi process if the bridge
+ * is not available (transparent to the caller).
+ */
+export async function executeSubagent(
+  pi: ExtensionAPI,
+  params: SubagentSlashParams,
+  signal?: AbortSignal,
+): Promise<SlashResponse> {
+  // Pipeline stages should never fork the parent session — they are independent tasks.
+  // Explicitly default to "fresh" context to avoid failures when pi-subagents agents
+  // have defaultContext: "fork" but the parent session hasn't been persisted to disk yet.
+  // This affects ALL pipelines, not just the built-in ones.
+  if (params.context === undefined) {
+    params.context = "fresh";
+  }
+
+  // Try the event bridge first
+  try {
+    return await tryBridge(pi, params, signal);
+  } catch (bridgeErr) {
+    const bridgeMessage = (bridgeErr as Error).message;
+
+    // If it's a bridge-unavailable error, try pi.exec() fallback
+    if (bridgeMessage.includes("bridge")) {
+      console.warn(`Bridge unavailable, falling back to pi.exec(): ${bridgeMessage}`);
+      try {
+        return await tryExec(pi, params, signal);
+      } catch (execErr) {
+        throw new Error(
+          `Subagent execution failed (bridge+fallback): ${(execErr as Error).message}`,
+          { cause: execErr },
+        );
+      }
+    }
+
+    throw bridgeErr;
+  }
+}
+
+/**
+ * Event-bridge execution path (same-process, pi-subagents must be loaded).
+ */
+function tryBridge(
+  pi: ExtensionAPI,
+  params: SubagentSlashParams,
+  signal?: AbortSignal,
+): Promise<SlashResponse> {
+  return new Promise((resolve, reject) => {
+    const requestId = randomUUID();
+    let started = false;
+    let done = false;
+
+    const startTimeout = setTimeout(() => {
+      if (!done) cleanup();
+      if (!done) {
+        done = true;
+        reject(new Error("Subagent bridge did not respond within 15s. Is pi-subagents installed?"));
+      }
+    }, 15_000);
+
+    const onStarted = (data: unknown) => {
+      if (done) return;
+      const d = data as { requestId?: string } | undefined;
+      if (d?.requestId !== requestId) return;
+      started = true;
+      clearTimeout(startTimeout);
+    };
+
+    const onResponse = (data: unknown) => {
+      if (done) return;
+      const d = data as SlashResponse | undefined;
+      if (d?.requestId !== requestId) return;
+      cleanup();
+      done = true;
+      resolve(d);
+    };
+
+    const cleanup = () => {
+      clearTimeout(startTimeout);
+      try {
+        unsubStarted?.();
+      } catch {
+        /* ignore */
+      }
+      try {
+        unsubResponse?.();
+      } catch {
+        /* ignore */
+      }
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        cleanup();
+        reject(new Error("Aborted"));
+        return;
+      }
+      signal.addEventListener(
+        "abort",
+        () => {
+          if (!done) {
+            pi.events.emit("subagent:slash:cancel", { requestId });
+            cleanup();
+            done = true;
+            reject(new Error("Aborted"));
+          }
+        },
+        { once: true },
+      );
+    }
+
+    const unsubStarted = pi.events.on("subagent:slash:started", onStarted);
+    const unsubResponse = pi.events.on("subagent:slash:response", onResponse);
+
+    pi.events.emit("subagent:slash:request", { requestId, params });
+
+    // If not started after a microtask tick, bridge didn't respond
+    setTimeout(() => {
+      if (!started && !done) {
+        cleanup();
+        done = true;
+        reject(
+          new Error(
+            "No subagent bridge responded. Ensure pi-subagents is installed (pi install npm:pi-subagents).",
+          ),
+        );
+      }
+    }, 100);
+  });
+}
+
+/**
+ * Fallback: launch a child Pi process to execute the subagent.
+ * Used when the event bridge is not available.
+ */
+async function tryExec(
+  pi: ExtensionAPI,
+  params: SubagentSlashParams,
+  signal?: AbortSignal,
+): Promise<SlashResponse> {
+  const agent = params.agent ?? "worker";
+  const task = params.task ?? "";
+
+  // Build the command
+  const escapedTask = task.replace(/"/g, '\\"');
+  const cmd = `/run ${agent} "${escapedTask}"`;
+
+  const result = await pi.exec("pi", ["-p", cmd], {
+    timeout: 300_000,
+    signal,
+  });
+
+  const output = (result.stdout ?? "").trim();
+  const error = (result.stderr ?? "").trim();
+
+  if (result.code !== 0 && !output) {
+    return {
+      requestId: "",
+      result: { content: error || "(no output)" },
+      isError: true,
+      errorText: error || `Exit code: ${result.code}`,
+    };
+  }
+
+  return {
+    requestId: "",
+    result: { content: output || "(done)" },
+    isError: result.code !== 0,
+    errorText: result.code !== 0 ? error : undefined,
+  };
+}
+
+/**
+ * Extract text content from a subagent response.
+ */
+export function extractResponseText(response: SlashResponse): string {
+  if (response.isError) return response.errorText ?? "(error)";
+
+  const content = response.result?.content;
+  if (typeof content === "string" && content.length > 0) return content;
+  if (Array.isArray(content)) {
+    const texts = content.filter((c) => c.type === "text").map((c) => c.text);
+    if (texts.length > 0) return texts.join("\n");
+  }
+
+  // Try details
+  const details = response.result?.details;
+  if (details?.results?.length) {
+    const outputs = details.results.map((r) => r.output ?? "").filter(Boolean);
+    if (outputs.length > 0) return outputs.join("\n\n");
+  }
+
+  return "(no output)";
+}
+
+/**
+ * Check if pi-subagents is available by probing the event bus.
+ */
+export function isSubagentAvailable(_pi: ExtensionAPI): boolean {
+  // We can probe by emitting a quick test or checking a known event handler
+  // Simple heuristic: check if the slash request event can be emitted
+  // (we can't directly check, but we'll learn from errors)
+  return true; // optimistic — errors surface when trying to execute
+}

package/extensions/tui-widgets.ts

@@ -0,0 +1,68 @@
+/**
+ * TUI Widgets — rendering for pipeline progress and results
+ */
+
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import type { PipelineResult } from "./types.ts";
+import { formatDuration } from "./utils.ts";
+
+export type ThemeAccessor = {
+  fg: (category: string, text: string) => string;
+  bg: (category: string, text: string) => string;
+  bold: (text: string) => string;
+};
+
+/**
+ * Create a TUI component for a pipeline result (used in custom message rendering).
+ */
+export function createPipelineResultComponent(
+  result: PipelineResult,
+  theme: ThemeAccessor,
+): Container {
+  const container = new Container();
+  container.addChild(new Spacer(1));
+
+  // Header
+  const statusIcon = result.success ? "✅" : "❌";
+  const headerText = theme.fg("toolTitle", theme.bold(`Pipeline: ${result.pipelineName}`));
+  container.addChild(
+    new Text(
+      `${headerText} ${theme.fg(result.success ? "success" : "error", `[${statusIcon}]`)}`,
+      0,
+      0,
+    ),
+  );
+  container.addChild(new Text(theme.fg("dim", `Task: ${result.task}`), 0, 0));
+  container.addChild(
+    new Text(theme.fg("dim", `Duration: ${formatDuration(result.totalDurationMs)}`), 0, 0),
+  );
+  container.addChild(new Text("", 0, 0));
+
+  // Stages
+  for (const stage of result.stages) {
+    const icon = stage.success ? theme.fg("success", "✓") : theme.fg("error", "✗");
+    const name = theme.bold(stage.stageId);
+
+    let meta = "";
+    if (stage.rounds) {
+      meta += ` ${theme.fg("dim", `(${stage.rounds}r)`)}`;
+    }
+    if (stage.scores?.length) {
+      meta += ` ${theme.fg("accent", `[${stage.scores.join(",")}]`)}`;
+    }
+    meta += ` ${theme.fg("dim", formatDuration(stage.durationMs))}`;
+
+    container.addChild(new Text(`${icon} ${name}${meta}`, 0, 0));
+
+    if (stage.error) {
+      container.addChild(new Text(theme.fg("error", `  ${stage.error}`), 0, 0));
+    }
+  }
+
+  // Fatal error
+  if (result.error && result.stages.length === 0) {
+    container.addChild(new Text(theme.fg("error", `Fatal: ${result.error}`), 0, 0));
+  }
+
+  return container;
+}

package/extensions/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Core types for the Pipelines extension
+ */
+
+/** A reviewer configuration inside a review gate */
+export interface ReviewerDef {
+  /** What this reviewer should focus on (prompt fragment) */
+  focus: string;
+  /** Optional specific agent to use (defaults to "reviewer") */
+  agent?: string;
+}
+
+/** Controls what output of a stage is passed forward to {outputs.stageId} */
+export interface StageReportConfig {
+  /** How to pass output to next stages:
+   *   'full'    — pass the raw agent output as-is (default)
+   *   'summary' — ask an LLM to summarize before passing forward
+   */
+  mode?: "full" | "summary";
+  /** Max length of the summary in characters (default: 500). Only used when mode='summary'. */
+  maxLength?: number;
+  /** Optional instruction to guide the summarizer. Only used when mode='summary'. */
+  instruction?: string;
+}
+
+/**
+ * Dynamic stage expansion configuration.
+ * Transforms a single stage template into N parallel stages,
+ * one per item from the source stage's output.
+ */
+export interface ExpandConfig {
+  /** ID of the source stage whose output provides the items to expand over */
+  from: string;
+  /** Maximum number of items to expand (default: 10) */
+  maxItems?: number;
+}
+
+/** A review gate that wraps a stage with iterative scoring */
+export interface ReviewGate {
+  type: "review-loop";
+  /** Maximum number of worker → review → fix rounds */
+  maxRounds: number;
+  /** Target score (0-10) that must be met to pass the gate */
+  targetScore: number;
+  /** List of reviewers to run in parallel each round */
+  reviewers: ReviewerDef[];
+  /** Optional model to use for the cross-model judge (different from worker) */
+  judgeModel?: string;
+}
+
+/** A single pipeline stage */
+export interface Stage {
+  /** Unique stage ID (used for output references like {outputs.stageId}) */
+  id: string;
+  /** Agent name to use (e.g. "planner", "worker", "reviewer", "scout") */
+  agent?: string;
+  /** Task description for the agent. Supports {task}, {outputs.stageId}, {lastFeedback} */
+  task?: string;
+  /** If set, run these stages in parallel */
+  parallel?: Stage[];
+  /**
+   * If set, dynamically expand this stage template into N parallel stages,
+   * one per item from the output of stage `expand.from`.
+   * In v1, expanded stages do NOT execute gates — use a separate
+   * parallel/review stage after the expand stage for quality checks.
+   */
+  expand?: ExpandConfig;
+  /** Optional review gate wrapping this stage */
+  gate?: ReviewGate;
+  /** Optional model override for this stage */
+  model?: string;
+  /** Output file for this stage's results */
+  output?: string;
+  /** Files to read before execution */
+  reads?: string[];
+  /** Maximum subagent depth for nested delegation */
+  maxSubagentDepth?: number;
+  /**
+   * Controls what output of this stage is passed forward via {outputs.stageId}.
+   * When undefined or { mode: 'full' }, the raw agent output is used.
+   * When { mode: 'summary' }, the output is summarized before being stored.
+   */
+  report?: StageReportConfig;
+}
+
+/** Configuration for the automatic post-pipeline report synthesizer */
+export interface ReportConfig {
+  /** Agent to use for synthesis (default: "planner") */
+  agent?: string;
+  /** Optional focus area to guide the synthesis prompt */
+  focus?: string;
+}
+
+/** A complete pipeline definition */
+export interface PipelineDef {
+  /** Pipeline name (matches filename without extension) */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Schema version */
+  version?: number;
+  /** Default judge model for review gates (cross-model) */
+  judgeModel?: string;
+  /** Pipeline stages */
+  stages: Stage[];
+  /**
+   * Optional report synthesizer configuration.
+   * When set (or when omitted), a synthesis agent is called after all
+   * stages complete to produce a summary report.
+   * Set to false to disable automatic synthesis.
+   */
+  report?: ReportConfig | false;
+}
+
+/** Runtime state for a single stage execution */
+export interface StageResult {
+  stageId: string;
+  success: boolean;
+  output: string;
+  error?: string;
+  durationMs: number;
+  rounds?: number; // How many review rounds were needed
+  scores?: number[]; // Review scores per round
+  rawOutput?: string; // Full raw output from the subagent
+}
+
+/** Full pipeline execution result */
+export interface PipelineResult {
+  pipelineName: string;
+  task: string;
+  success: boolean;
+  stages: StageResult[];
+  totalDurationMs: number;
+  error?: string;
+  /** Synthesized report from the automatic post-pipeline summary agent */
+  synthesis?: string;
+  /** Error from the synthesis step (synthesis itself can fail without failing the pipeline) */
+  synthesisError?: string;
+}
+
+/** How to execute a stage — resolved from YAML + defaults */
+export interface ResolvedStage {
+  original: Stage;
+  agent: string;
+  task: string;
+  isParallel: boolean;
+  children: ResolvedStage[];
+  gate: ReviewGate | null;
+  model: string | undefined;
+  output: string | undefined;
+  reads: string[] | undefined;
+  maxSubagentDepth: number | undefined;
+}

package/extensions/utils.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared utility functions for pi-pipelines.
+ */
+
+/**
+ * Format a duration in milliseconds into a human-readable string.
+ * @internal Exported for testing. See pipeline-runner.test.ts
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const min = Math.floor(ms / 60000);
+  const sec = ((ms % 60000) / 1000).toFixed(0);
+  return `${min}m ${sec}s`;
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "pi-pipelines",
+  "version": "0.1.0",
+  "description": "Pi extension for defining and running multi-agent pipelines with review gates, loops, and scoring — powered by pi-subagents",
+  "author": "Rybens92",
+  "license": "MIT",
+  "type": "module",
+  "main": "./extensions/index.ts",
+  "exports": {
+    ".": "./extensions/index.ts"
+  },
+  "files": [
+    "extensions/",
+    "pipelines/",
+    "skills/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rybens92/pi-pipelines.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rybens92/pi-pipelines/issues"
+  },
+  "homepage": "https://github.com/Rybens92/pi-pipelines#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pipelines",
+    "orchestration",
+    "workflows"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint extensions/ tests/",
+    "lint:fix": "eslint --fix extensions/ tests/",
+    "format": "prettier --write 'extensions/**/*.ts' 'tests/**/*.ts'",
+    "format:check": "prettier --check 'extensions/**/*.ts' 'tests/**/*.ts'",
+    "check": "pnpm lint && pnpm format:check && pnpm test",
+    "prepublishOnly": "pnpm check"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.2",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.8"
+  }
+}