@osolmaz/pi-workflows 0.1.0

package/dist/workflows/graph.js

@@ -0,0 +1,127 @@
+import { assertValidWorkflowDefinitionShape } from "./schema.js";
+/**
+ * Validate the full graph: shape, known start node, known edge targets, and
+ * at most one outgoing edge per node.
+ */
+export function validateWorkflowDefinition(workflow) {
+    assertValidWorkflowDefinitionShape(workflow);
+    if (!Object.hasOwn(workflow.nodes, workflow.startAt)) {
+        throw new Error(`Workflow start node is missing: ${workflow.startAt}`);
+    }
+    const outgoingEdges = new Set();
+    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) {
+    const reachable = new Set([workflow.startAt]);
+    const queue = [workflow.startAt];
+    while (queue.length > 0) {
+        const nodeId = queue.shift();
+        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, nodeId, description) {
+    // 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, edge, outgoingEdges) {
+    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, from, output, result) {
+    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, from, result) {
+    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, output, result) {
+    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, result, jsonPath) {
+    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, jsonPath) {
+    if (!jsonPath.startsWith("$.")) {
+        throw new Error(`Unsupported JSON path: ${jsonPath}`);
+    }
+    return jsonPath
+        .slice(2)
+        .split(".")
+        .reduce((current, key) => {
+        if (current == null || typeof current !== "object") {
+            return undefined;
+        }
+        return current[key];
+    }, value);
+}
+//# sourceMappingURL=graph.js.map

package/dist/workflows/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/workflows/graph.ts"],"names":[],"mappings":"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"}

package/dist/workflows/index.d.ts

@@ -0,0 +1,11 @@
+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/dist/workflows/index.js

@@ -0,0 +1,11 @@
+export { agent, action, checkpoint, compute, defineWorkflow, isWorkflowDefinition, shell, } from "./definition.js";
+export { decision, decisionEdge } from "./decision.js";
+export { WorkflowEngine, appendStepContract } from "./engine.js";
+export { CancelledError, TimeoutError } from "./errors.js";
+export { extractJsonValue, parseJsonValue, parseStrictJsonValue, } from "./json.js";
+export { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
+export { discoverWorkflows, loadWorkflowFile, resolveWorkflowRef, workflowFileStem, workflowSearchDirs, } 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, } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,MAAM,EACN,UAAU,EACV,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,KAAK,GACN,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAA2B,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,GAErB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GAGnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,cAAc,EACd,aAAa,EACb,mBAAmB,GAEpB,MAAM,YAAY,CAAC"}

package/dist/workflows/json.d.ts

@@ -0,0 +1,14 @@
+export type JsonParseMode = "strict" | "fenced" | "compat";
+/**
+ * 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 declare function parseJsonValue(text: string, options?: {
+    mode?: JsonParseMode;
+}): unknown;
+/** Strict parse: the whole text must be a JSON value. */
+export declare function parseStrictJsonValue(text: string): unknown;
+/** Default tolerant parser: direct JSON, then fenced, then embedded object. */
+export declare function extractJsonValue(text: string): unknown;

package/dist/workflows/json.js

@@ -0,0 +1,134 @@
+/**
+ * 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, options = {}) {
+    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) {
+    return parseJsonValue(text, { mode: "strict" });
+}
+/** Default tolerant parser: direct JSON, then fenced, then embedded object. */
+export function extractJsonValue(text) {
+    return parseJsonValue(text, { mode: "compat" });
+}
+function tryParse(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function extractFencedJsonText(text) {
+    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) {
+    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) {
+    const candidates = [];
+    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, startIndex) {
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = startIndex; index < text.length; index += 1) {
+        const char = text[index];
+        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;
+}
+//# sourceMappingURL=json.js.map

package/dist/workflows/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/workflows/json.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,OAAO,GAA6B,EAAE;IACjF,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC;IAEtC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;YACpC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,OAAO,MAAM,CAAC,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,KAAK,MAAM,SAAS,IAAI,6BAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/D,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;YACnC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,OAAO,MAAM,CAAC,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY;IACzC,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,iBAAiB,KAAK,CAAC,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,YAAY,GAAG,iBAAiB,GAAG,CAAC,CAAC;IACzC,IACE,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM;QACnE,iBAAiB,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,EACzC,CAAC;QACD,YAAY,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QAC7C,YAAY,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAC5D,IAAI,iBAAiB,KAAK,CAAC,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAwB;IACjD,OAAO,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC;AACzE,CAAC;AAED,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B,SAAS,6BAA6B,CAAC,IAAY;IACjD,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,GAAG,mBAAmB,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACnF,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;YAC/C,SAAS;QACX,CAAC;QACD,KAAK,IAAI,CAAC,CAAC;QACX,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5C,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,UAAkB;IACpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,IAAI,KAAK,GAAG,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAW,CAAC;QAEnC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;iBAAM,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBACzB,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;iBAAM,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBACxB,QAAQ,GAAG,KAAK,CAAC;YACnB,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjB,QAAQ,GAAG,IAAI,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjC,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,OAAO,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC;QACjF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,GAAG,EAAE,CAAC;QACZ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/workflows/loader.d.ts

@@ -0,0 +1,28 @@
+import type { WorkflowDefinition } from "./types.js";
+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 declare function workflowSearchDirs(options: WorkflowSearchPaths): {
+    dir: string;
+    source: "project" | "global";
+}[];
+export declare function workflowFileStem(filePath: string): string;
+/** Load a workflow module from disk. The default export must be `defineWorkflow(...)`. */
+export declare function loadWorkflowFile(filePath: string): Promise<WorkflowDefinition>;
+/** Discover named workflows in the project and global workflow directories. */
+export declare function discoverWorkflows(options: WorkflowSearchPaths): Promise<DiscoveredWorkflow[]>;
+/**
+ * Resolve a `/workflow` argument to a workflow file. Accepts a discovered
+ * workflow name or a direct path to a `*.workflow.ts` file.
+ */
+export declare function resolveWorkflowRef(ref: string, options: WorkflowSearchPaths): Promise<{
+    path: string;
+    source: DiscoveredWorkflow["source"];
+}>;

package/dist/workflows/loader.js

@@ -0,0 +1,94 @@
+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";
+const WORKFLOW_FILE_SUFFIXES = [".workflow.ts", ".workflow.js", ".workflow.mts", ".workflow.mjs"];
+/** Directories scanned for `*.workflow.ts` files, in precedence order. */
+export function workflowSearchDirs(options) {
+    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) {
+    return WORKFLOW_FILE_SUFFIXES.some((suffix) => fileName.endsWith(suffix));
+}
+export function workflowFileStem(filePath) {
+    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) {
+    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 }));
+    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) {
+    const discovered = [];
+    const seenNames = new Set();
+    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) {
+    let entries;
+    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, options) {
+    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) {
+    return (ref.includes("/") ||
+        ref.includes("\\") ||
+        WORKFLOW_FILE_SUFFIXES.some((suffix) => ref.endsWith(suffix)));
+}
+//# sourceMappingURL=loader.js.map

