@sweny-ai/core 0.1.128 → 0.1.129

package/dist/executor.js

@@ -19,6 +19,7 @@ import { evaluateRequires } from "./requires.js";
 import { buildRetryPreamble } from "./retry.js";
 import { resolveExecutionModel } from "./model.js";
 import { buildToolAliases } from "./skills/index.js";
+import { validateWorkflow } from "./schema.js";
 import { resolveAgentAccess } from "./agent-env.js";
 import { fenceUntrusted } from "./untrusted.js";
 /**
@@ -1052,6 +1053,16 @@ function validate(workflow, skills) {
         if (!workflow.nodes[edge.to])
             throw new Error(`Edge references unknown node: "${edge.to}"`);
     }
+    // Same structural validation the CLI loader runs (reachability, self-loops,
+    // ambiguous edges, unbounded cycles, reserved eval policies, retry and
+    // max_iterations ceilings). Library callers, Studio's simulator and run.ts
+    // reach execute() without the loader, so without this they got none of it
+    // (#326). Runs once per execute() call, before any node runs. Skill
+    // availability stays a warning below, so no knownSkills here.
+    const structural = validateWorkflow(workflow);
+    if (structural.length > 0) {
+        throw new Error(`Invalid workflow "${workflow.id}":\n${structural.map((e) => `  ${e.code}: ${e.message}`).join("\n")}`);
+    }
     // Check that each node has at least one available skill (if it lists any)
     for (const [nodeId, node] of Object.entries(workflow.nodes)) {
         if (node.skills.length === 0)

package/dist/schema.d.ts

@@ -776,6 +776,22 @@ export declare const nodeToolsZ: z.ZodEffects<z.ZodObject<{
     deny?: string[] | undefined;
     allow?: string[] | undefined;
 }>;
+/**
+ * Ceiling on `retry.max`. Each retry attempt re-invokes the agent on the
+ * node (full model spend), so an unbounded value here is an unbounded spend
+ * multiplier per node, independent of the workflow-level `max_steps` budget.
+ * 10 comfortably covers every declared workflow today (max observed: 1) while
+ * still catching a fat-fingered value (e.g. a missing digit) at author time
+ * instead of at runtime. See #325.
+ */
+export declare const NODE_RETRY_MAX_CEILING = 10;
+/**
+ * Ceiling on an edge's `max_iterations`. A bounded back-edge is still a spend
+ * multiplier (each lap re-runs model nodes), and the default `max_steps` is
+ * 200, so a value above this can never be reached in a default run and only
+ * hides a typo. See #325.
+ */
+export declare const EDGE_MAX_ITERATIONS_CEILING = 100;
 export declare const nodeRetryZ: z.ZodObject<{
     max: z.ZodNumber;
     instruction: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
@@ -2735,7 +2751,7 @@ export declare function parseWorkflow(raw: unknown): {
     }> | undefined;
 };
 export interface WorkflowError {
-    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL";
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL" | "EDGE_ITERATIONS_EXCEEDED" | "RETRY_MAX_EXCEEDED";
     message: string;
     nodeId?: string;
 }
@@ -3347,6 +3363,7 @@ export declare const workflowJsonSchema: {
                     readonly max_iterations: {
                         readonly type: "integer";
                         readonly minimum: 1;
+                        readonly maximum: 100;
                         readonly description: "Max times this edge can be followed. Enables controlled retry loops.";
                     };
                 };

package/dist/schema.js

@@ -230,7 +230,14 @@ const retryInstructionReflectZ = z.object({ reflect: z.string().min(1) }).strict
  * still catching a fat-fingered value (e.g. a missing digit) at author time
  * instead of at runtime. See #325.
  */
