@quintinshaw/pi-dynamic-workflows 1.0.0

package/src/workflow-tool.ts

@@ -0,0 +1,254 @@
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+  createToolUpdateWorkflowDisplay,
+  createWorkflowSnapshot,
+  preview,
+  recomputeWorkflowSnapshot,
+  renderWorkflowText,
+  type WorkflowSnapshot,
+} from "./display.js";
+import { WorkflowError, WorkflowErrorCode } from "./errors.js";
+import { parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
+import { WorkflowManager } from "./workflow-manager.js";
+import { createWorkflowStorage } from "./workflow-saved.js";
+
+const workflowToolSchema = Type.Object({
+  script: Type.String({
+    description: [
+      "Required raw JavaScript workflow script, with no Markdown fences.",
+      "First statement: export const meta = { name: 'short_snake_case', description: 'non-empty description', phases: [{ title: 'Phase' }] }",
+      "Use phase('Name'), agent(prompt, opts), parallel(arrayOfFunctions), pipeline(items, ...stages), log(message), args, and budget. The workflow must call agent() at least once.",
+      "parallel() requires functions, not promises: await parallel(items.map(item => () => agent(...))).",
+    ].join(" "),
+  }),
+  args: Type.Optional(
+    Type.Any({ description: "Optional JSON value exposed to the workflow script as global `args`." }),
+  ),
+  background: Type.Optional(
+    Type.Boolean({
+      description: "Run the workflow in the background. Default: false. When true, returns immediately with a run ID.",
+    }),
+  ),
+  maxAgents: Type.Optional(
+    Type.Number({
+      description: "Maximum number of agents allowed in this run. Default: 1000.",
+    }),
+  ),
+  agentTimeoutMs: Type.Optional(
+    Type.Number({
+      description: "Timeout per agent in milliseconds. Default: 300000 (5 minutes).",
+    }),
+  ),
+});
+
+export type WorkflowToolInput = {
+  script: string;
+  args?: unknown;
+  background?: boolean;
+  maxAgents?: number;
+  agentTimeoutMs?: number;
+};
+
+export interface WorkflowToolOptions {
+  cwd?: string;
+  concurrency?: number;
+}
+
+export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefinition<typeof workflowToolSchema, any> {
+  const manager = new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
+  const _storage = createWorkflowStorage(options.cwd ?? process.cwd());
+
+  return defineTool({
+    name: "workflow",
+    label: "Workflow",
+    description: [
+      "Execute a deterministic JavaScript workflow that orchestrates multiple subagents with agent(), parallel(), and pipeline().",
+      "script is required raw JavaScript. It must start with export const meta = { name, description, phases? } and must call agent() at least once.",
+    ].join(" "),
+    promptSnippet:
+      "Run a deterministic JavaScript workflow. Required script header: export const meta = { name: 'short_snake_case', description: 'non-empty description', phases: [{ title: 'Phase' }] }.",
+    promptGuidelines: [
+      "Use workflow only when the user explicitly asks for a workflow, workflows, fan-out, or multi-agent orchestration.",
+      "For workflow, always pass one raw JavaScript string in the required script parameter; do not include Markdown fences or prose around the script.",
+      "For workflow, the script's first statement must be `export const meta = { name: 'short_snake_case', description: 'non-empty human description', phases: [{ title: 'Phase name' }] }`; meta.name and meta.description are required non-empty strings.",
+      "For workflow, write plain JavaScript after the meta export. Do not use TypeScript syntax, imports, require(), fs, Date.now(), Math.random(), or new Date().",
+      "For workflow, available globals are agent(prompt, opts), parallel(thunks), pipeline(items, ...stages), phase(title), log(message), args, cwd, process.cwd(), and budget. Every workflow must call agent() at least once; do not use workflow only to declare phases or return a static object.",
+      "For workflow, prefer it for decomposable work: repository inspection, independent research/checks, multi-perspective review, or fan-out/fan-in synthesis. Do not use it for a single quick file read/edit or when ordinary tools are enough.",
+      "For workflow, parallel() takes functions, not promises: use `await parallel(items.map(item => () => agent('...', { label: '...' })))`, never `await parallel(items.map(item => agent(...)))`. Results are returned in input order.",
+      "For workflow, pipeline(items, ...stages) runs each item through stages sequentially, while different items may run concurrently. Each stage receives (previousValue, originalItem, index).",
+      "For workflow, every agent() call should include a unique short label option, 2-5 words, such as { label: 'repo inventory' } or { label: 'source modules' }; unique labels make live status and error reporting readable.",
+      "For workflow, failed agent(), parallel(), or pipeline() branches return null and log the failure unless the workflow is aborted. Check for nulls before synthesizing conclusions.",
+      "For workflow, include a final synthesis/assertion agent when combining multiple subagent results; return a compact JSON-serializable value with ok/verdict plus the important outputs.",
+      "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
+      "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
+      "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+    ],
+    parameters: workflowToolSchema,
+    prepareArguments(args) {
+      return normalizeWorkflowToolArgs(args);
+    },
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const script = normalizeWorkflowScript(params.script);
+      const parsed = parseWorkflowScript(script);
+
+      // Background execution
+      if (params.background) {
+        const { runId } = manager.startInBackground(script, params.args);
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Workflow "${parsed.meta.name}" started in background.`,
+                `Run ID: ${runId}`,
+                `Use /workflow status ${runId} to check progress.`,
+                `Use /workflow stop ${runId} to cancel.`,
+              ].join("\n"),
+            },
+          ],
+          details: { runId, background: true },
+        };
+      }
+
+      // Synchronous execution (blocking)
+      let snapshot: WorkflowSnapshot = createWorkflowSnapshot(parsed.meta);
+      const display = createToolUpdateWorkflowDisplay(onUpdate, undefined, {
+        key: "workflow",
+        streamToolUpdates: true,
+        maxAgents: 4,
+        maxLogs: 1,
+        showResultPreviews: false,
+      });
+
+      const update = () => {
+        snapshot = recomputeWorkflowSnapshot(snapshot);
+        display.update(snapshot);
+      };
+
+      let result: WorkflowRunResult;
+      try {
+        result = await runWorkflow(script, {
+          cwd: options.cwd ?? ctx.cwd,
+          args: params.args,
+          signal,
+          concurrency: options.concurrency,
+          maxAgents: params.maxAgents,
+          agentTimeoutMs: params.agentTimeoutMs,
+          onLog(message) {
+            snapshot.logs.push(message);
+            update();
+          },
+          onPhase(title) {
+            snapshot.currentPhase = title;
+            if (!snapshot.phases.includes(title)) snapshot.phases.push(title);
+            update();
+          },
+          onAgentStart(event) {
+            if (signal?.aborted) throw new Error("Workflow was aborted");
+            snapshot.agents.push({
+              id: snapshot.agents.length + 1,
+              label: event.label,
+              phase: event.phase,
+              prompt: event.prompt,
+              status: "running",
+            });
+            update();
+          },
+          onAgentEnd(event) {
+            const agent = [...snapshot.agents]
+              .reverse()
+              .find((item) => item.label === event.label && item.status === "running");
+            if (agent) {
+              agent.status = event.result === null ? "error" : "done";
+              agent.resultPreview = preview(event.result);
+              agent.tokens = event.tokens;
+            }
+            update();
+          },
+          onTokenUsage(usage) {
+            snapshot.tokenUsage = usage;
+            update();
+          },
+        });
+      } catch (error) {
+        if (signal?.aborted || (error instanceof WorkflowError && error.code === WorkflowErrorCode.WORKFLOW_ABORTED)) {
+          for (const agent of snapshot.agents) {
+            if (agent.status === "running") {
+              agent.status = "skipped";
+              agent.error = "aborted";
+            }
+          }
+          snapshot = recomputeWorkflowSnapshot(snapshot);
+          display.complete(snapshot);
+          throw new Error("Workflow was aborted");
+        }
+        throw error;
+      }
+
+      if (result.agentCount === 0) {
+        throw new Error(
+          "workflow scripts must call agent() at least once; this workflow declared phases but did not run any subagents",
+        );
+      }
+
+      snapshot.result = result.result;
+      snapshot.durationMs = result.durationMs;
+      snapshot = recomputeWorkflowSnapshot(snapshot);
+      display.complete(snapshot);
+
+      // Format token usage
+      const tokenInfo = result.tokenUsage ? `\n\nToken usage: ${result.tokenUsage.total.toLocaleString()} tokens` : "";
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Workflow ${result.meta.name} completed with ${result.agentCount} agent(s).\n\nResult:\n${JSON.stringify(result.result, null, 2)}${tokenInfo}`,
+          },
+        ],
+        details: {
+          ...snapshot,
+          meta: result.meta,
+          phases: result.phases,
+          logs: result.logs,
+          result: result.result,
+          durationMs: result.durationMs,
+          tokenUsage: result.tokenUsage,
+          runId: result.runId,
+        },
+      };
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("workflow")), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme) {
+      const snapshot = result.details as WorkflowSnapshot | undefined;
+      if (snapshot?.name) {
+        return new Text(renderWorkflowText(snapshot, !isPartial), 0, 0);
+      }
+      const text = result.content?.[0];
+      return new Text(text?.type === "text" ? text.text : theme.fg("muted", "workflow"), 0, 0);
+    },
+  });
+}
+
+function normalizeWorkflowToolArgs(args: unknown): WorkflowToolInput {
+  if (!args || typeof args !== "object") throw new Error("workflow requires an object argument with a script string");
+  const value = args as Record<string, unknown>;
+  if (typeof value.script !== "string") throw new Error("workflow requires `script` to be a string");
+  return { ...value, script: normalizeWorkflowScript(value.script) } as WorkflowToolInput;
+}
+
+function normalizeWorkflowScript(script: string): string {
+  let text = script.trim();
+  const fence = text.match(/^```(?:js|javascript)?\s*\n([\s\S]*?)\n```$/i);
+  if (fence) text = fence[1].trim();
+  return text;
+}
+
+function _isAbortError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return /\babort(?:ed)?\b/i.test(error.message);
+}