package/dist/workflows/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/workflows/loader.ts"],"names":[],"mappings":"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"}

package/dist/workflows/schema.d.ts

@@ -0,0 +1,7 @@
+import type { AgentNodeDefinition, ActionNodeDefinition, CheckpointNodeDefinition, ComputeNodeDefinition, ShellActionNodeDefinition, WorkflowDefinition } from "./types.js";
+export declare function assertValidAgentNode(node: AgentNodeDefinition, nodeId?: string): void;
+export declare function assertValidComputeNode(node: ComputeNodeDefinition, nodeId?: string): void;
+export declare function assertValidActionNode(node: ActionNodeDefinition, nodeId?: string): void;
+export declare function assertValidShellActionNode(node: ShellActionNodeDefinition, nodeId?: string): void;
+export declare function assertValidCheckpointNode(node: CheckpointNodeDefinition, nodeId?: string): void;
+export declare function assertValidWorkflowDefinitionShape(definition: WorkflowDefinition): void;

package/dist/workflows/schema.js

@@ -0,0 +1,176 @@
+const NODE_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function fail(message) {
+    throw new Error(`Invalid workflow definition: ${message}`);
+}
+function assertRecord(value, description) {
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        fail(`${description} must be an object`);
+    }
+}
+function assertOptionalFunction(value, description) {
+    if (value !== undefined && typeof value !== "function") {
+        fail(`${description} must be a function when provided`);
+    }
+}
+function assertCommonNodeFields(node, nodeId) {
+    if (node.timeoutMs !== undefined &&
+        (typeof node.timeoutMs !== "number" || !Number.isFinite(node.timeoutMs) || node.timeoutMs <= 0)) {
+        fail(`node ${nodeId} timeoutMs must be a finite positive number`);
+    }
+    if (node.statusDetail !== undefined && typeof node.statusDetail !== "string") {
+        fail(`node ${nodeId} statusDetail must be a string`);
+    }
+}
+export function assertValidAgentNode(node, nodeId = "agent") {
+    if (typeof node.prompt !== "function") {
+        fail(`node ${nodeId} requires a prompt function`);
+    }
+    if (node.expectedOutput !== undefined && typeof node.expectedOutput !== "string") {
+        fail(`node ${nodeId} expectedOutput must be a string`);
+    }
+    assertOptionalFunction(node.validate, `node ${nodeId} validate`);
+    assertCommonNodeFields(node, nodeId);
+}
+export function assertValidComputeNode(node, nodeId = "compute") {
+    if (typeof node.run !== "function") {
+        fail(`node ${nodeId} requires a run function`);
+    }
+    assertCommonNodeFields(node, nodeId);
+}
+export function assertValidActionNode(node, nodeId = "action") {
+    // Dispatch discriminates with `"exec" in node`, so validation must use the
+    // same property semantics: a present-but-invalid `exec` is an error even
+    // when a `run` function exists.
+    const hasExec = "exec" in node;
+    const hasRun = "run" in node;
+    if (hasExec === hasRun) {
+        fail(`node ${nodeId} requires exactly one of run or exec`);
+    }
+    if (hasExec) {
+        if (typeof node.exec !== "function") {
+            fail(`node ${nodeId} exec must be a function`);
+        }
+        assertOptionalFunction(node.parse, `node ${nodeId} parse`);
+    }
+    else if (typeof node.run !== "function") {
+        fail(`node ${nodeId} run must be a function`);
+    }
+    assertCommonNodeFields(node, nodeId);
+}
+export function assertValidShellActionNode(node, nodeId = "shell") {
+    if (typeof node.exec !== "function") {
+        fail(`node ${nodeId} requires an exec function`);
+    }
+    assertOptionalFunction(node.parse, `node ${nodeId} parse`);
+    assertCommonNodeFields(node, nodeId);
+}
+export function assertValidCheckpointNode(node, nodeId = "checkpoint") {
+    if (node.summary !== undefined && typeof node.summary !== "string") {
+        fail(`node ${nodeId} summary must be a string`);
+    }
+    assertOptionalFunction(node.run, `node ${nodeId} run`);
+    assertCommonNodeFields(node, nodeId);
+}
+function assertValidNode(node, nodeId) {
+    switch (node.nodeType) {
+        case "agent":
+            assertValidAgentNode(node, nodeId);
+            return;
+        case "compute":
+            assertValidComputeNode(node, nodeId);
+            return;
+        case "action":
+            assertValidActionNode(node, nodeId);
+            return;
+        case "checkpoint":
+            assertValidCheckpointNode(node, nodeId);
+            return;
+        default:
+            fail(`node ${nodeId} has unknown nodeType ${String(node.nodeType)}`);
+    }
+}
+function assertValidEdgeShape(edge, index) {
+    assertRecord(edge, `edge ${index}`);
+    if (typeof edge.from !== "string" || edge.from.length === 0) {
+        fail(`edge ${index} requires a from node id`);
+    }
+    if ("to" in edge) {
+        if (typeof edge.to !== "string" || edge.to.length === 0) {
+            fail(`edge ${index} requires a to node id`);
+        }
+        return;
+    }
+    assertRecord(edge.switch, `edge ${index} switch`);
+    if (typeof edge.switch.on !== "string" || edge.switch.on.length === 0) {
+        fail(`edge ${index} switch.on must be a JSON path string`);
+    }
+    // Routing only understands these prefixes; rejecting others here prevents
+    // the source node from executing its side effects before a routing error.
+    const on = edge.switch.on;
+    if (!on.startsWith("$.") && !on.startsWith("$output.") && !on.startsWith("$result.")) {
+        fail(`edge ${index} switch.on must start with "$.", "$output.", or "$result."`);
+    }
+    assertRecord(edge.switch.cases, `edge ${index} switch.cases`);
+    if (Object.keys(edge.switch.cases).length === 0) {
+        fail(`edge ${index} switch.cases must not be empty`);
+    }
+    for (const [caseKey, target] of Object.entries(edge.switch.cases)) {
+        if (typeof target !== "string" || target.length === 0) {
+            fail(`edge ${index} switch case ${JSON.stringify(caseKey)} must map to a node id`);
+        }
+    }
+}
+/**
+ * Names claimed by `/workflow` subcommands; a workflow with one of these
+ * names could never be started because the keyword wins the argument slot.
+ */
+const RESERVED_WORKFLOW_NAMES = new Set(["cancel", "list", "pause", "resume"]);
+export function assertValidWorkflowDefinitionShape(definition) {
+    assertRecord(definition, "workflow");
+    if (typeof definition.name !== "string" || definition.name.length === 0) {
+        fail("workflow requires a name");
+    }
+    if (RESERVED_WORKFLOW_NAMES.has(definition.name)) {
+        fail(`workflow name ${JSON.stringify(definition.name)} is reserved for /workflow subcommands`);
+    }
+    if (definition.title !== undefined &&
+        typeof definition.title !== "string" &&
+        typeof definition.title !== "function") {
+        fail("workflow title must be a string or function");
+    }
+    if (definition.presentationPrompt !== undefined &&
+        typeof definition.presentationPrompt !== "string" &&
+        typeof definition.presentationPrompt !== "function") {
+        fail("workflow presentationPrompt must be a string or function");
+    }
+    if (typeof definition.startAt !== "string" || definition.startAt.length === 0) {
+        fail("workflow requires startAt");
+    }
+    if (definition.maxSteps !== undefined &&
+        (typeof definition.maxSteps !== "number" ||
+            !Number.isInteger(definition.maxSteps) ||
+            definition.maxSteps <= 0)) {
+        fail("workflow maxSteps must be a positive integer");
+    }
+    assertRecord(definition.nodes, "workflow nodes");
+    if (Object.keys(definition.nodes).length === 0) {
+        fail("workflow requires at least one node");
+    }
+    for (const [nodeId, node] of Object.entries(definition.nodes)) {
+        if (!NODE_ID_PATTERN.test(nodeId)) {
+            fail(`node id ${JSON.stringify(nodeId)} must match ${NODE_ID_PATTERN.source}`);
+        }
+        // Ids like __proto__ or toString would collide with Object prototype
+        // members in the plain-object maps used for outputs and results.
+        if (nodeId in Object.prototype) {
+            fail(`node id ${JSON.stringify(nodeId)} shadows an Object prototype member`);
+        }
+        assertRecord(node, `node ${nodeId}`);
+        assertValidNode(node, nodeId);
+    }
+    if (!Array.isArray(definition.edges)) {
+        fail("workflow edges must be an array");
+    }
+    definition.edges.forEach(assertValidEdgeShape);
+}
+//# sourceMappingURL=schema.js.map