@baryonlabs/pi-dynamic-workflows 1.0.2

package/src/workflow.ts

@@ -0,0 +1,502 @@
+import vm from "node:vm";
+import type { Node } from "acorn";
+import { parse } from "acorn";
+import type { TSchema } from "typebox";
+import { WorkflowAgent, type WorkflowAgentOptions } from "./agent.js";
+
+export interface WorkflowMetaPhase {
+  title: string;
+  detail?: string;
+  model?: string;
+}
+
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  whenToUse?: string;
+  phases?: WorkflowMetaPhase[];
+}
+
+export interface WorkflowRunOptions extends WorkflowAgentOptions {
+  args?: unknown;
+  agent?: Pick<WorkflowAgent, "run">;
+  concurrency?: number;
+  tokenBudget?: number | null;
+  signal?: AbortSignal;
+  onLog?: (message: string) => void;
+  onPhase?: (title: string) => void;
+  onAgentStart?: (event: { label: string; phase?: string; prompt: string }) => void;
+  onAgentEnd?: (event: { label: string; phase?: string; result: unknown }) => void;
+}
+
+export interface WorkflowRunResult<T = unknown> {
+  meta: WorkflowMeta;
+  result: T;
+  logs: string[];
+  phases: string[];
+  agentCount: number;
+  durationMs: number;
+}
+
+export interface AgentOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined> {
+  label?: string;
+  phase?: string;
+  schema?: TSchemaDef;
+  model?: string;
+  isolation?: "worktree";
+  agentType?: string;
+}
+
+interface RuntimeState {
+  currentPhase?: string;
+  logs: string[];
+  phases: string[];
+  agentCount: number;
+  spent: number;
+}
+
+type AnyNode = Node & { [key: string]: any; start: number; end: number };
+
+const NONDETERMINISM_ERROR =
+  "Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable";
+
+export async function runWorkflow<T = unknown>(
+  script: string,
+  options: WorkflowRunOptions = {},
+): Promise<WorkflowRunResult<T>> {
+  const started = Date.now();
+  const { meta, body } = parseWorkflowScript(script);
+  const state: RuntimeState = { logs: [], phases: [], agentCount: 0, spent: 0 };
+  const agentRunner = options.agent ?? new WorkflowAgent(options);
+  const concurrency = Math.max(
+    1,
+    Math.min(options.concurrency ?? Math.max(1, (globalThis.navigator?.hardwareConcurrency ?? 8) - 2), 16),
+  );
+  const limiter = createLimiter(concurrency);
+  const pendingAgentRuns = new Set<Promise<unknown>>();
+
+  const log = (message: string) => {
+    const text = String(message);
+    state.logs.push(text);
+    options.onLog?.(text);
+  };
+
+  const phase = (title: unknown) => {
+    const text = requireString(title, "phase title");
+    state.currentPhase = text;
+    if (!state.phases.includes(text)) state.phases.push(text);
+    options.onPhase?.(text);
+  };
+
+  const budget = Object.freeze({
+    total: options.tokenBudget ?? null,
+    spent: () => state.spent,
+    remaining: () => (options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - state.spent)),
+  });
+
+  const throwIfAborted = () => {
+    if (options.signal?.aborted) throw new Error("workflow aborted");
+  };
+
+  const agent = async (prompt: unknown, agentOptions: unknown = {}) => {
+    throwIfAborted();
+    if (budget.total !== null && budget.remaining() <= 0) throw new Error("workflow token budget exhausted");
+    const taskPrompt = requireString(prompt, "agent prompt");
+    const normalizedOptions = normalizeAgentOptions(agentOptions);
+    const assignedPhase = normalizedOptions.phase ?? state.currentPhase;
+    const requestedLabel = normalizedOptions.label?.trim();
+    const run = limiter(async () => {
+      state.agentCount++;
+      const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+      options.onAgentStart?.({ label, phase: assignedPhase, prompt: taskPrompt });
+      try {
+        throwIfAborted();
+        const result = await agentRunner.run(taskPrompt, {
+          label,
+          schema: normalizedOptions.schema,
+          signal: options.signal,
+          instructions: buildAgentInstructions(assignedPhase, normalizedOptions),
+        } as any);
+        throwIfAborted();
+        state.spent += estimateTokens(result);
+        options.onAgentEnd?.({ label, phase: assignedPhase, result });
+        return result;
+      } catch (error) {
+        if (options.signal?.aborted) throw error;
+        log(`agent ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+        options.onAgentEnd?.({ label, phase: assignedPhase, result: null });
+        return null;
+      }
+    });
+    pendingAgentRuns.add(run);
+    run.then(
+      () => pendingAgentRuns.delete(run),
+      () => pendingAgentRuns.delete(run),
+    );
+    return run;
+  };
+
+  const parallel = async (thunks: Array<() => Promise<unknown>>) => {
+    throwIfAborted();
+    if (!Array.isArray(thunks)) throw new TypeError("parallel() expects an array of functions");
+    if (thunks.some((thunk) => typeof thunk !== "function")) {
+      throw new TypeError("parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)");
+    }
+    return Promise.all(
+      thunks.map(async (thunk, index) => {
+        try {
+          return await thunk();
+        } catch (error) {
+          if (options.signal?.aborted) throw error;
+          log(`parallel[${index}] failed: ${error instanceof Error ? error.message : String(error)}`);
+          return null;
+        }
+      }),
+    );
+  };
+
+  const pipeline = async (
+    items: unknown[],
+    ...stages: Array<(prev: unknown, original: unknown, index: number) => unknown>
+  ) => {
+    throwIfAborted();
+    if (!Array.isArray(items)) throw new TypeError("pipeline() expects an array as the first argument");
+    if (stages.some((stage) => typeof stage !== "function")) {
+      throw new TypeError("pipeline() stages must be functions: pipeline(items, item => ..., result => ...)");
+    }
+    return Promise.all(
+      items.map(async (item, index) => {
+        let value: unknown = item;
+        for (const stage of stages) {
+          try {
+            throwIfAborted();
+            value = await stage(value, item, index);
+            throwIfAborted();
+          } catch (error) {
+            if (options.signal?.aborted) throw error;
+            log(`pipeline[${index}] failed: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+          }
+        }
+        return value;
+      }),
+    );
+  };
+
+  // Models sometimes hallucinate host APIs inside workflow scripts (bash, fetch,
+  // require, ...). A bare ReferenceError is opaque and, when thrown inside an
+  // un-awaited async call, escapes as an unhandled rejection. Predefine the
+  // usual suspects as guards that throw a descriptive, actionable error instead.
+  const unavailable = (name: string, hint: string) => () => {
+    throw new Error(`${name}() is not available in workflow scripts — ${hint}`);
+  };
+  const shellHint =
+    'delegate shell/file work to a subagent instead, e.g. await agent("run <command> and report the output")';
+  const guards = Object.fromEntries(
+    ["bash", "sh", "shell", "exec", "execSync", "spawn", "spawnSync", "system"].map((name) => [
+      name,
+      unavailable(name, shellHint),
+    ]),
+  );
+  guards.fetch = unavailable("fetch", 'use await agent("fetch <url> and report ...") instead');
+  guards.require = unavailable("require", "workflow scripts have no module system; use agent()/parallel()/pipeline()");
+
+  const context = vm.createContext({
+    ...guards,
+    agent,
+    parallel,
+    pipeline,
+    log,
+    phase,
+    args: options.args,
+    cwd: options.cwd ?? process.cwd(),
+    process: Object.freeze({ cwd: () => options.cwd ?? process.cwd() }),
+    budget,
+    console: {
+      log,
+      info: log,
+      warn: (m: unknown) => log(`[warn] ${String(m)}`),
+      error: (m: unknown) => log(`[error] ${String(m)}`),
+    },
+    JSON,
+    Math,
+    Array,
+    Object,
+    String,
+    Number,
+    Boolean,
+    Set,
+    Map,
+    Promise,
+  });
+
+  const wrapped = `(async () => {\n${body}\n})()`;
+  // A floating rejection inside the script (e.g. an un-awaited `main()` that
+  // throws) bypasses this await and escapes as a process-level unhandled
+  // rejection — killing the HOST process (pi exits, losing the session).
+  // Capture unhandled rejections for the duration of the run and fail the
+  // workflow with them instead, so the error comes back as a tool result.
+  // Node emits `unhandledRejection` at end-of-tick, possibly AFTER the script
+  // resolves — so keep listening one extra event-loop turn before deciding.
+  let floated = false;
+  let floatingReject!: (reason: unknown) => void;
+  const floatingRejection = new Promise<never>((_, reject) => {
+    floatingReject = (reason) => {
+      floated = true;
+      reject(reason instanceof Error ? reason : new Error(String(reason)));
+    };
+  });
+  floatingRejection.catch(() => {}); // avoid the sentinel itself going unhandled
+  const onUnhandled = (reason: unknown) => floatingReject(reason);
+  process.on("unhandledRejection", onUnhandled);
+  let result: unknown;
+  try {
+    const scriptRun = new vm.Script(wrapped, { filename: `${meta.name || "workflow"}.js` }).runInContext(context);
+    result = await Promise.race([scriptRun, floatingRejection]);
+    await Promise.allSettled([...pendingAgentRuns]);
+  } finally {
+    // Late rejections surface on the next tick — absorb them before detaching,
+    // otherwise they'd escape to the process the instant we stop listening.
+    await new Promise((resolve) => setImmediate(resolve));
+    process.off("unhandledRejection", onUnhandled);
+  }
+  if (floated) await floatingRejection; // rethrow the captured floating error
+  assertStructuredCloneable(result, "workflow result");
+  return {
+    meta,
+    result: result as T,
+    logs: state.logs,
+    phases: state.phases,
+    agentCount: state.agentCount,
+    durationMs: Date.now() - started,
+  };
+}
+
+export function parseWorkflowScript(script: string): { meta: WorkflowMeta; body: string } {
+  const ast = parse(script, {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    ranges: false,
+  }) as AnyNode;
+
+  assertDeterministicAst(ast);
+
+  const first = ast.body?.[0] as AnyNode | undefined;
+  if (first?.type !== "ExportNamedDeclaration") {
+    throw new Error("`export const meta = { name, description }` must be the first statement in the script");
+  }
+
+  const declaration = first.declaration as AnyNode | null;
+  if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") {
+    throw new Error("meta export must be `export const meta = ...`");
+  }
+  if (declaration.declarations.length !== 1) {
+    throw new Error("meta export must declare only `meta`");
+  }
+
+  const declarator = declaration.declarations[0] as AnyNode;
+  if (declarator.id?.type !== "Identifier" || declarator.id.name !== "meta") {
+    throw new Error("meta export must declare `meta`");
+  }
+  if (!declarator.init) throw new Error("meta must have a literal value");
+
+  const meta = evaluateLiteral(declarator.init, "meta");
+  validateMeta(meta);
+
+  return {
+    meta,
+    body: script.slice(0, first.start) + script.slice(first.end),
+  };
+}
+
+function evaluateLiteral(node: AnyNode, path: string): unknown {
+  switch (node.type) {
+    case "ObjectExpression": {
+      const out: Record<string, unknown> = {};
+      for (const prop of node.properties as AnyNode[]) {
+        if (prop.type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
+        if (prop.type !== "Property") throw new Error(`only plain properties allowed in ${path}`);
+        if (prop.computed) throw new Error(`computed keys not allowed in ${path}`);
+        if (prop.kind !== "init" || prop.method) throw new Error(`methods/accessors not allowed in ${path}`);
+        const key = propertyKey(prop.key as AnyNode, path);
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+          throw new Error(`reserved key name not allowed in ${path}: ${key}`);
+        }
+        out[key] = evaluateLiteral(prop.value as AnyNode, `${path}.${key}`);
+      }
+      return out;
+    }
+    case "ArrayExpression":
+      return (node.elements as Array<AnyNode | null>).map((element, index) => {
+        if (!element) throw new Error(`sparse arrays not allowed in ${path}`);
+        if (element.type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
+        return evaluateLiteral(element, `${path}[${index}]`);
+      });
+    case "Literal":
+      return node.value;
+    case "TemplateLiteral":
+      if (node.expressions.length > 0) throw new Error(`template interpolation not allowed in ${path}`);
+      return node.quasis.map((quasi: AnyNode) => quasi.value.cooked ?? quasi.value.raw).join("");
+    case "UnaryExpression":
+      if (node.operator === "-" && node.argument?.type === "Literal" && typeof node.argument.value === "number") {
+        return -node.argument.value;
+      }
+      throw new Error(`only negative-number unary allowed in ${path}`);
+    default:
+      throw new Error(`non-literal node type in ${path}: ${node.type}`);
+  }
+}
+
+function propertyKey(node: AnyNode, path: string): string {
+  if (node.type === "Identifier") return node.name;
+  if (node.type === "Literal" && (typeof node.value === "string" || typeof node.value === "number"))
+    return String(node.value);
+  throw new Error(`unsupported key type in ${path}: ${node.type}`);
+}
+
+function assertDeterministicAst(node: AnyNode): void {
+  if (isDateNowCall(node) || isMathRandomCall(node) || isNewDateExpression(node)) {
+    throw new Error(NONDETERMINISM_ERROR);
+  }
+
+  for (const child of astChildren(node)) assertDeterministicAst(child);
+}
+
+function astChildren(node: AnyNode): AnyNode[] {
+  const children: AnyNode[] = [];
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) children.push(...value.filter(isAstNode));
+    else if (isAstNode(value)) children.push(value);
+  }
+  return children;
+}
+
+function isAstNode(value: unknown): value is AnyNode {
+  return !!value && typeof value === "object" && typeof (value as AnyNode).type === "string";
+}
+
+function isDateNowCall(node: AnyNode): boolean {
+  return node.type === "CallExpression" && isMemberExpression(node.callee, "Date", "now");
+}
+
+function isMathRandomCall(node: AnyNode): boolean {
+  return node.type === "CallExpression" && isMemberExpression(node.callee, "Math", "random");
+}
+
+function isNewDateExpression(node: AnyNode): boolean {
+  return node.type === "NewExpression" && node.callee?.type === "Identifier" && node.callee.name === "Date";
+}
+
+function isMemberExpression(node: AnyNode | undefined, objectName: string, propertyName: string): boolean {
+  if (node?.type !== "MemberExpression" || node.object?.type !== "Identifier" || node.object.name !== objectName) {
+    return false;
+  }
+  return propertyNameOf(node) === propertyName;
+}
+
+function propertyNameOf(node: AnyNode): string | undefined {
+  if (!node.computed && node.property?.type === "Identifier") return node.property.name;
+  return staticStringOf(node.property);
+}
+
+function staticStringOf(node: AnyNode | undefined): string | undefined {
+  if (node?.type === "Literal" && typeof node.value === "string") return node.value;
+  if (node?.type === "TemplateLiteral" && node.expressions.length === 0) {
+    return node.quasis.map((quasi: AnyNode) => quasi.value.cooked ?? quasi.value.raw).join("");
+  }
+  if (node?.type === "BinaryExpression" && node.operator === "+") {
+    const left = staticStringOf(node.left);
+    const right = staticStringOf(node.right);
+    if (left !== undefined && right !== undefined) return left + right;
+  }
+  return undefined;
+}
+
+function validateMeta(meta: unknown): asserts meta is WorkflowMeta {
+  if (!meta || typeof meta !== "object") throw new Error("meta must be an object");
+  const value = meta as WorkflowMeta;
+  if (typeof value.name !== "string" || !value.name.trim()) throw new Error("meta.name must be a non-empty string");
+  if (typeof value.description !== "string" || !value.description.trim())
+    throw new Error("meta.description must be a non-empty string");
+  if (value.whenToUse !== undefined && typeof value.whenToUse !== "string")
+    throw new Error("meta.whenToUse must be a string");
+  if (value.phases !== undefined) {
+    if (!Array.isArray(value.phases)) throw new Error("meta.phases must be an array");
+    for (const phase of value.phases) {
+      if (!phase || typeof phase !== "object" || typeof (phase as WorkflowMetaPhase).title !== "string") {
+        throw new Error("each meta phase must have a title string");
+      }
+    }
+  }
+}
+
+function createLimiter(limit: number) {
+  let active = 0;
+  const queue: Array<() => void> = [];
+  const next = () => {
+    active--;
+    queue.shift()?.();
+  };
+  return async <T>(fn: () => Promise<T>): Promise<T> => {
+    if (active >= limit) await new Promise<void>((resolve) => queue.push(resolve));
+    active++;
+    try {
+      return await fn();
+    } finally {
+      next();
+    }
+  };
+}
+
+function requireString(value: unknown, name: string): string {
+  if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+  return value;
+}
+
+function optionalString(value: unknown, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  return requireString(value, name);
+}
+
+function normalizeAgentOptions(value: unknown): AgentOptions {
+  if (!value || typeof value !== "object") throw new TypeError("agent options must be an object");
+  const options = value as AgentOptions;
+  return {
+    ...options,
+    label: optionalString(options.label, "agent label"),
+    phase: optionalString(options.phase, "agent phase"),
+    model: optionalString(options.model, "agent model"),
+    isolation: options.isolation,
+    agentType: optionalString(options.agentType, "agent type"),
+  };
+}
+
+function assertStructuredCloneable(value: unknown, name: string): void {
+  try {
+    structuredClone(value);
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : "";
+    throw new Error(
+      `${name} must be structured-cloneable; did you forget to await agent(), parallel(), or pipeline()?${detail}`,
+    );
+  }
+}
+
+function defaultAgentLabel(phase: string | undefined, index: number): string {
+  return phase ? `${phase} agent ${index}` : `agent ${index}`;
+}
+
+function buildAgentInstructions(phase: string | undefined, options: AgentOptions): string | undefined {
+  const lines = [];
+  if (phase) lines.push(`Workflow phase: ${phase}`);
+  if (options.agentType) lines.push(`Act as workflow subagent type: ${options.agentType}`);
+  if (options.isolation) lines.push(`Requested isolation: ${options.isolation}`);
+  if (options.model) lines.push(`Requested model: ${options.model}`);
+  return lines.length ? lines.join("\n") : undefined;
+}
+
+function estimateTokens(value: unknown): number {
+  return Math.ceil(JSON.stringify(value ?? "").length / 4);
+}