-const NODE_RETRY_MAX_CEILING = 10;
+export const NODE_RETRY_MAX_CEILING = 10;
+/**
+ * Ceiling on an edge's `max_iterations`. A bounded back-edge is still a spend
+ * multiplier (each lap re-runs model nodes), and the default `max_steps` is
+ * 200, so a value above this can never be reached in a default run and only
+ * hides a typo. See #325.
+ */
+export const EDGE_MAX_ITERATIONS_CEILING = 100;
 export const nodeRetryZ = z
     .object({
     max: z.number().int().min(1).max(NODE_RETRY_MAX_CEILING),
@@ -263,7 +270,7 @@ export const edgeZ = z
     from: z.string().min(1),
     to: z.string().min(1),
     when: z.string().optional(),
-    max_iterations: z.number().int().min(1).optional(),
+    max_iterations: z.number().int().min(1).max(EDGE_MAX_ITERATIONS_CEILING).optional(),
 })
     .strict();
 /**
@@ -352,13 +359,25 @@ export function parseWorkflow(raw) {
 export function validateWorkflow(workflow, knownSkills) {
     const errors = [];
     const nodeIds = new Set(Object.keys(workflow.nodes));
+    const entryExists = nodeIds.has(workflow.entry);
     // Entry must exist
-    if (!nodeIds.has(workflow.entry)) {
+    if (!entryExists) {
         errors.push({
             code: "MISSING_ENTRY",
             message: `Entry node "${workflow.entry}" does not exist`,
         });
     }
+    // Adjacency over real nodes, built once (O(nodes + edges)) so reachability
+    // and cycle detection stay linear on large graphs.
+    const outAll = new Map();
+    const outUnbounded = new Map();
+    const push = (m, k, v) => {
+        const l = m.get(k);
+        if (l)
+            l.push(v);
+        else
+            m.set(k, [v]);
+    };
     // Edge targets must exist
     for (const edge of workflow.edges) {
         if (!nodeIds.has(edge.from)) {
@@ -382,6 +401,18 @@ export function validateWorkflow(workflow, knownSkills) {
                 nodeId: edge.from,
             });
         }
+        if (edge.max_iterations != null && edge.max_iterations > EDGE_MAX_ITERATIONS_CEILING) {
+            errors.push({
+                code: "EDGE_ITERATIONS_EXCEEDED",
+                message: `Edge from "${edge.from}" to "${edge.to}" declares max_iterations ${edge.max_iterations}, above the ceiling of ${EDGE_MAX_ITERATIONS_CEILING}`,
+                nodeId: edge.from,
+            });
+        }
+        if (nodeIds.has(edge.from) && nodeIds.has(edge.to)) {
+            push(outAll, edge.from, edge.to);
+            if (!edge.max_iterations && edge.from !== edge.to)
+                push(outUnbounded, edge.from, edge.to);
+        }
     }
     // Edge determinism: a node with two or more out-edges that have no `when`
     // clause is ambiguous. The executor's resolveNext picks the first such edge
@@ -396,9 +427,7 @@ export function validateWorkflow(workflow, knownSkills) {
             continue;
         if (edge.when)
             continue;
-        const list = unconditionalByNode.get(edge.from) ?? [];
-        list.push(edge.to);
-        unconditionalByNode.set(edge.from, list);
+        push(unconditionalByNode, edge.from, edge.to);
     }
     for (const [from, targets] of unconditionalByNode) {
         if (targets.length > 1) {
@@ -409,60 +438,63 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
-    // Don't check reachability if there are structural errors
-    if (errors.length > 0)
-        return errors;
-    // Reachability: BFS from entry
-    const visited = new Set();
-    const queue = [workflow.entry];
-    while (queue.length > 0) {
-        const id = queue.shift();
-        if (visited.has(id))
-            continue;
-        visited.add(id);
-        for (const edge of workflow.edges) {
-            if (edge.from === id && !visited.has(edge.to)) {
-                queue.push(edge.to);
+    // Reachability: BFS from entry. Skipped only when the entry is missing
+    // (every node would be reported, which is noise). All other diagnostics
+    // accumulate so one pass reports every structural problem.
+    if (entryExists) {
+        const visited = new Set([workflow.entry]);
+        const queue = [workflow.entry];
+        for (let i = 0; i < queue.length; i++) {
+            for (const to of outAll.get(queue[i]) ?? []) {
+                if (!visited.has(to)) {
+                    visited.add(to);
+                    queue.push(to);
+                }
             }
         }
-    }
-    for (const nodeId of nodeIds) {
-        if (!visited.has(nodeId)) {
-            errors.push({
-                code: "UNREACHABLE_NODE",
-                message: `Node "${nodeId}" is unreachable from entry "${workflow.entry}"`,
-                nodeId,
-            });
+        for (const nodeId of nodeIds) {
+            if (!visited.has(nodeId)) {
+                errors.push({
+                    code: "UNREACHABLE_NODE",
+                    message: `Node "${nodeId}" is unreachable from entry "${workflow.entry}"`,
+                    nodeId,
+                });
+            }
         }
     }
     // Detect unbounded cycles: the graph with max_iterations edges removed must be acyclic.
     // If removing bounded edges still leaves a cycle, it can loop forever.
-    const unboundedEdges = workflow.edges.filter((e) => !e.max_iterations && e.from !== e.to);
-    // DFS-based cycle detection on the unbounded subgraph
+    // Iterative DFS with an explicit stack so a deep chain cannot overflow the
+    // call stack (#326).
     const WHITE = 0, GRAY = 1, BLACK = 2;
     const color = new Map();
     for (const id of nodeIds)
         color.set(id, WHITE);
-    function dfs(node) {
-        color.set(node, GRAY);
-        for (const e of unboundedEdges) {
-            if (e.from !== node)
+    const findCycle = (start) => {
+        const stack = [{ node: start, i: 0 }];
+        color.set(start, GRAY);
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            const outs = outUnbounded.get(top.node) ?? [];
+            if (top.i >= outs.length) {
+                color.set(top.node, BLACK);
+                stack.pop();
                 continue;
-            const c = color.get(e.to);
+            }
+            const to = outs[top.i++];
+            const c = color.get(to);
             if (c === GRAY)
-                return e.to; // back-edge found → cycle
+                return to; // back-edge found → cycle
             if (c === WHITE) {
-                const cycle = dfs(e.to);
-                if (cycle)
-                    return cycle;
+                color.set(to, GRAY);
+                stack.push({ node: to, i: 0 });
             }
         }
-        color.set(node, BLACK);
         return null;
-    }
+    };
     for (const id of nodeIds) {
         if (color.get(id) === WHITE) {
-            const cycleNode = dfs(id);
+            const cycleNode = findCycle(id);
             if (cycleNode) {
                 errors.push({
                     code: "UNBOUNDED_CYCLE",
@@ -472,6 +504,18 @@ export function validateWorkflow(workflow, knownSkills) {
             }
         }
     }
+    // Retry ceiling for workflows that never went through zod (library callers,
+    // the e2e batch runner). Mirrors nodeRetryZ so every path enforces it (#325).
+    for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+        const max = node.retry?.max;
+        if (max != null && max > NODE_RETRY_MAX_CEILING) {
+            errors.push({
+                code: "RETRY_MAX_EXCEEDED",
+                message: `Node "${nodeId}" declares retry.max ${max}, above the ceiling of ${NODE_RETRY_MAX_CEILING}`,
+                nodeId,
+            });
+        }
+    }
     // Reject eval policies that are reserved in the vocabulary but not yet
     // implemented. The Zod schema accepts the whole EVAL_POLICIES enum (the
     // published JSON schema advertises them as reserved), but only `all_pass`
@@ -941,6 +985,7 @@ export const workflowJsonSchema = {
                     max_iterations: {
                         type: "integer",
                         minimum: 1,
+                        maximum: EDGE_MAX_ITERATIONS_CEILING,
                         description: "Max times this edge can be followed. Enables controlled retry loops.",
                     },
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.128",
+  "version": "0.1.129",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"