@osolmaz/pi-workflows 0.1.0

package/src/workflows/errors.ts

@@ -0,0 +1,27 @@
+export class TimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    super(`Timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export class CancelledError extends Error {
+  constructor(message = "Workflow run was cancelled") {
+    super(message);
+    this.name = "CancelledError";
+  }
+}
+
+export function isAbortLikeError(error: unknown): boolean {
+  return error instanceof CancelledError || (error instanceof Error && error.name === "AbortError");
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/workflows/graph.ts

@@ -0,0 +1,161 @@
+import { assertValidWorkflowDefinitionShape } from "./schema.js";
+import type { WorkflowDefinition, WorkflowEdge, WorkflowNodeResult } from "./types.js";
+
+/**
+ * Validate the full graph: shape, known start node, known edge targets, and
+ * at most one outgoing edge per node.
+ */
+export function validateWorkflowDefinition(workflow: WorkflowDefinition): void {
+  assertValidWorkflowDefinitionShape(workflow);
+  if (!Object.hasOwn(workflow.nodes, workflow.startAt)) {
+    throw new Error(`Workflow start node is missing: ${workflow.startAt}`);
+  }
+
+  const outgoingEdges = new Set<string>();
+  for (const edge of workflow.edges) {
+    validateWorkflowEdge(workflow, edge, outgoingEdges);
+  }
+
+  assertAllNodesReachable(workflow);
+}
+
+/** Reject nodes that no path from `startAt` can ever reach. */
+function assertAllNodesReachable(workflow: WorkflowDefinition): void {
+  const reachable = new Set<string>([workflow.startAt]);
+  const queue = [workflow.startAt];
+  while (queue.length > 0) {
+    const nodeId = queue.shift() as string;
+    for (const edge of workflow.edges) {
+      if (edge.from !== nodeId) {
+        continue;
+      }
+      const targets = "to" in edge ? [edge.to] : Object.values(edge.switch.cases);
+      for (const target of targets) {
+        if (!reachable.has(target)) {
+          reachable.add(target);
+          queue.push(target);
+        }
+      }
+    }
+  }
+  const unreachable = Object.keys(workflow.nodes).filter((nodeId) => !reachable.has(nodeId));
+  if (unreachable.length > 0) {
+    throw new Error(`Workflow has unreachable nodes: ${unreachable.join(", ")}`);
+  }
+}
+
+function assertKnownNode(workflow: WorkflowDefinition, nodeId: string, description: string): void {
+  // Own-property check so ids like "toString" cannot resolve through the
+  // Object prototype and later dispatch an inherited function as a node.
+  if (!Object.hasOwn(workflow.nodes, nodeId)) {
+    throw new Error(`${description}: ${nodeId}`);
+  }
+}
+
+function validateWorkflowEdge(
+  workflow: WorkflowDefinition,
+  edge: WorkflowEdge,
+  outgoingEdges: Set<string>,
+): void {
+  assertKnownNode(workflow, edge.from, "Workflow edge references unknown from-node");
+  if (workflow.nodes[edge.from]?.nodeType === "checkpoint") {
+    // A checkpoint terminates the run as `waiting` and nothing resumes it,
+    // so an outgoing edge would make its targets silently unreachable.
+    throw new Error(`Workflow checkpoint node must not declare an outgoing edge: ${edge.from}`);
+  }
+  if (outgoingEdges.has(edge.from)) {
+    throw new Error(`Workflow node must not declare multiple outgoing edges: ${edge.from}`);
+  }
+  outgoingEdges.add(edge.from);
+
+  if ("to" in edge) {
+    assertKnownNode(workflow, edge.to, "Workflow edge references unknown to-node");
+    return;
+  }
+
+  for (const target of Object.values(edge.switch.cases)) {
+    assertKnownNode(workflow, target, "Workflow switch references unknown to-node");
+  }
+}
+
+/**
+ * Resolve the next node after `from` completed with `output`. Switch edges
+ * route on a JSON path into the output (`$.field` or `$output.field`) or the
+ * node result (`$result.outcome`).
+ */
+export function resolveNext(
+  edges: WorkflowEdge[],
+  from: string,
+  output: unknown,
+  result?: WorkflowNodeResult,
+): string | null {
+  const edge = edges.find((candidate) => candidate.from === from);
+  if (!edge) {
+    return null;
+  }
+  if ("to" in edge) {
+    return edge.to;
+  }
+  return resolveSwitchTarget(edge, output, result);
+}
+
+/**
+ * Resolve routing for a failed node. Only `$result.` switch edges apply, so a
+ * workflow can explicitly route on outcomes like `failed` or `timed_out`.
+ */
+export function resolveNextForOutcome(
+  edges: WorkflowEdge[],
+  from: string,
+  result: WorkflowNodeResult,
+): string | null {
+  const edge = edges.find((candidate) => candidate.from === from);
+  if (!edge || "to" in edge || !edge.switch.on.startsWith("$result.")) {
+    return null;
+  }
+  return resolveSwitchTarget(edge, undefined, result);
+}
+
+function resolveSwitchTarget(
+  edge: Extract<WorkflowEdge, { switch: unknown }>,
+  output: unknown,
+  result: WorkflowNodeResult | undefined,
+): string {
+  const value = getBySwitchPath(output, result, edge.switch.on);
+  if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+    throw new Error(`Workflow switch value must be scalar for ${edge.switch.on}`);
+  }
+  const next = edge.switch.cases[String(value)];
+  if (!next) {
+    throw new Error(`No workflow switch case for ${edge.switch.on}=${JSON.stringify(value)}`);
+  }
+  return next;
+}
+
+function getBySwitchPath(
+  output: unknown,
+  result: WorkflowNodeResult | undefined,
+  jsonPath: string,
+): unknown {
+  if (jsonPath.startsWith("$result.")) {
+    return getByPath(result, `$.${jsonPath.slice("$result.".length)}`);
+  }
+  if (jsonPath.startsWith("$output.")) {
+    return getByPath(output, `$.${jsonPath.slice("$output.".length)}`);
+  }
+  return getByPath(output, jsonPath);
+}
+
+function getByPath(value: unknown, jsonPath: string): unknown {
+  if (!jsonPath.startsWith("$.")) {
+    throw new Error(`Unsupported JSON path: ${jsonPath}`);
+  }
+  return jsonPath
+    .slice(2)
+    .split(".")
+    .reduce((current: unknown, key) => {
+      if (current == null || typeof current !== "object") {
+        return undefined;
+      }
+      return (current as Record<string, unknown>)[key];
+    }, value);
+}

package/src/workflows/index.ts

@@ -0,0 +1,76 @@
+export {
+  agent,
+  action,
+  checkpoint,
+  compute,
+  defineWorkflow,
+  isWorkflowDefinition,
+  shell,
+} from "./definition.js";
+export { decision, decisionEdge, type DecisionDefinition } from "./decision.js";
+export { WorkflowEngine, appendStepContract } from "./engine.js";
+export { CancelledError, TimeoutError } from "./errors.js";
+export {
+  extractJsonValue,
+  parseJsonValue,
+  parseStrictJsonValue,
+  type JsonParseMode,
+} from "./json.js";
+export { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
+export {
+  discoverWorkflows,
+  loadWorkflowFile,
+  resolveWorkflowRef,
+  workflowFileStem,
+  workflowSearchDirs,
+  type DiscoveredWorkflow,
+  type WorkflowSearchPaths,
+} from "./loader.js";
+export { renderShellCommand, runShellAction } from "./shell.js";
+export { sanitizeText, stripAnsi } from "./text.js";
+export {
+  DEFINITION_SNAPSHOT_SCHEMA,
+  RUN_BUNDLE_SCHEMA,
+  TRACE_EVENT_SCHEMA,
+  WorkflowRunStore,
+  createDefinitionSnapshot,
+  createRunId,
+  listRunBundles,
+  readRunBundle,
+  workflowRunsBaseDir,
+  type LoadedRunBundle,
+} from "./store.js";
+export type {
+  AgentNodeDefinition,
+  AgentStepContract,
+  AgentStepExecutor,
+  AgentStepRequest,
+  AgentStepSubmission,
+  ActionNodeDefinition,
+  CheckpointNodeDefinition,
+  ComputeNodeDefinition,
+  FunctionActionNodeDefinition,
+  MaybePromise,
+  ShellActionExecution,
+  ShellActionNodeDefinition,
+  ShellActionResult,
+  WorkflowActionReceipt,
+  WorkflowDefinition,
+  WorkflowDefinitionSnapshot,
+  WorkflowEdge,
+  WorkflowEngineOptions,
+  WorkflowNodeCommon,
+  WorkflowNodeContext,
+  WorkflowNodeDefinition,
+  WorkflowNodeOutcome,
+  WorkflowNodeResult,
+  WorkflowNodeSnapshot,
+  WorkflowPresentationContext,
+  WorkflowRunManifest,
+  WorkflowRunResult,
+  WorkflowRunState,
+  WorkflowRunStatus,
+  WorkflowStepRecord,
+  WorkflowTraceEvent,
+  WorkflowTraceEventDraft,
+} from "./types.js";

package/src/workflows/json.ts

@@ -0,0 +1,155 @@
+export type JsonParseMode = "strict" | "fenced" | "compat";
+
+type ParseAttempt = { ok: true; value: unknown } | { ok: false };
+
+/**
+ * Parse a JSON value out of model text. `strict` requires the whole text to
+ * be JSON. `fenced` additionally accepts a ```json fenced block. `compat`
+ * (the default) also scans for the first balanced JSON object or array
+ * embedded in chatty output.
+ */
+export function parseJsonValue(text: string, options: { mode?: JsonParseMode } = {}): unknown {
+  const trimmed = typeof text === "string" ? text.trim() : "";
+  if (!trimmed) {
+    throw new Error("Expected JSON output, got empty text");
+  }
+  const mode = options.mode ?? "compat";
+
+  const direct = tryParse(trimmed);
+  if (direct.ok) {
+    return direct.value;
+  }
+
+  if (mode === "fenced" || mode === "compat") {
+    const fencedText = extractFencedJsonText(trimmed);
+    if (fencedText !== null) {
+      const fenced = tryParse(fencedText);
+      if (fenced.ok) {
+        return fenced.value;
+      }
+    }
+  }
+
+  if (mode === "compat") {
+    for (const candidate of extractBalancedJsonCandidates(trimmed)) {
+      const parsed = tryParse(candidate);
+      if (parsed.ok) {
+        return parsed.value;
+      }
+    }
+  }
+
+  throw new Error(`Could not parse JSON from text:\n${trimmed}`);
+}
+
+/** Strict parse: the whole text must be a JSON value. */
+export function parseStrictJsonValue(text: string): unknown {
+  return parseJsonValue(text, { mode: "strict" });
+}
+
+/** Default tolerant parser: direct JSON, then fenced, then embedded object. */
+export function extractJsonValue(text: string): unknown {
+  return parseJsonValue(text, { mode: "compat" });
+}
+
+function tryParse(text: string): ParseAttempt {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function extractFencedJsonText(text: string): string | null {
+  const openingFenceIndex = text.indexOf("```");
+  if (openingFenceIndex === -1) {
+    return null;
+  }
+
+  let contentStart = openingFenceIndex + 3;
+  if (
+    text.slice(contentStart, contentStart + 4).toLowerCase() === "json" &&
+    isFenceWhitespace(text[contentStart + 4])
+  ) {
+    contentStart += 4;
+  }
+  while (isFenceWhitespace(text[contentStart])) {
+    contentStart += 1;
+  }
+
+  const closingFenceIndex = text.indexOf("```", contentStart);
+  if (closingFenceIndex === -1) {
+    return null;
+  }
+  return text.slice(contentStart, closingFenceIndex).trim();
+}
+
+function isFenceWhitespace(char: string | undefined): boolean {
+  return char === " " || char === "\n" || char === "\r" || char === "\t";
+}
+
+// Bound on balanced-scan attempts. Without it, pathological text such as
+// twenty thousand opening braces makes candidate extraction quadratic and
+// blocks the event loop, which also prevents node timeouts from firing.
+const MAX_CANDIDATE_SCANS = 64;
+
+function extractBalancedJsonCandidates(text: string): string[] {
+  const candidates: string[] = [];
+  let scans = 0;
+  for (let index = 0; index < text.length && scans < MAX_CANDIDATE_SCANS; index += 1) {
+    if (text[index] !== "{" && text[index] !== "[") {
+      continue;
+    }
+    scans += 1;
+    const candidate = scanBalanced(text, index);
+    if (candidate !== null) {
+      candidates.push(candidate);
+    }
+  }
+  return candidates;
+}
+
+function scanBalanced(text: string, startIndex: number): string | null {
+  const stack: string[] = [];
+  let inString = false;
+  let escaped = false;
+
+  for (let index = startIndex; index < text.length; index += 1) {
+    const char = text[index] as string;
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      stack.push(char);
+      continue;
+    }
+    if (char !== "}" && char !== "]") {
+      continue;
+    }
+
+    const open = stack.at(-1);
+    const matches = (open === "{" && char === "}") || (open === "[" && char === "]");
+    if (!matches) {
+      return null;
+    }
+    stack.pop();
+    if (stack.length === 0) {
+      return text.slice(startIndex, index + 1);
+    }
+  }
+
+  return null;
+}

package/src/workflows/loader.ts

@@ -0,0 +1,123 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { isWorkflowDefinition } from "./definition.js";
+import type { WorkflowDefinition } from "./types.js";
+
+const WORKFLOW_FILE_SUFFIXES = [".workflow.ts", ".workflow.js", ".workflow.mts", ".workflow.mjs"];
+
+export type DiscoveredWorkflow = {
+  name: string;
+  path: string;
+  source: "project" | "global" | "path";
+};
+
+export type WorkflowSearchPaths = {
+  cwd: string;
+  homeDir?: string;
+};
+
+/** Directories scanned for `*.workflow.ts` files, in precedence order. */
+export function workflowSearchDirs(
+  options: WorkflowSearchPaths,
+): { dir: string; source: "project" | "global" }[] {
+  const homeDir = options.homeDir ?? os.homedir();
+  return [
+    { dir: path.join(options.cwd, ".pi", "workflows"), source: "project" },
+    { dir: path.join(homeDir, ".pi", "agent", "workflows"), source: "global" },
+  ];
+}
+
+function isWorkflowFile(fileName: string): boolean {
+  return WORKFLOW_FILE_SUFFIXES.some((suffix) => fileName.endsWith(suffix));
+}
+
+export function workflowFileStem(filePath: string): string {
+  const base = path.basename(filePath);
+  const suffix = WORKFLOW_FILE_SUFFIXES.find((candidate) => base.endsWith(candidate));
+  return suffix ? base.slice(0, -suffix.length) : base;
+}
+
+// Alias the package name to this module's own entry so workflow files can
+// `import { agent } from "@osolmaz/pi-workflows"` whether the engine runs from src
+// (tests, tsx) or from the built dist inside the installed package.
+const SELF_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+
+/** Load a workflow module from disk. The default export must be `defineWorkflow(...)`. */
+export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefinition> {
+  const absolutePath = path.resolve(filePath);
+  const jiti = createJiti(pathToFileURL(absolutePath).href, {
+    interopDefault: true,
+    moduleCache: false,
+    alias: { "@osolmaz/pi-workflows": SELF_ENTRY },
+  });
+  const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
+  if (!isWorkflowDefinition(loaded)) {
+    throw new Error(`Workflow module must default-export defineWorkflow(...): ${absolutePath}`);
+  }
+  return loaded;
+}
+
+/** Discover named workflows in the project and global workflow directories. */
+export async function discoverWorkflows(
+  options: WorkflowSearchPaths,
+): Promise<DiscoveredWorkflow[]> {
+  const discovered: DiscoveredWorkflow[] = [];
+  const seenNames = new Set<string>();
+  for (const { dir, source } of workflowSearchDirs(options)) {
+    for (const filePath of await listWorkflowFiles(dir)) {
+      const name = workflowFileStem(filePath);
+      if (seenNames.has(name)) {
+        continue;
+      }
+      seenNames.add(name);
+      discovered.push({ name, path: filePath, source });
+    }
+  }
+  return discovered;
+}
+
+async function listWorkflowFiles(dir: string): Promise<string[]> {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile() && isWorkflowFile(entry.name))
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}
+
+/**
+ * Resolve a `/workflow` argument to a workflow file. Accepts a discovered
+ * workflow name or a direct path to a `*.workflow.ts` file.
+ */
+export async function resolveWorkflowRef(
+  ref: string,
+  options: WorkflowSearchPaths,
+): Promise<{ path: string; source: DiscoveredWorkflow["source"] }> {
+  if (looksLikePath(ref)) {
+    const absolutePath = path.resolve(options.cwd, ref);
+    await fs.access(absolutePath);
+    return { path: absolutePath, source: "path" };
+  }
+  const discovered = await discoverWorkflows(options);
+  const match = discovered.find((workflow) => workflow.name === ref);
+  if (!match) {
+    const available = discovered.map((workflow) => workflow.name).join(", ") || "(none)";
+    throw new Error(`Unknown workflow ${JSON.stringify(ref)}. Available workflows: ${available}`);
+  }
+  return { path: match.path, source: match.source };
+}
+
+function looksLikePath(ref: string): boolean {
+  return (
+    ref.includes("/") ||
+    ref.includes("\\") ||
+    WORKFLOW_FILE_SUFFIXES.some((suffix) => ref.endsWith(suffix))
+  );
+}