package/types/workflow.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Ambient globals available inside pi-dynamic-workflows workflow scripts.
+ *
+ * Add this to a JavaScript or TypeScript workflow file for editor IntelliSense:
+ *
+ *   /// <reference types="pi-dynamic-workflows/workflow" />
+ */
+
+export {};
+
+declare global {
+  /** Literal workflow metadata. Must be the first statement: `export const meta = { ... }`. */
+  interface WorkflowMeta {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    /** Optional documentation for an expected outline. Live progress is driven by `phase(...)`. */
+    phases?: WorkflowMetaPhase[];
+  }
+
+  interface WorkflowMetaPhase {
+    title: string;
+    detail?: string;
+    model?: string;
+  }
+
+  interface WorkflowAgentOptions<TSchema = JsonSchema> {
+    /** Short label shown in the live progress UI. */
+    label?: string;
+    /** Override the current runtime phase for this agent. */
+    phase?: string;
+    /** JSON Schema for structured output. When present, the returned value is typed as unknown unless you provide a generic. */
+    schema?: TSchema;
+    /** Requested model name. Currently passed as subagent guidance. */
+    model?: string;
+    /** Requested isolation mode. */
+    isolation?: "worktree";
+    /** Requested subagent role/type. */
+    agentType?: string;
+  }
+
+  type JsonPrimitive = string | number | boolean | null;
+  type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+  interface JsonObject {
+    [key: string]: JsonValue;
+  }
+
+  interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema | JsonSchema[];
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    enum?: JsonValue[];
+    const?: JsonValue;
+    description?: string;
+    [key: string]: unknown;
+  }
+
+  interface WorkflowBudget {
+    total: number | null;
+    spent(): number;
+    remaining(): number;
+  }
+
+  /** Spawn a subagent. Returns final text unless a structured-output schema is used with an explicit generic. */
+  function agent<T = string>(prompt: string, options?: WorkflowAgentOptions): Promise<T>;
+
+  /** Run independent async tasks concurrently. Pass functions, not already-created promises. */
+  function parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]>;
+
+  /** Run each item through sequential async stages while different items may run concurrently. */
+  function pipeline<TItem, TResult = unknown>(
+    items: TItem[],
+    ...stages: Array<(previous: unknown, original: TItem, index: number) => TResult | Promise<TResult>>
+  ): Promise<TResult[]>;
+
+  /** Mark the current workflow phase for progress grouping. */
+  function phase(title: string): void;
+
+  /** Append a workflow-level log line. */
+  function log(message: unknown): void;
+
+  /** Optional JSON args passed to the workflow tool. Narrow with a local type assertion when needed. */
+  const args: unknown;
+
+  /** Current working directory for the workflow/subagents. */
+  const cwd: string;
+
+  /** Deterministic process shim exposing only cwd(). */
+  const process: { cwd(): string };
+
+  /** Simple token-budget estimate for workflow runs. */
+  const budget: WorkflowBudget;
+}