@fkws/klonk 0.0.12 → 0.0.14

package/README.md

@@ -64,11 +64,21 @@ A `Machine` is a finite state machine. It's made up of `StateNode`s. Each `State
 
 The `Machine` carries a mutable `stateData` object that can be read from and written to by playlists and transition conditions throughout its execution.
 
+#### Machine run modes
+- **any**: Runs until the first terminal condition occurs (leaf state, roundtrip to the initial state, or all reachable states visited).
+- **leaf**: Runs until a leaf state (no transitions) is reached.
+- **roundtrip**: Runs until it transitions back to the initial state.
+- **infinitely**: Continues running indefinitely, sleeping between iterations (`interval` ms, default 1000). Use `stopAfter` to cap total states entered.
+
+Notes:
+- `stopAfter` counts states entered, including the initial state. For example, `stopAfter: 1` will run the initial state's playlist once and then stop; `stopAfter: 0` stops before entering the initial state.
+- Retries are independent of `stopAfter`. A state can retry its transition condition (with optional delay) without affecting the `stopAfter` count until a state transition actually occurs.
+
 ## Features
 - **Type-Safe & Autocompleted**: Klonk leverages TypeScript's inference to provide a world-class developer experience. The inputs and outputs of every step are strongly typed, so you'll know at compile time if your logic is sound.
 - **Code-First**: Define your automations directly in TypeScript. No YAML, no drag-and-drop UIs. Just the full power of a real programming language.
 - **Composable & Extensible**: The core primitives (`Task`, `Trigger`) are simple abstract classes, making it easy to create your own reusable components and integrations.
-- **Flexible Execution**: `Machines` can be run synchronously to completion (`run`) for request/response style work, or started as a long-running background process (`start`).
+- **Flexible Execution**: `Machines` run with configurable modes via `run(state, options)`: `any`, `leaf`, `roundtrip`, or `infinitely` (with optional `interval`).
 
 ## Klonkworks: Pre-built Components
 Coming soon(ish)! Klonkworks will be a large collection of pre-built Tasks, Triggers, and integrations. This will allow you to quickly assemble powerful automations that connect to a wide variety of services, often without needing to build your own components from scratch.
@@ -445,8 +455,9 @@ const webSearchAgent = Machine
                 }
             })
     ))
