@baryonlabs/pi-dynamic-workflows 1.0.2

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@baryonlabs/pi-dynamic-workflows",
+  "version": "1.0.2",
+  "description": "Claude-Code-style dynamic workflow orchestration for Pi (Baryon fork: crash-safe script errors + guarded sandbox).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./workflow": {
+      "types": "./types/workflow.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "extensions/",
+    "src/",
+    "types/",
+    "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"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "workflow",
+    "agents"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/workflow.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baryonlabs/pi-dynamic-workflows.git"
+  },
+  "author": "michaelliv",
+  "license": "MIT",
+  "dependencies": {
+    "acorn": "^8.16.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@earendil-works/pi-ai": "0.78.0",
+    "@earendil-works/pi-coding-agent": "0.78.0",
+    "@earendil-works/pi-tui": "0.78.0",
+    "tsx": "latest",
+    "typebox": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,131 @@
+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(this.cwd),
+      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/display.ts

@@ -0,0 +1,235 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowMeta } from "./workflow.js";
+
+export type WorkflowAgentStatus = "queued" | "running" | "done" | "error" | "skipped";
+
+export interface WorkflowAgentSnapshot {
+  id: number;
+  label: string;
+  phase?: string;
+  prompt: string;
+  status: WorkflowAgentStatus;
+  resultPreview?: string;
+  error?: string;
+}
+
+export interface WorkflowSnapshot {
+  name: string;
+  description?: string;
+  phases: string[];
+  currentPhase?: string;
+  logs: string[];
+  agents: WorkflowAgentSnapshot[];
+  agentCount: number;
+  runningCount: number;
+  doneCount: number;
+  errorCount: number;
+  durationMs?: number;
+  result?: unknown;
+}
+
+export interface WorkflowDisplay {
+  update(snapshot: WorkflowSnapshot): void;
+  complete(snapshot: WorkflowSnapshot): void;
+  clear(): void;
+}
+
+export interface WorkflowDisplayOptions {
+  key?: string;
+  placement?: "aboveEditor" | "belowEditor";
+  maxAgents?: number;
+  maxLogs?: number;
+  showStatus?: boolean;
+  showResultPreviews?: boolean;
+}
+
+export function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot {
+  return {
+    name: meta.name,
+    description: meta.description,
+    phases: [],
+    logs: [],
+    agents: [],
+    agentCount: 0,
+    runningCount: 0,
+    doneCount: 0,
+    errorCount: 0,
+  };
+}
+
+export function recomputeWorkflowSnapshot(snapshot: WorkflowSnapshot): WorkflowSnapshot {
+  const runningCount = snapshot.agents.filter((agent) => agent.status === "running").length;
+  const doneCount = snapshot.agents.filter((agent) => agent.status === "done").length;
+  const errorCount = snapshot.agents.filter((agent) => agent.status === "error").length;
+  return { ...snapshot, agentCount: snapshot.agents.length, runningCount, doneCount, errorCount };
+}
+
+export function createWidgetWorkflowDisplay(
+  ctx: Pick<ExtensionContext, "ui" | "hasUI">,
+  options: WorkflowDisplayOptions = {},
+): WorkflowDisplay {
+  const key = options.key ?? "workflow";
+  const placement = options.placement ?? "belowEditor";
+  const showStatus = options.showStatus ?? false;
+
+  const render = (snapshot: WorkflowSnapshot, completed = false) => {
+    if (!ctx.hasUI) return;
+    if (showStatus) ctx.ui.setStatus(key, statusLine(snapshot, completed));
+    ctx.ui.setWidget(key, renderWorkflowLines(snapshot, options), { placement });
+  };
+
+  return {
+    update(snapshot) {
+      render(snapshot, false);
+    },
+    complete(snapshot) {
+      render(snapshot, true);
+    },
+    clear() {
+      if (!ctx.hasUI) return;
+      if (showStatus) ctx.ui.setStatus(key, undefined);
+      ctx.ui.setWidget(key, undefined);
+    },
+  };
+}
+
+export function createToolUpdateWorkflowDisplay(
+  onUpdate: ((result: { content: Array<{ type: "text"; text: string }>; details: unknown }) => void) | undefined,
+  ctx?: Pick<ExtensionContext, "ui" | "hasUI">,
+  options: WorkflowDisplayOptions & { streamToolUpdates?: boolean } = {},
+): WorkflowDisplay {
+  const widget = ctx ? createWidgetWorkflowDisplay(ctx, options) : undefined;
+  const streamToolUpdates = options.streamToolUpdates ?? !ctx?.hasUI;
+
+  const emit = (snapshot: WorkflowSnapshot, completed = false) => {
+    if (streamToolUpdates) {
+      onUpdate?.({
+        content: [{ type: "text", text: renderWorkflowText(snapshot, completed, options) }],
+        details: snapshot,
+      });
+    }
+    if (completed) widget?.complete(snapshot);
+    else widget?.update(snapshot);
+  };
+
+  return {
+    update(snapshot) {
+      emit(snapshot, false);
+    },
+    complete(snapshot) {
+      emit(snapshot, true);
+    },
+    clear() {
+      widget?.clear();
+    },
+  };
+}
+
+export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: WorkflowDisplayOptions = {}): string[] {
+  const maxAgents = options.maxAgents ?? 8;
+  const maxLogs = options.maxLogs ?? 2;
+  const showResultPreviews = options.showResultPreviews ?? false;
+  const state =
+    snapshot.errorCount > 0
+      ? `, ${snapshot.errorCount} errors`
+      : snapshot.runningCount > 0
+        ? `, ${snapshot.runningCount} running`
+        : "";
+  const lines = [`◆ Workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})`];
+
+  const agentPhaseNames = snapshot.agents
+    .map((agent) => agent.phase)
+    .filter((phase): phase is string => Boolean(phase));
+  const phaseNames = unique([
+    ...snapshot.phases,
+    ...(snapshot.currentPhase ? [snapshot.currentPhase] : []),
+    ...agentPhaseNames,
+  ]);
+  const rendered = new Set<WorkflowAgentSnapshot>();
+
+  for (const phase of phaseNames) {
+    const agents = snapshot.agents.filter((agent) => agent.phase === phase);
+    if (agents.length === 0 && snapshot.currentPhase !== phase) continue;
+    for (const agent of agents) rendered.add(agent);
+    const done = agents.filter((agent) => agent.status === "done").length;
+    const running = agents.filter((agent) => agent.status === "running").length;
+    const errors = agents.filter((agent) => agent.status === "error").length;
+    const skipped = agents.filter((agent) => agent.status === "skipped").length;
+    const complete = agents.length > 0 && done + errors + skipped === agents.length;
+    const marker = running > 0 || (!complete && snapshot.currentPhase === phase) ? "▶" : complete ? "✓" : " ";
+    lines.push(
+      `  ${marker} ${phase} ${done}/${agents.length}${running ? ` · ${running} running` : ""}${errors ? ` · ${errors} errors` : ""}${skipped ? ` · ${skipped} skipped` : ""}`,
+    );
+
+    const visibleAgents = agents.slice(-maxAgents);
+    for (const agent of visibleAgents) {
+      const order = `#${agent.id}`;
+      const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+      lines.push(`    ${order} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${result}`);
+    }
+    if (agents.length > visibleAgents.length)
+      lines.push(`    … ${agents.length - visibleAgents.length} earlier agents`);
+  }
+
+  const unphased = snapshot.agents.filter((agent) => !rendered.has(agent));
+  if (unphased.length) {
+    lines.push("  Unphased");
+    for (const agent of unphased.slice(-maxAgents)) {
+      const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+      lines.push(`    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${result}`);
+    }
+  }
+
+  const visibleLogs = snapshot.logs.slice(-maxLogs);
+  if (visibleLogs.length) {
+    if (lines.length > 1) lines.push("");
+    for (const log of visibleLogs) lines.push(`  log: ${log}`);
+  }
+  return lines;
+}
+
+export function renderWorkflowText(
+  snapshot: WorkflowSnapshot,
+  completed = false,
+  options: WorkflowDisplayOptions = {},
+): string {
+  const header = completed ? "Workflow completed" : "Workflow running";
+  return [header, ...renderWorkflowLines(snapshot, options)].join("\n");
+}
+
+function statusLine(snapshot: WorkflowSnapshot, completed: boolean): string {
+  if (completed) return `workflow ✓ ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount}`;
+  if (snapshot.runningCount > 0)
+    return `workflow ${snapshot.name}: ${snapshot.runningCount} running, ${snapshot.doneCount}/${snapshot.agentCount} done`;
+  return `workflow ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount} done`;
+}
+
+function statusIcon(status: WorkflowAgentStatus): string {
+  switch (status) {
+    case "queued":
+      return "○";
+    case "running":
+      return "●";
+    case "done":
+      return "✓";
+    case "error":
+      return "✗";
+    case "skipped":
+      return "-";
+  }
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function shorten(value: string, max: number): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+export function preview(value: unknown, max = 80): string {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  if (!text) return "";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.js";
+export { WorkflowAgent } from "./agent.js";
+export type {
+  WorkflowAgentSnapshot,
+  WorkflowAgentStatus,
+  WorkflowDisplay,
+  WorkflowDisplayOptions,
+  WorkflowSnapshot,
+} from "./display.js";
+export {
+  createToolUpdateWorkflowDisplay,
+  createWidgetWorkflowDisplay,
+  createWorkflowSnapshot,
+  preview,
+  recomputeWorkflowSnapshot,
+  renderWorkflowLines,
+  renderWorkflowText,
+} from "./display.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 { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
+export { createWorkflowTool } from "./workflow-tool.js";

package/src/structured-output.ts

@@ -0,0 +1,47 @@
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+
+export interface StructuredOutputCapture<T = unknown> {
+  value: T | undefined;
+  called: boolean;
+}
+
+export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
+  schema: TSchemaDef;
+  capture: StructuredOutputCapture<Static<TSchemaDef>>;
+  name?: string;
+}
+
+/**
+ * Create a terminating tool that captures validated params as the subagent result.
+ *
+ * Pi validates `params` against `schema` before execute() is called. Returning
+ * `terminate: true` lets the subagent finish on this tool call without paying for
+ * an extra assistant follow-up turn.
+ */
+export function createStructuredOutputTool<TSchemaDef extends TSchema>({
+  schema,
+  capture,
+  name = "structured_output",
+}: StructuredOutputToolOptions<TSchemaDef>): ToolDefinition<TSchemaDef, Static<TSchemaDef>> {
+  return defineTool({
+    name,
+    label: "Structured Output",
+    description: "Return the final machine-readable result for this subagent task.",
+    promptSnippet: "Return final machine-readable output",
+    promptGuidelines: [
+      `${name} is the final answer channel for this task; call ${name} exactly once when done.`,
+      `Do not write a prose final answer after calling ${name}.`,
+    ],
+    parameters: schema,
+    async execute(_toolCallId, params) {
+      capture.value = params;
+      capture.called = true;
+      return {
+        content: [{ type: "text", text: "Structured output received." }],
+        details: params,
+        terminate: true,
+      };
+    },
+  });
+}