@sweny-ai/core 0.1.24 → 0.1.26

package/dist/__tests__/executor.test.js

@@ -275,6 +275,92 @@ describe("executor", () => {
         // All nodes still execute (executor doesn't short-circuit on failure)
         expect(results.get("a")?.status).toBe("failed");
     });
+    it("executes a retry loop with max_iterations", async () => {
+        const retryWorkflow = {
+            id: "retry",
+            name: "Retry",
+            description: "A→B→A (retry once)→B→C",
+            entry: "extract",
+            nodes: {
+                extract: { name: "Extract", instruction: "Extract data", skills: [] },
+                judge: { name: "Judge", instruction: "Judge quality", skills: [] },
+                done: { name: "Done", instruction: "Finish", skills: [] },
+            },
+            edges: [
+                { from: "extract", to: "judge" },
+                { from: "judge", to: "extract", when: "quality is low", max_iterations: 1 },
+                { from: "judge", to: "done", when: "quality is high or retries exhausted" },
+            ],
+        };
+        // Track how many times each node runs
+        let extractCount = 0;
+        let judgeCount = 0;
+        const mockClaude = {
+            async run(opts) {
+                if (opts.instruction.includes("Extract")) {
+                    extractCount++;
+                    return { status: "success", data: { extracted: true, attempt: extractCount }, toolCalls: [] };
+                }
+                if (opts.instruction.includes("Judge")) {
+                    judgeCount++;
+                    // First judge: low quality (triggers retry). Second judge: still low but edge exhausted.
+                    return { status: "success", data: { quality: "low" }, toolCalls: [] };
+                }
+                return { status: "success", data: {}, toolCalls: [] };
+            },
+            async evaluate(opts) {
+                // Always try to route to extract (retry), but max_iterations will block it on 2nd attempt
+                const retryChoice = opts.choices.find((c) => c.id === "extract");
+                if (retryChoice)
+                    return "extract";
+                return opts.choices[0].id;
+            },
+        };
+        const results = await execute(retryWorkflow, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        // extract ran twice (initial + 1 retry), judge ran twice, done ran once
+        expect(extractCount).toBe(2);
+        expect(judgeCount).toBe(2);
+        expect(results.has("done")).toBe(true);
+        // The second extract result overwrites the first
+        expect(results.get("extract")?.data.attempt).toBe(2);
+    });
+    it("respects max_iterations=1 as single retry", async () => {
+        const singleRetry = {
+            id: "single-retry",
+            name: "Single Retry",
+            description: "A↔B with max 1 loop",
+            entry: "a",
+            nodes: {
+                a: { name: "A", instruction: "Step A", skills: [] },
+                b: { name: "B", instruction: "Step B", skills: [] },
+                end: { name: "End", instruction: "End", skills: [] },
+            },
+            edges: [
+                { from: "a", to: "b" },
+                { from: "b", to: "a", when: "retry", max_iterations: 1 },
+                { from: "b", to: "end", when: "done" },
+            ],
+        };
+        let aCount = 0;
+        const mockClaude = {
+            async run(opts) {
+                if (opts.instruction.includes("Step A"))
+                    aCount++;
+                return { status: "success", data: {}, toolCalls: [] };
+            },
+            async evaluate(opts) {
+                // Always try to loop back
+                const retry = opts.choices.find((c) => c.id === "a");
+                if (retry)
+                    return "a";
+                return opts.choices[0].id;
+            },
+        };
+        const results = await execute(singleRetry, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        // A runs twice (once initially, once via retry), then edge is exhausted → falls to "end"
+        expect(aCount).toBe(2);
+        expect(results.has("end")).toBe(true);
+    });
     it("validates route choice falls back on invalid Claude response", async () => {
         // Create a claude mock that returns an invalid route
         const badRouteClaude = {

package/dist/__tests__/schema.test.js

@@ -60,6 +60,16 @@ describe("Zod schemas", () => {
         it("rejects empty to", () => {
             expect(() => edgeZ.parse({ from: "a", to: "" })).toThrow();
         });
+        it("parses an edge with max_iterations", () => {
+            const result = edgeZ.parse({ from: "a", to: "b", when: "needs retry", max_iterations: 3 });
+            expect(result.max_iterations).toBe(3);
+        });
+        it("rejects max_iterations less than 1", () => {
+            expect(() => edgeZ.parse({ from: "a", to: "b", max_iterations: 0 })).toThrow();
+        });
+        it("rejects non-integer max_iterations", () => {
+            expect(() => edgeZ.parse({ from: "a", to: "b", max_iterations: 1.5 })).toThrow();
+        });
     });
     describe("toolZ", () => {
         it("parses a valid tool", () => {
@@ -158,7 +168,7 @@ describe("validateWorkflow", () => {
         const errors = validateWorkflow(bad);
         expect(errors).toContainEqual(expect.objectContaining({ code: "UNKNOWN_EDGE_TARGET" }));
     });
-    it("detects self-loops", () => {
+    it("detects self-loops without max_iterations", () => {
         const loopy = {
             ...validWorkflow,
             edges: [
@@ -170,6 +180,42 @@ describe("validateWorkflow", () => {
         const errors = validateWorkflow(loopy);
         expect(errors).toContainEqual(expect.objectContaining({ code: "SELF_LOOP", nodeId: "a" }));
     });
+    it("allows self-loops with max_iterations", () => {
+        const loopy = {
+            ...validWorkflow,
+            edges: [
+                { from: "a", to: "a", when: "needs retry", max_iterations: 2 },
+                { from: "a", to: "b" },
+                { from: "b", to: "c" },
+            ],
+        };
+        const errors = validateWorkflow(loopy);
+        expect(errors).toEqual([]);
+    });
+    it("detects unbounded multi-node cycles", () => {
+        const cyclic = {
+            ...validWorkflow,
+            edges: [
+                { from: "a", to: "b" },
+                { from: "b", to: "a", when: "retry" }, // cycle without max_iterations
+                { from: "b", to: "c" },
+            ],
+        };
+        const errors = validateWorkflow(cyclic);
+        expect(errors).toContainEqual(expect.objectContaining({ code: "UNBOUNDED_CYCLE" }));
+    });
+    it("allows multi-node cycles with max_iterations", () => {
+        const cyclic = {
+            ...validWorkflow,
+            edges: [
+                { from: "a", to: "b" },
+                { from: "b", to: "a", when: "retry", max_iterations: 3 },
+                { from: "b", to: "c" },
+            ],
+        };
+        const errors = validateWorkflow(cyclic);
+        expect(errors).toEqual([]);
+    });
     it("detects unreachable nodes", () => {
         const disconnected = {
             ...validWorkflow,
@@ -231,6 +277,12 @@ describe("workflowJsonSchema", () => {
         expect(workflowJsonSchema.properties.edges.items.required).toContain("from");
         expect(workflowJsonSchema.properties.edges.items.required).toContain("to");
     });
+    it("edge items include max_iterations", () => {
+        const edgeProps = workflowJsonSchema.properties.edges.items.properties;
+        expect(edgeProps.max_iterations).toBeDefined();
+        expect(edgeProps.max_iterations.type).toBe("integer");
+        expect(edgeProps.max_iterations.minimum).toBe(1);
+    });
     it("node items require name and instruction", () => {
         expect(workflowJsonSchema.properties.nodes.additionalProperties.required).toContain("name");
         expect(workflowJsonSchema.properties.nodes.additionalProperties.required).toContain("instruction");

package/dist/executor.d.ts

@@ -1,11 +1,15 @@
 /**
- * DAG Workflow Executor
+ * Workflow Executor
  *
  * Walks a workflow graph node-by-node. At each node, Claude gets
  * the node's instruction + available skill tools + context from
  * prior nodes. Claude does the work, then the executor resolves
  * which edge to follow next.
  *
+ * Supports controlled cycles via max_iterations on edges — when
+ * an edge has been followed max_iterations times, it is excluded
+ * from routing, causing flow to fall through to alternative paths.
+ *
  * This replaces ~8k lines of engine + recipe step code.
  */
 import type { Workflow, Skill, Claude, Observer, NodeResult, Logger } from "./types.js";

package/dist/executor.js

@@ -1,11 +1,15 @@
 /**
- * DAG Workflow Executor
+ * Workflow Executor
  *
  * Walks a workflow graph node-by-node. At each node, Claude gets
  * the node's instruction + available skill tools + context from
  * prior nodes. Claude does the work, then the executor resolves
  * which edge to follow next.
  *
+ * Supports controlled cycles via max_iterations on edges — when
+ * an edge has been followed max_iterations times, it is excluded
+ * from routing, causing flow to fall through to alternative paths.
+ *
  * This replaces ~8k lines of engine + recipe step code.
  */
 import { consoleLogger } from "./types.js";
@@ -19,6 +23,7 @@ export async function execute(workflow, input, options) {
     const config = resolveConfig(skills, options.config);
     const logger = options.logger ?? consoleLogger;
     const results = new Map();
+    const edgeCounts = new Map(); // "from→to" → times followed
     validate(workflow, skills);
     safeObserve(observer, { type: "workflow:start", workflow: workflow.id }, logger);
     let currentId = workflow.entry;
@@ -75,7 +80,7 @@ export async function execute(workflow, input, options) {
             }
         }
         // Resolve next node via edge conditions
-        currentId = await resolveNext(workflow, currentId, results, input, claude, observer);
+        currentId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts);
     }
     safeObserve(observer, {
         type: "workflow:end",
@@ -160,13 +165,30 @@ function resolveConfig(skills, overrides) {
  * - 0 out-edges → terminal (return null)
  * - 1 unconditional edge → follow it
  * - Multiple or conditional → Claude evaluates
+ *
+ * Edges with max_iterations are filtered out once exhausted.
  */
-async function resolveNext(workflow, current, results, input, claude, observer) {
-    const outEdges = workflow.edges.filter((e) => e.from === current);
+async function resolveNext(workflow, current, results, input, claude, observer, edgeCounts) {
+    // Filter out edges that have exceeded their max_iterations
+    const outEdges = workflow.edges.filter((e) => {
+        if (e.from !== current)
+            return false;
+        if (e.max_iterations && edgeCounts) {
+            const key = `${e.from}→${e.to}`;
+            const count = edgeCounts.get(key) ?? 0;
+            if (count >= e.max_iterations)
+                return false;
+        }
+        return true;
+    });
     if (outEdges.length === 0)
         return null;
     // Single unconditional edge — just follow it
     if (outEdges.length === 1 && !outEdges[0].when) {
+        if (edgeCounts) {
+            const key = `${current}→${outEdges[0].to}`;
+            edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
+        }
         safeObserve(observer, { type: "route", from: current, to: outEdges[0].to, reason: "only path" });
         return outEdges[0].to;
     }
@@ -194,6 +216,11 @@ async function resolveNext(workflow, current, results, input, claude, observer)
     // Validate that Claude returned a valid target
     const validTargets = new Set(outEdges.map((e) => e.to));
     const resolved = validTargets.has(chosen) ? chosen : (defaultEdge?.to ?? outEdges[0].to); // fall back to default or first edge
+    // Track edge usage for max_iterations
+    if (edgeCounts) {
+        const key = `${current}→${resolved}`;
+        edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
+    }
     safeObserve(observer, {
         type: "route",
         from: current,

package/dist/schema.d.ts

@@ -122,14 +122,17 @@ export declare const edgeZ: z.ZodObject<{
     from: z.ZodString;
     to: z.ZodString;
     when: z.ZodOptional<z.ZodString>;
+    max_iterations: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     from: string;
     to: string;
     when?: string | undefined;
+    max_iterations?: number | undefined;
 }, {
     from: string;
     to: string;
     when?: string | undefined;
+    max_iterations?: number | undefined;
 }>;
 export declare const workflowZ: z.ZodObject<{
     id: z.ZodString;
@@ -155,14 +158,17 @@ export declare const workflowZ: z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         when: z.ZodOptional<z.ZodString>;
+        max_iterations: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         from: string;
         to: string;
         when?: string | undefined;
+        max_iterations?: number | undefined;
     }, {
         from: string;
         to: string;
         when?: string | undefined;
+        max_iterations?: number | undefined;
     }>, "many">;
     entry: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -179,6 +185,7 @@ export declare const workflowZ: z.ZodObject<{
         from: string;
         to: string;
         when?: string | undefined;
+        max_iterations?: number | undefined;
     }[];
     entry: string;
 }, {
@@ -194,6 +201,7 @@ export declare const workflowZ: z.ZodObject<{
         from: string;
         to: string;
         when?: string | undefined;
+        max_iterations?: number | undefined;
     }[];
     entry: string;
     description?: string | undefined;
@@ -213,11 +221,12 @@ export declare function parseWorkflow(raw: unknown): {
         from: string;
         to: string;
         when?: string | undefined;
+        max_iterations?: number | undefined;
     }[];
     entry: string;
 };
 export interface WorkflowError {
-    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "NO_OUTGOING_EDGE";
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "NO_OUTGOING_EDGE";
     message: string;
     nodeId?: string;
 }
@@ -241,7 +250,7 @@ export declare const workflowJsonSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://sweny.ai/schemas/workflow.json";
     readonly title: "SWEny Workflow";
-    readonly description: "A DAG workflow definition for skill-based orchestration";
+    readonly description: "A workflow definition for skill-based orchestration (supports controlled cycles via max_iterations)";
     readonly type: "object";
     readonly required: readonly ["id", "name", "nodes", "edges", "entry"];
     readonly additionalProperties: false;
@@ -311,6 +320,11 @@ export declare const workflowJsonSchema: {
                         readonly type: "string";
                         readonly description: "Natural language condition — Claude evaluates at runtime";
                     };
+                    readonly max_iterations: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "Max times this edge can be followed — enables controlled retry loops";
+                    };
                 };
             };
         };

package/dist/schema.js

@@ -43,6 +43,7 @@ export const edgeZ = z.object({
     from: z.string().min(1),
     to: z.string().min(1),
     when: z.string().optional(),
+    max_iterations: z.number().int().min(1).optional(),
 });
 export const workflowZ = z.object({
     id: z.string().min(1),
@@ -93,10 +94,10 @@ export function validateWorkflow(workflow, knownSkills) {
                 nodeId: edge.to,
             });
         }
-        if (edge.from === edge.to) {
+        if (edge.from === edge.to && !edge.max_iterations) {
             errors.push({
                 code: "SELF_LOOP",
-                message: `Edge from "${edge.from}" to itself`,
+                message: `Edge from "${edge.from}" to itself (add max_iterations to allow)`,
                 nodeId: edge.from,
             });
         }
@@ -127,12 +128,41 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
-    // Non-terminal nodes must have outgoing edges
-    for (const nodeId of nodeIds) {
-        const hasOutgoing = workflow.edges.some((e) => e.from === nodeId);
-        if (!hasOutgoing && visited.has(nodeId)) {
-            // Terminal node — fine, no error. This is intentional.
-            // But if it has outgoing in the graph, it's fine too.
+    // 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
+    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)
+                continue;
+            const c = color.get(e.to);
+            if (c === GRAY)
+                return e.to; // back-edge found → cycle
+            if (c === WHITE) {
+                const cycle = dfs(e.to);
+                if (cycle)
+                    return cycle;
+            }
+        }
+        color.set(node, BLACK);
+        return null;
+    }
+    for (const id of nodeIds) {
+        if (color.get(id) === WHITE) {
+            const cycleNode = dfs(id);
+            if (cycleNode) {
+                errors.push({
+                    code: "UNBOUNDED_CYCLE",
+                    message: `Unbounded cycle detected involving node "${cycleNode}" — add max_iterations to at least one edge in the cycle`,
+                    nodeId: cycleNode,
+                });
+            }
         }
     }
     // Skill references
@@ -160,7 +190,7 @@ export const workflowJsonSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://sweny.ai/schemas/workflow.json",
     title: "SWEny Workflow",
-    description: "A DAG workflow definition for skill-based orchestration",
+    description: "A workflow definition for skill-based orchestration (supports controlled cycles via max_iterations)",
     type: "object",
     required: ["id", "name", "nodes", "edges", "entry"],
     additionalProperties: false,
@@ -200,6 +230,11 @@ export const workflowJsonSchema = {
                     from: { type: "string", minLength: 1 },
                     to: { type: "string", minLength: 1 },
                     when: { type: "string", description: "Natural language condition — Claude evaluates at runtime" },
+                    max_iterations: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Max times this edge can be followed — enables controlled retry loops",
+                    },
                 },
             },
         },

package/dist/types.d.ts

@@ -48,6 +48,8 @@ export interface Edge {
     to: string;
     /** Natural language condition — Claude evaluates at runtime */
     when?: string;
+    /** Max times this edge can be followed (enables retry loops). Default: unlimited. */
+    max_iterations?: number;
 }
 /** A complete workflow definition — pure data, fully serializable */
 export interface Workflow {

package/package.json

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