-    .finalize({ // Finalize your machine to make it ready to run. Verbose machines emit JSON logs. If you don't provide an ident, a uuidv4 will be generated for it.
-        verbose: true,
+    .addLogger(pino()) // If you add a logger to your machine,
+                       // it will call its info(), error(), debug(), fatal(), warn(), and trace() methods. Pino is recommended.
+    .finalize({ // Finalize your machine to make it ready to run. If you don't provide an ident, a uuidv4 will be generated for it.
         ident: "web-search-agent"
     })
 
@@ -457,10 +468,10 @@ const state: StateData = { // The state object is mutable and is passed to the m
     model: "openai/gpt-4o-mini"
 }
 
-// The .run() method executes the machine until it reaches a terminal state
-// (leaf, failed, out of retries, looped back to initial state)
-// and returns the final state. The original state object is also mutated.
-const finalState = await webSearchAgent.run(state)
+// The .run() method executes the machine until it reaches a terminal condition
+// based on the selected mode. For example, 'roundtrip' stops when it returns
+// to the initial state. The original state object is also mutated.
+const finalState = await webSearchAgent.run(state, { mode: 'roundtrip' })
 
 console.log(finalState.finalResponse) // The final state is returned.
 // Or simply:

package/dist/index.cjs

@@ -1,21 +1,8 @@
 var import_node_module = require("node:module");
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
 var __moduleCache = /* @__PURE__ */ new WeakMap;
 var __toCommonJS = (from) => {
   var entry = __moduleCache.get(from), desc;
@@ -181,22 +168,18 @@ class Trigger {
   }
 }
 // src/prototypes/Machine.ts
-var import_pino = __toESM(require("pino"));
 var import_crypto = require("crypto");
-var glogger = null;
-
 class StateNode {
   transitions;
   playlist;
-  timeToNextTick;
   ident;
   tempTransitions;
   retry;
   maxRetries;
+  logger;
   constructor(transitions, playlist) {
     this.transitions = transitions;
     this.playlist = playlist;
-    this.timeToNextTick = 1000;
     this.ident = "";
     this.retry = 1000;
     this.maxRetries = false;
@@ -255,7 +238,7 @@ class StateNode {
     return null;
   }
   async next(data) {
-    const logger = glogger?.child({ path: "StateNode.next", state: this.ident });
+    const logger = this.logger?.child?.({ path: "StateNode.next", state: this.ident }) ?? this.logger;
     logger?.info({ phase: "start" }, "Evaluating next state");
     const sorted = [...this.transitions || []].map((t, i) => ({ t, i })).sort((a, b) => (b.t.weight ?? 0) - (a.t.weight ?? 0) || a.i - b.i);
     for (const { t } of sorted) {
@@ -280,8 +263,10 @@ class Machine {
   finalized = false;
   logger;
   ident;
+  started = false;
+  tickTimer = null;
   getAllStates() {
-    const logger = glogger?.child({ path: "machine.getAllStates" });
+    const logger = this.logger?.child?.({ path: "machine.getAllStates" }) ?? this.logger;
     logger?.info({ phase: "start" }, "Gathering all states...");
     if (!this.initialState)
       return [];
@@ -310,10 +295,9 @@ class Machine {
     return new Machine;
   }
   finalize({
-    verbose,
     ident
   } = {}) {
-    const logger = glogger?.child({ path: "machine.finalize", instance: this.ident });
+    const logger = this.logger?.child?.({ path: "machine.finalize", instance: this.ident }) ?? this.logger;
     if (!this.initialState || this.statesToCreate.length === 0) {
       logger?.error({ phase: "error" }, "Finalization failed: no initial state or states to create");
       throw new Error("Cannot finalize a machine without an initial state or states to create.");
@@ -323,13 +307,11 @@ class Machine {
     } else {
       this.ident = import_crypto.randomUUID();
     }
-    if (verbose)
-      glogger = import_pino.default();
-    logger?.info("Logging enabled.");
     logger?.info({ phase: "start" }, `Finalizing machine ${this.ident}...`);
     const registry = new Map;
     logger?.info({ phase: "progress" }, `Building state registry...`);
     for (const s of this.statesToCreate) {
+      s.logger = this.logger;
       if (!s.ident) {
         logger?.error({ phase: "error" }, "Finalization failed: state missing ident");
         throw new Error("State missing ident.");
@@ -361,7 +343,7 @@ class Machine {
     return this;
   }
   addState(state, options = {}) {
-    const logger = glogger?.child({ path: "machine.addState", instance: this.ident });
+    const logger = this.logger?.child?.({ path: "machine.addState", instance: this.ident }) ?? this.logger;
     logger?.info({ phase: "start", state: state.ident, isInitial: !!options.initial }, "Adding state");
     this.statesToCreate.push(state);
     if (options.initial) {
@@ -370,45 +352,29 @@ class Machine {
     logger?.info({ phase: "end", state: state.ident }, "State added");
     return this;
   }
-  async start(stateData, options) {
-    const logger = glogger?.child({ path: "machine.start", instance: this.ident });
-    logger?.info({ phase: "start" }, "Starting machine...");
-    if (!this.finalized) {
-      logger?.error({ phase: "error" }, "Machine not finalized");
-      throw new Error("Cannot start a machine that is not finalized.");
-    }
-    if (!this.initialState) {
-      logger?.error({ phase: "error" }, "No initial state");
-      throw new Error("Cannot start a machine without an initial state.");
-    }
-    const interval = options?.interval ?? 1000;
-    logger?.info({ phase: "progress", interval }, "Machine interval set");
-    if (!this.currentState) {
-      this.currentState = this.initialState;
-      logger?.info({ phase: "progress", state: this.currentState.ident }, "Set initial state. Running playlist.");
-      await this.currentState.playlist.run(stateData);
-      logger?.info({ phase: "progress", state: this.currentState.ident }, "Initial playlist run complete.");
-    }
-    const tick = async () => {
-      const tickLogger = logger?.child({ path: "machine.tick" });
-      tickLogger?.info({ phase: "start", state: this.currentState.ident }, "Tick.");
-      const next = await this.currentState.next(stateData);
-      if (next) {
-        tickLogger?.info({ phase: "progress", from: this.currentState.ident, to: next.ident }, "Transitioning state.");
-        this.currentState = next;
-        await this.currentState.playlist.run(stateData);
-        tickLogger?.info({ phase: "progress", state: this.currentState.ident }, "Playlist run complete.");
-      } else {
-        tickLogger?.info({ phase: "progress", state: this.currentState.ident }, "No next state.");
+  addLogger(logger) {
+    this.logger = logger;
+    if (this.initialState) {
+      const visited = new Set;
+      const stack = [this.initialState];
+      while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node.ident || visited.has(node.ident))
+          continue;
+        visited.add(node.ident);
+        node.logger = logger;
+        for (const tr of node.transitions || []) {
+          if (tr.to && tr.to.ident && !visited.has(tr.to.ident)) {
+            stack.push(tr.to);
+          }
+        }
       }
-      setTimeout(tick, interval);
-    };
-    tick();
-    logger?.info({ phase: "end" }, "Machine started, tick loop initiated.");
+    }
+    return this;
   }
-  async run(stateData) {
-    const logger = glogger?.child({ path: "machine.run", instance: this.ident });
-    logger?.info({ phase: "start" }, "Running machine...");
+  async run(stateData, options) {
+    const logger = this.logger?.child?.({ path: "machine.run", instance: this.ident }) ?? this.logger;
+    logger?.info({ phase: "start", options }, "Running machine...");
     if (!this.finalized) {
       logger?.error({ phase: "error" }, "Machine not finalized");
       throw new Error("Cannot run a machine that is not finalized.");
@@ -419,27 +385,39 @@ class Machine {
     }
     const allStates = this.getAllStates();
     const visitedIdents = new Set;
+    let transitionsCount = 0;
+    if (options.stopAfter !== undefined && options.stopAfter === 0) {
+      logger?.info({ phase: "end", reason: "stopAfter", count: transitionsCount }, "Stop condition met.");
+      return stateData;
+    }
     let current = this.initialState;
     logger?.info({ phase: "progress", state: current.ident }, "Set initial state. Running playlist.");
     await current.playlist.run(stateData);
+    transitionsCount = 1;
     visitedIdents.add(current.ident);
+    if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {
+      logger?.info({ phase: "end", reason: "stopAfter", count: transitionsCount }, "Stop condition met.");
+      return stateData;
+    }
     while (true) {
       if (!current.transitions || current.transitions.length === 0) {
-        logger?.info({ phase: "end", state: current.ident }, "Reached leaf node, run complete.");
-        return stateData;
+        if (options.mode !== "infinitely") {
+          logger?.info({ phase: "end", state: current.ident, reason: "leaf" }, "Stop condition met.");
+          return stateData;
+        }
       }
       let next = await current.next(stateData);
       if (!next) {
         const retryDelay = current.retry;
-        if (!retryDelay) {
-          logger?.info({ phase: "end", state: current.ident }, "No next state and retries disabled, run complete.");
+        if (retryDelay === false) {
+          logger?.info({ phase: "end", state: current.ident, reason: "no-transition-no-retry" }, "Stop condition met.");
           return stateData;
         }
         let retries = 0;
         logger?.info({ phase: "progress", state: current.ident, retryDelay }, "No next state, beginning retry logic.");
         while (!next) {
-          if (current.maxRetries && retries >= current.maxRetries) {
-            logger?.warn({ phase: "end", state: current.ident, retries }, "Retry limit exhausted, run complete.");
+          if (current.maxRetries !== false && retries >= current.maxRetries) {
+            logger?.warn({ phase: "end", state: current.ident, retries, reason: "retries-exhausted" }, "Stop condition met.");
             return stateData;
           }
           await this.sleep(retryDelay);
@@ -454,17 +432,29 @@ class Machine {
       }
       const resolvedNext = next;
       if (resolvedNext === this.initialState) {
-        logger?.info({ phase: "end" }, "Next state is initial state, run complete.");
-        return stateData;
+        if (options.mode !== "infinitely") {
+          logger?.info({ phase: "end", reason: "roundtrip" }, "Stop condition met.");
+          return stateData;
+        }
       }
       logger?.info({ phase: "progress", from: current.ident, to: resolvedNext.ident }, "Transitioning state.");
       current = resolvedNext;
       await current.playlist.run(stateData);
       visitedIdents.add(current.ident);
-      if (visitedIdents.size >= allStates.length) {
-        logger?.info({ phase: "end" }, "All reachable states visited, run complete.");
+      transitionsCount++;
+      if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {
+        logger?.info({ phase: "end", reason: "stopAfter", count: transitionsCount }, "Stop condition met.");
         return stateData;
       }
+      if (visitedIdents.size >= allStates.length) {
+        if (options.mode === "any") {
+          logger?.info({ phase: "end", reason: "all-visited" }, "Stop condition met.");
+          return stateData;
+        }
+      }
+      if (options.mode === "infinitely") {
+        await this.sleep(options.interval ?? 1000);
+      }
     }
   }
 }

package/dist/index.d.ts

@@ -282,7 +282,15 @@ declare class Workflow<
 	*/
 	static create(): Workflow<never, {}, null>;
 }
-import { Logger } from "pino";
+type Logger = {
+	info: (...args: any[]) => void
+	error: (...args: any[]) => void
+	debug: (...args: any[]) => void
+	fatal: (...args: any[]) => void
+	warn: (...args: any[]) => void
+	trace: (...args: any[]) => void
+	child?: (bindings: Record<string, unknown>) => Logger
+};
 /**
 * A weighted, conditional edge to a target state.
 * Transitions are evaluated in descending `weight` order, then by insertion order.
@@ -307,7 +315,6 @@ type Transition<TStateData> = {
 declare class StateNode<TStateData> {
 	transitions?: Transition<TStateData>[];
 	playlist: Playlist<any, TStateData>;
-	timeToNextTick: number;
 	ident: string;
 	tempTransitions?: {
 		to: string
@@ -316,6 +323,7 @@ declare class StateNode<TStateData> {
 	}[];
 	retry: false | number;
 	maxRetries: false | number;
+	logger?: Logger;
 	/**
 	* Create a `StateNode`.
 	*
@@ -417,6 +425,8 @@ declare class Machine2<TStateData> {
 	finalized: boolean;
 	logger?: Logger;
 	ident?: string;
+	private started;
+	private tickTimer;
 	/**
 	* Compute the set of reachable states starting from the initial state.
 	* Used by `run` to determine completion once all states have been visited.
@@ -448,8 +458,7 @@ declare class Machine2<TStateData> {
 	* @returns This machine for chaining.
 	* @throws If there is no initial state, no states have been added, a state is missing an ident, or idents are duplicated.
 	*/
-	finalize({ verbose, ident }?: {
-		verbose?: boolean
+	finalize({ ident }?: {
 		ident?: string
 	}): Machine2<TStateData>;
 	/**
@@ -464,19 +473,10 @@ declare class Machine2<TStateData> {
 		initial?: boolean
 	}): Machine2<TStateData>;
 	/**
-	* Start the machine in a repeated tick loop. Executes the current state's playlist,
-	* evaluates transitions, and schedules the next tick with `setTimeout`.
-	* The method returns immediately after initializing the loop.
-	*
-	* @param stateData - Mutable external state provided to playlists and transition conditions.
-	* @param options - Start options.
-	* @param options.interval - Tick interval in milliseconds (default 1000ms).
-	* @returns A promise that resolves once the loop has been initiated.
-	* @throws If the machine has not been finalized or no initial state is set.
+	* Attach a logger to this machine. If the machine has an initial state set,
+	* the logger will be propagated to all currently reachable states.
 	*/
-	start(stateData: TStateData, options?: {
-		interval?: number
-	}): Promise<void>;
+	addLogger(logger: Logger): Machine2<TStateData>;
 	/**
 	* Run the machine synchronously until it reaches a terminal condition:
 	* - A leaf state (no transitions)
@@ -489,6 +489,18 @@ declare class Machine2<TStateData> {
 	* @returns A promise that resolves once the run completes.
 	* @throws If the machine has not been finalized or no initial state is set.
 	*/
-	run(stateData: TStateData): Promise<TStateData>;
+	run(stateData: TStateData, options: RunOptions): Promise<TStateData>;
 }
-export { Workflow, TriggerEvent, Trigger, Task, StateNode, Railroad, Playlist, Machine2 as Machine };
+type RunOptions = {
+	stopAfter?: number
+} & ({
+	mode: "any"
+} | {
+	mode: "leaf"
+} | {
+	mode: "roundtrip"
+} | {
+	mode: "infinitely"
+	interval?: number
+});
+export { Workflow, TriggerEvent, Trigger, Task, StateNode, RunOptions, Railroad, Playlist, Machine2 as Machine };

package/dist/index.js

@@ -127,22 +127,18 @@ class Trigger {
   }
 }
 // src/prototypes/Machine.ts
-import pino from "pino";
 import { randomUUID } from "crypto";
-var glogger = null;
-
 class StateNode {
   transitions;
   playlist;
-  timeToNextTick;
   ident;
   tempTransitions;
   retry;
   maxRetries;
+  logger;
   constructor(transitions, playlist) {
     this.transitions = transitions;
     this.playlist = playlist;
-    this.timeToNextTick = 1000;
     this.ident = "";
     this.retry = 1000;
     this.maxRetries = false;
@@ -201,7 +197,7 @@ class StateNode {
     return null;
   }
   async next(data) {
-    const logger = glogger?.child({ path: "StateNode.next", state: this.ident });
+    const logger = this.logger?.child?.({ path: "StateNode.next", state: this.ident }) ?? this.logger;
     logger?.info({ phase: "start" }, "Evaluating next state");
     const sorted = [...this.transitions || []].map((t, i) => ({ t, i })).sort((a, b) => (b.t.weight ?? 0) - (a.t.weight ?? 0) || a.i - b.i);
     for (const { t } of sorted) {
@@ -226,8 +222,10 @@ class Machine {
   finalized = false;
   logger;
   ident;
+  started = false;
+  tickTimer = null;
   getAllStates() {
-    const logger = glogger?.child({ path: "machine.getAllStates" });
+    const logger = this.logger?.child?.({ path: "machine.getAllStates" }) ?? this.logger;
     logger?.info({ phase: "start" }, "Gathering all states...");
     if (!this.initialState)
       return [];
@@ -256,10 +254,9 @@ class Machine {
     return new Machine;
   }
   finalize({
-    verbose,
     ident
   } = {}) {
-    const logger = glogger?.child({ path: "machine.finalize", instance: this.ident });
+    const logger = this.logger?.child?.({ path: "machine.finalize", instance: this.ident }) ?? this.logger;
     if (!this.initialState || this.statesToCreate.length === 0) {
       logger?.error({ phase: "error" }, "Finalization failed: no initial state or states to create");
       throw new Error("Cannot finalize a machine without an initial state or states to create.");
@@ -269,13 +266,11 @@ class Machine {
     } else {
       this.ident = randomUUID();
     }
-    if (verbose)
-      glogger = pino();
-    logger?.info("Logging enabled.");
     logger?.info({ phase: "start" }, `Finalizing machine ${this.ident}...`);
     const registry = new Map;
     logger?.info({ phase: "progress" }, `Building state registry...`);
     for (const s of this.statesToCreate) {
+      s.logger = this.logger;
       if (!s.ident) {
         logger?.error({ phase: "error" }, "Finalization failed: state missing ident");
         throw new Error("State missing ident.");
@@ -307,7 +302,7 @@ class Machine {
     return this;
   }
   addState(state, options = {}) {
-    const logger = glogger?.child({ path: "machine.addState", instance: this.ident });
+    const logger = this.logger?.child?.({ path: "machine.addState", instance: this.ident }) ?? this.logger;
     logger?.info({ phase: "start", state: state.ident, isInitial: !!options.initial }, "Adding state");
     this.statesToCreate.push(state);
     if (options.initial) {
@@ -316,45 +311,29 @@ class Machine {
     logger?.info({ phase: "end", state: state.ident }, "State added");
     return this;
   }
-  async start(stateData, options) {
-    const logger = glogger?.child({ path: "machine.start", instance: this.ident });
-    logger?.info({ phase: "start" }, "Starting machine...");
-    if (!this.finalized) {
-      logger?.error({ phase: "error" }, "Machine not finalized");
-      throw new Error("Cannot start a machine that is not finalized.");
-    }
-    if (!this.initialState) {
-      logger?.error({ phase: "error" }, "No initial state");
-      throw new Error("Cannot start a machine without an initial state.");
-    }
-    const interval = options?.interval ?? 1000;
-    logger?.info({ phase: "progress", interval }, "Machine interval set");
-    if (!this.currentState) {
-      this.currentState = this.initialState;
-      logger?.info({ phase: "progress", state: this.currentState.ident }, "Set initial state. Running playlist.");
-      await this.currentState.playlist.run(stateData);
-      logger?.info({ phase: "progress", state: this.currentState.ident }, "Initial playlist run complete.");
-    }
-    const tick = async () => {
-      const tickLogger = logger?.child({ path: "machine.tick" });
-      tickLogger?.info({ phase: "start", state: this.currentState.ident }, "Tick.");
-      const next = await this.currentState.next(stateData);
-      if (next) {
-        tickLogger?.info({ phase: "progress", from: this.currentState.ident, to: next.ident }, "Transitioning state.");
-        this.currentState = next;
-        await this.currentState.playlist.run(stateData);
-        tickLogger?.info({ phase: "progress", state: this.currentState.ident }, "Playlist run complete.");
-      } else {
-        tickLogger?.info({ phase: "progress", state: this.currentState.ident }, "No next state.");
+  addLogger(logger) {
+    this.logger = logger;
+    if (this.initialState) {
+      const visited = new Set;
+      const stack = [this.initialState];
+      while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node.ident || visited.has(node.ident))
+          continue;
+        visited.add(node.ident);
+        node.logger = logger;
+        for (const tr of node.transitions || []) {
+          if (tr.to && tr.to.ident && !visited.has(tr.to.ident)) {
+            stack.push(tr.to);
+          }
+        }
       }
-      setTimeout(tick, interval);
-    };
-    tick();
-    logger?.info({ phase: "end" }, "Machine started, tick loop initiated.");
+    }
+    return this;
   }
-  async run(stateData) {
-    const logger = glogger?.child({ path: "machine.run", instance: this.ident });
-    logger?.info({ phase: "start" }, "Running machine...");
+  async run(stateData, options) {
+    const logger = this.logger?.child?.({ path: "machine.run", instance: this.ident }) ?? this.logger;
+    logger?.info({ phase: "start", options }, "Running machine...");
     if (!this.finalized) {
       logger?.error({ phase: "error" }, "Machine not finalized");
       throw new Error("Cannot run a machine that is not finalized.");
@@ -365,27 +344,39 @@ class Machine {
     }
     const allStates = this.getAllStates();
     const visitedIdents = new Set;
+    let transitionsCount = 0;
+    if (options.stopAfter !== undefined && options.stopAfter === 0) {
+      logger?.info({ phase: "end", reason: "stopAfter", count: transitionsCount }, "Stop condition met.");
+      return stateData;
+    }
     let current = this.initialState;
     logger?.info({ phase: "progress", state: current.ident }, "Set initial state. Running playlist.");
     await current.playlist.run(stateData);
+    transitionsCount = 1;
     visitedIdents.add(current.ident);
+    if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {
+      logger?.info({ phase: "end", reason: "stopAfter", count: transitionsCount }, "Stop condition met.");
+      return stateData;
+    }
     while (true) {
       if (!current.transitions || current.transitions.length === 0) {
-        logger?.info({ phase: "end", state: current.ident }, "Reached leaf node, run complete.");
-        return stateData;
+        if (options.mode !== "infinitely") {
+          logger?.info({ phase: "end", state: current.ident, reason: "leaf" }, "Stop condition met.");
+          return stateData;
+        }
       }
       let next = await current.next(stateData);
       if (!next) {
         const retryDelay = current.retry;
-        if (!retryDelay) {
-          logger?.info({ phase: "end", state: current.ident }, "No next state and retries disabled, run complete.");
+        if (retryDelay === false) {
+          logger?.info({ phase: "end", state: current.ident, reason: "no-transition-no-retry" }, "Stop condition met.");
           return stateData;
         }
         let retries = 0;
         logger?.info({ phase: "progress", state: current.ident, retryDelay }, "No next state, beginning retry logic.");
         while (!next) {
-          if (current.maxRetries && retries >= current.maxRetries) {
-            logger?.warn({ phase: "end", state: current.ident, retries }, "Retry limit exhausted, run complete.");
+          if (current.maxRetries !== false && retries >= current.maxRetries) {
+            logger?.warn({ phase: "end", state: current.ident, retries, reason: "retries-exhausted" }, "Stop condition met.");
             return stateData;
           }
           await this.sleep(retryDelay);
@@ -400,17 +391,29 @@ class Machine {
       }
       const resolvedNext = next;
       if (resolvedNext === this.initialState) {
-        logger?.info({ phase: "end" }, "Next state is initial state, run complete.");
-        return stateData;
+        if (options.mode !== "infinitely") {
+          logger?.info({ phase: "end", reason: "roundtrip" }, "Stop condition met.");
+          return stateData;
+        }
       }
       logger?.info({ phase: "progress", from: current.ident, to: resolvedNext.ident }, "Transitioning state.");
       current = resolvedNext;
       await current.playlist.run(stateData);
       visitedIdents.add(current.ident);
-      if (visitedIdents.size >= allStates.length) {
-        logger?.info({ phase: "end" }, "All reachable states visited, run complete.");
+      transitionsCount++;
+      if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {
+        logger?.info({ phase: "end", reason: "stopAfter", count: transitionsCount }, "Stop condition met.");
         return stateData;
       }
+      if (visitedIdents.size >= allStates.length) {
+        if (options.mode === "any") {
+          logger?.info({ phase: "end", reason: "all-visited" }, "Stop condition met.");
+          return stateData;
+        }
+      }
+      if (options.mode === "infinitely") {
+        await this.sleep(options.interval ?? 1000);
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fkws/klonk",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "A lightweight, extensible workflow automation engine for Node.js and Bun",
   "repository": "https://github.com/klar-web-services/klonk",
   "homepage": "https://klonk.dev",
@@ -48,12 +48,11 @@
     "@types/node": "latest",
     "@vitest/coverage-v8": "^4.0.3",
     "bunup": "^0.6.2",
-    "vitest": "^4.0.3"
+    "vitest": "^4.0.3",
+    "pino": "^10.1.0"
   },
   "peerDependencies": {
     "typescript": "^5"
   },
-  "dependencies": {
-    "pino": "^10.1.0"
-  }
+  "dependencies": {}
 }