@sweny-ai/core 0.1.27 → 0.1.28

package/dist/__tests__/executor.test.js

@@ -66,7 +66,7 @@ describe("executor", () => {
             },
         });
         const events = [];
-        const results = await execute(linearWorkflow, { alert: "test" }, {
+        const { results } = await execute(linearWorkflow, { alert: "test" }, {
             skills: createSkillMap([fileSkill]),
             claude,
             observer: (e) => events.push(e),
@@ -92,7 +92,7 @@ describe("executor", () => {
             },
             routes: { check: "high" },
         });
-        const results = await execute(branchingWorkflow, { alert: "cpu" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "cpu" }, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -111,7 +111,7 @@ describe("executor", () => {
             },
             routes: { check: "low" },
         });
-        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "minor" }, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -154,7 +154,7 @@ describe("executor", () => {
                 c: { data: {} },
             },
         });
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([]),
             claude,
             observer: () => {
@@ -193,7 +193,7 @@ describe("executor", () => {
         const claude = new MockClaude({
             responses: { only: { data: { result: "done" } } },
         });
-        const results = await execute(singleNode, {}, {
+        const { results } = await execute(singleNode, {}, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -252,7 +252,7 @@ describe("executor", () => {
             claude,
         })).rejects.toThrow("Missing required config");
         // Should succeed with override
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([skillWithConfig]),
             claude,
             config: { MY_KEY: "provided" },
@@ -267,7 +267,7 @@ describe("executor", () => {
                 c: { data: {} },
             },
         });
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -316,13 +316,20 @@ describe("executor", () => {
                 return opts.choices[0].id;
             },
         };
-        const results = await execute(retryWorkflow, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        const { results, trace } = 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);
+        // Trace captures the full execution path including loops
+        expect(trace.steps).toHaveLength(5); // extract, judge, extract(retry), judge, done
+        expect(trace.steps[0]).toEqual({ node: "extract", status: "success", iteration: 1 });
+        expect(trace.steps[2]).toEqual({ node: "extract", status: "success", iteration: 2 });
+        // Trace edges include the retry loop
+        const retryEdge = trace.edges.find((e) => e.from === "judge" && e.to === "extract");
+        expect(retryEdge).toBeDefined();
     });
     it("respects max_iterations=1 as single retry", async () => {
         const singleRetry = {
@@ -356,7 +363,7 @@ describe("executor", () => {
                 return opts.choices[0].id;
             },
         };
-        const results = await execute(singleRetry, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        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);
@@ -371,7 +378,7 @@ describe("executor", () => {
                 return "nonexistent_node"; // invalid target
             },
         };
-        const results = await execute(branchingWorkflow, {}, {
+        const { results } = await execute(branchingWorkflow, {}, {
             skills: createSkillMap([]),
             claude: badRouteClaude,
             config: {},

package/dist/__tests__/integration/e2e-workflow.integration.test.js

@@ -47,7 +47,7 @@ describe.runIf(available.claude)("e2e workflow with real Claude", () => {
             maxTurns: 3,
         });
         const events = [];
-        const results = await execute(analysisWorkflow, {
+        const { results } = await execute(analysisWorkflow, {
             alert: "CPU usage at 98% for 15 minutes on production server web-03",
             service: "api-gateway",
             timestamp: "2025-03-25T08:00:00Z",

package/dist/cli/main.js

@@ -358,7 +358,7 @@ triageCmd.action(async (options) => {
         contextUrls,
     };
     try {
-        const results = await execute(triageWorkflow, workflowInput, {
+        const { results } = await execute(triageWorkflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -474,7 +474,7 @@ implementCmd.action(async (issueId, options) => {
         contextUrls,
     };
     try {
-        const results = await execute(implementWorkflow, workflowInput, {
+        const { results } = await execute(implementWorkflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -624,7 +624,7 @@ export async function workflowRunAction(file, options) {
         };
     }
     try {
-        const results = await execute(workflow, workflowInput, {
+        const { results, trace } = await execute(workflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -642,7 +642,7 @@ export async function workflowRunAction(file, options) {
             for (const [nodeId, result] of results) {
                 state[nodeId] = result.status === "success" ? "success" : result.status === "failed" ? "failed" : "skipped";
             }
-            process.stdout.write(toMermaidBlock(workflow, { state, title: workflow.name }) + "\n");
+            process.stdout.write(toMermaidBlock(workflow, { state, trace, title: workflow.name }) + "\n");
         }
         const hasFailed = [...results.values()].some((r) => r.status === "failed");
         if (hasFailed) {

package/dist/executor.d.ts

@@ -12,7 +12,7 @@
  *
  * This replaces ~8k lines of engine + recipe step code.
  */
-import type { Workflow, Skill, Claude, Observer, NodeResult, Logger } from "./types.js";
+import type { Workflow, Skill, Claude, Observer, Logger, ExecutionResult } from "./types.js";
 export interface ExecuteOptions {
     /** Registered skills (id → Skill) */
     skills: Map<string, Skill>;
@@ -28,6 +28,8 @@ export interface ExecuteOptions {
 /**
  * Execute a workflow from entry to completion.
  *
- * Returns a map of node ID → result for every node that ran.
+ * Returns an ExecutionResult with:
+ * - `results`: map of node ID → final result (last execution if retried)
+ * - `trace`: full ordered execution trace including loops and routing decisions
  */
-export declare function execute(workflow: Workflow, input: unknown, options: ExecuteOptions): Promise<Map<string, NodeResult>>;
+export declare function execute(workflow: Workflow, input: unknown, options: ExecuteOptions): Promise<ExecutionResult>;

package/dist/executor.js

@@ -16,7 +16,9 @@ import { consoleLogger } from "./types.js";
 /**
  * Execute a workflow from entry to completion.
  *
- * Returns a map of node ID → result for every node that ran.
+ * Returns an ExecutionResult with:
+ * - `results`: map of node ID → final result (last execution if retried)
+ * - `trace`: full ordered execution trace including loops and routing decisions
  */
 export async function execute(workflow, input, options) {
     const { skills, claude, observer } = options;
@@ -24,6 +26,8 @@ export async function execute(workflow, input, options) {
     const logger = options.logger ?? consoleLogger;
     const results = new Map();
     const edgeCounts = new Map(); // "from→to" → times followed
+    const nodeRunCounts = new Map(); // node → times executed
+    const trace = { steps: [], edges: [] };
     validate(workflow, skills);
     safeObserve(observer, { type: "workflow:start", workflow: workflow.id }, logger);
     let currentId = workflow.entry;
@@ -31,6 +35,8 @@ export async function execute(workflow, input, options) {
         const node = workflow.nodes[currentId];
         if (!node)
             throw new Error(`Unknown node: "${currentId}"`);
+        const iteration = (nodeRunCounts.get(currentId) ?? 0) + 1;
+        nodeRunCounts.set(currentId, iteration);
         safeObserve(observer, { type: "node:enter", node: currentId, instruction: node.instruction }, logger);
         logger.info(`→ ${node.name}`, { node: currentId });
         // Gather tools from the node's skills
@@ -64,6 +70,7 @@ export async function execute(workflow, input, options) {
             },
         });
         results.set(currentId, result);
+        trace.steps.push({ node: currentId, status: result.status, iteration });
         safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
         logger.info(`  ✓ ${result.status}`, { node: currentId, toolCalls: result.toolCalls.length });
         // Dry run hard gate — stop at the first conditional routing decision.
@@ -80,13 +87,20 @@ export async function execute(workflow, input, options) {
             }
         }
         // Resolve next node via edge conditions
+        const prevId = currentId;
         currentId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger);
+        // Record the routing decision in the trace
+        if (currentId) {
+            const edgeKey = `${prevId}→${currentId}`;
+            const reason = workflow.edges.find((e) => e.from === prevId && e.to === currentId)?.when ?? "only path";
+            trace.edges.push({ from: prevId, to: currentId, reason });
+        }
     }
     safeObserve(observer, {
         type: "workflow:end",
         results: Object.fromEntries(results),
     }, logger);
-    return results;
+    return { results, trace };
 }
 // ─── Internals ───────────────────────────────────────────────────
 /**
@@ -119,7 +133,12 @@ function buildNodeInstruction(baseInstruction, input) {
         return baseInstruction;
     return `${sections.join("\n\n")}\n\n---\n\n${baseInstruction}`;
 }
-/** Call observer without letting exceptions crash the workflow */
+/**
+ * Call observer without letting exceptions crash the workflow.
+ *
+ * Accepts a typed ExecutionEvent so TypeScript catches mistakes in
+ * event construction at compile time rather than silently at runtime.
+ */
 function safeObserve(observer, event, logger) {
     if (!observer)
         return;

package/dist/executor.test.js

@@ -167,7 +167,7 @@ describe("executor", () => {
             },
         });
         const events = [];
-        const results = await execute(simpleWorkflow, { alert: "test" }, {
+        const { results } = await execute(simpleWorkflow, { alert: "test" }, {
             skills,
             claude,
             observer: (e) => events.push(e),
@@ -202,7 +202,7 @@ describe("executor", () => {
                 check: "handle_high", // Route to high severity handler
             },
         });
-        const results = await execute(branchingWorkflow, { alert: "cpu spike" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "cpu spike" }, {
             skills,
             claude,
             config: {},
@@ -224,7 +224,7 @@ describe("executor", () => {
                 check: "handle_low",
             },
         });
-        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "minor" }, {
             skills,
             claude,
             config: {},

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, } from "./types.js";
 export { consoleLogger } from "./types.js";
 export { execute } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";

package/dist/mermaid.d.ts

@@ -6,13 +6,16 @@
  * VS Code preview, documentation sites, and anywhere Mermaid is supported.
  *
  * Accepts optional execution state to color nodes by status
- * (current/success/failed/skipped).
+ * (current/success/failed/skipped) and optional execution trace
+ * to highlight which edges were taken and show loop iterations.
  */
-import type { Workflow } from "./types.js";
+import type { Workflow, ExecutionTrace } from "./types.js";
 export type NodeStatus = "current" | "success" | "failed" | "skipped";
 export interface MermaidOptions {
     /** Execution state — nodes not in this map render as default (pending) */
     state?: Record<string, NodeStatus>;
+    /** Execution trace — highlights taken/not-taken edges and loop counts */
+    trace?: ExecutionTrace;
     /** Graph direction: TB (top-bottom) or LR (left-right). Default: TB */
     direction?: "TB" | "LR";
     /** Title rendered above the diagram */
@@ -27,6 +30,7 @@ export interface MermaidOptions {
  *
  * const md = toMermaid(workflow, {
  *   state: { triage: 'success', investigate: 'current' },
+ *   trace: executionResult.trace,
  * });
  * // Wrap in ```mermaid fence for GitHub rendering
  * ```

package/dist/mermaid.js

@@ -6,7 +6,8 @@
  * VS Code preview, documentation sites, and anywhere Mermaid is supported.
  *
  * Accepts optional execution state to color nodes by status
- * (current/success/failed/skipped).
+ * (current/success/failed/skipped) and optional execution trace
+ * to highlight which edges were taken and show loop iterations.
  */
 /**
  * Convert a Workflow to a Mermaid flowchart diagram string.
@@ -17,12 +18,13 @@
  *
  * const md = toMermaid(workflow, {
  *   state: { triage: 'success', investigate: 'current' },
+ *   trace: executionResult.trace,
  * });
  * // Wrap in ```mermaid fence for GitHub rendering
  * ```
  */
 export function toMermaid(workflow, options = {}) {
-    const { state = {}, direction = "TB", title } = options;
+    const { state = {}, trace, direction = "TB", title } = options;
     const lines = [];
     if (title) {
         lines.push("---");
@@ -30,45 +32,80 @@ export function toMermaid(workflow, options = {}) {
         lines.push("---");
     }
     lines.push(`graph ${direction}`);
+    // Build node iteration counts from trace
+    const nodeIterations = new Map();
+    if (trace) {
+        for (const step of trace.steps) {
+            nodeIterations.set(step.node, Math.max(nodeIterations.get(step.node) ?? 0, step.iteration));
+        }
+    }
     // Nodes
     for (const [id, node] of Object.entries(workflow.nodes)) {
-        const label = escapeLabel(node.name);
+        let label = escapeLabel(node.name);
         const isEntry = id === workflow.entry;
         const entryTag = isEntry ? " \\u25B6" : "";
-        // Use stadium shape ([...]) for entry, rounded ([(...)])  for others
+        // Show iteration count for nodes that ran multiple times
+        const iterations = nodeIterations.get(id);
+        const iterTag = iterations && iterations > 1 ? ` ×${iterations}` : "";
         if (isEntry) {
-            lines.push(`    ${sanitizeId(id)}([${label}${entryTag}])`);
+            lines.push(`    ${sanitizeId(id)}([${label}${entryTag}${iterTag}])`);
         }
         else {
-            lines.push(`    ${sanitizeId(id)}[${label}]`);
+            lines.push(`    ${sanitizeId(id)}[${label}${iterTag}]`);
         }
     }
     lines.push("");
-    // Edges
+    // Build set of taken edges from trace for lookup
+    const takenEdges = new Set();
+    const edgeTakenCounts = new Map();
+    if (trace) {
+        for (const te of trace.edges) {
+            const key = `${te.from}→${te.to}`;
+            takenEdges.add(key);
+            edgeTakenCounts.set(key, (edgeTakenCounts.get(key) ?? 0) + 1);
+        }
+    }
+    // Edges — track index for linkStyle directives
+    const takenIndices = [];
+    const notTakenIndices = [];
+    let edgeIndex = 0;
     for (const edge of workflow.edges) {
         const from = sanitizeId(edge.from);
         const to = sanitizeId(edge.to);
-        if (edge.when) {
-            const label = escapeLabel(edge.when);
-            if (edge.max_iterations) {
-                lines.push(`    ${from} -->|"${label} (max ${edge.max_iterations}x)"| ${to}`);
-            }
-            else {
-                lines.push(`    ${from} -->|"${label}"| ${to}`);
-            }
-        }
-        else if (edge.max_iterations) {
-            lines.push(`    ${from} -->|"max ${edge.max_iterations}x"| ${to}`);
+        const key = `${edge.from}→${edge.to}`;
+        const taken = takenEdges.has(key);
+        const takenCount = edgeTakenCounts.get(key) ?? 0;
+        // Build label parts
+        const labelParts = [];
+        if (edge.when)
+            labelParts.push(edge.when);
+        if (edge.max_iterations)
+            labelParts.push(`max ${edge.max_iterations}x`);
+        // Show how many times this edge was actually followed
+        if (takenCount > 1)
+            labelParts.push(`taken ${takenCount}x`);
+        if (labelParts.length > 0) {
+            const label = escapeLabel(labelParts.join(" · "));
+            lines.push(`    ${from} -->|"${label}"| ${to}`);
         }
         else {
             lines.push(`    ${from} --> ${to}`);
         }
+        // Track edge indices for styling
+        if (trace) {
+            if (taken) {
+                takenIndices.push(edgeIndex);
+            }
+            else {
+                notTakenIndices.push(edgeIndex);
+            }
+        }
+        edgeIndex++;
     }
-    // Status styling
+    // Node status styling
     const statusNodes = groupByStatus(state);
     if (statusNodes.size > 0) {
         lines.push("");
-        // Define style classes
         lines.push("    classDef current fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px");
         lines.push("    classDef success fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px");
         lines.push("    classDef failed fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:2px");
@@ -78,6 +115,16 @@ export function toMermaid(workflow, options = {}) {
             lines.push(`    class ${sanitized} ${status}`);
         }
     }
+    // Edge styling — taken edges bold green, not-taken edges dashed gray
+    if (trace) {
+        lines.push("");
+        if (takenIndices.length > 0) {
+            lines.push(`    linkStyle ${takenIndices.join(",")} stroke:#22c55e,stroke-width:3px`);
+        }
+        if (notTakenIndices.length > 0) {
+            lines.push(`    linkStyle ${notTakenIndices.join(",")} stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 5`);
+        }
+    }
     return lines.join("\n");
 }
 /**

package/dist/mermaid.test.js

@@ -72,7 +72,7 @@ describe("toMermaid", () => {
     });
     it("renders max_iterations on edges", () => {
         const result = toMermaid(withLoop);
-        expect(result).toContain('a -->|"needs retry (max 3x)"| a');
+        expect(result).toContain('a -->|"needs retry · max 3x"| a');
         expect(result).toContain("a --> b");
     });
     it("renders max_iterations without condition", () => {
@@ -168,6 +168,43 @@ describe("toMermaid", () => {
         expect(result).toContain("class a,b success");
         expect(result).toContain("class c current");
     });
+    it("highlights taken edges and dims not-taken edges with trace", () => {
+        const trace = {
+            steps: [
+                { node: "triage", status: "success", iteration: 1 },
+                { node: "investigate", status: "success", iteration: 1 },
+                { node: "close", status: "success", iteration: 1 },
+            ],
+            edges: [
+                { from: "triage", to: "investigate", reason: "severity is high or critical" },
+                { from: "investigate", to: "close", reason: "only path" },
+            ],
+        };
+        const result = toMermaid(branching, { trace });
+        // Taken edges get green bold styling (edges 0 and 2 in the workflow)
+        expect(result).toContain("linkStyle");
+        expect(result).toContain("stroke:#22c55e,stroke-width:3px");
+        // Not-taken edges get dashed gray
+        expect(result).toContain("stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 5");
+    });
+    it("shows iteration count on nodes and edges from trace", () => {
+        const trace = {
+            steps: [
+                { node: "a", status: "success", iteration: 1 },
+                { node: "a", status: "success", iteration: 2 },
+                { node: "b", status: "success", iteration: 1 },
+            ],
+            edges: [
+                { from: "a", to: "a", reason: "needs retry" },
+                { from: "a", to: "b", reason: "only path" },
+            ],
+        };
+        const result = toMermaid(withLoop, { trace });
+        // Node a ran twice — should show ×2
+        expect(result).toContain("×2");
+        // Node b ran once — no iteration tag
+        expect(result).not.toContain("Done ×");
+    });
 });
 describe("builtin workflows", () => {
     it("renders triage workflow", () => {

package/dist/schema.d.ts

@@ -238,7 +238,11 @@ export interface WorkflowError {
  * - All edge sources and targets reference existing nodes
  * - No self-loops
  * - All nodes are reachable from entry
+ * - Unbounded cycles (cycles with no max_iterations guard)
  * - (optional) All referenced skills exist in the provided skill set
+ *
+ * Note: nodes with no outgoing edges are valid terminal nodes — the executor
+ * returns null when it reaches one, ending the workflow cleanly.
  */
 export declare function validateWorkflow(workflow: z.infer<typeof workflowZ>, knownSkills?: Set<string>): WorkflowError[];
 /**

package/dist/schema.js

@@ -65,7 +65,11 @@ export function parseWorkflow(raw) {
  * - All edge sources and targets reference existing nodes
  * - No self-loops
  * - All nodes are reachable from entry
+ * - Unbounded cycles (cycles with no max_iterations guard)
  * - (optional) All referenced skills exist in the provided skill set
+ *
+ * Note: nodes with no outgoing edges are valid terminal nodes — the executor
+ * returns null when it reaches one, ending the workflow cleanly.
  */
 export function validateWorkflow(workflow, knownSkills) {
     const errors = [];

package/dist/types.d.ts

@@ -107,6 +107,36 @@ export type ExecutionEvent = {
     results: Record<string, NodeResult>;
 };
 export type Observer = (event: ExecutionEvent) => void;
+/** A single node execution within the trace */
+export interface TraceStep {
+    /** Node ID */
+    node: string;
+    /** Outcome of this execution */
+    status: "success" | "failed" | "skipped";
+    /** 1-based iteration count (2 = second time this node ran) */
+    iteration: number;
+}
+/** A routing decision between nodes */
+export interface TraceEdge {
+    from: string;
+    to: string;
+    /** Why this edge was chosen (condition text or "only path") */
+    reason: string;
+}
+/** Full execution trace — ordered steps + edges taken */
+export interface ExecutionTrace {
+    /** Ordered list of node executions (includes repeats from retry loops) */
+    steps: TraceStep[];
+    /** Ordered list of routing decisions */
+    edges: TraceEdge[];
+}
+/** Result of execute() — final node results + full execution trace */
+export interface ExecutionResult {
+    /** Final result per node (last execution if retried) */
+    results: Map<string, NodeResult>;
+    /** Full execution trace including loops and routing decisions */
+    trace: ExecutionTrace;
+}
 export interface Claude {
     /** Run a node: give Claude an instruction, context, and tools */
     run(opts: {

package/package.json

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