@fkws/klonk 0.0.13 → 0.0.16

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;
@@ -54,16 +41,16 @@ module.exports = __toCommonJS(exports_src);
 
 // src/prototypes/Playlist.ts
 class Playlist {
-  machines;
+  bundles;
   finalizer;
-  constructor(machines = [], finalizer) {
-    this.machines = machines;
+  constructor(bundles = [], finalizer) {
+    this.bundles = bundles;
     this.finalizer = finalizer;
   }
   addTask(task, builder) {
-    const machine = { task, builder };
-    const newMachines = [...this.machines, machine];
-    return new Playlist(newMachines, this.finalizer);
+    const bundle = { task, builder };
+    const newBundles = [...this.bundles, bundle];
+    return new Playlist(newBundles, this.finalizer);
   }
   finally(finalizer) {
     this.finalizer = finalizer;
@@ -71,14 +58,14 @@ class Playlist {
   }
   async run(source) {
     const outputs = {};
-    for (const machine of this.machines) {
-      const input = machine.builder(source, outputs);
-      const isValid = await machine.task.validateInput(input);
+    for (const bundle of this.bundles) {
+      const input = bundle.builder(source, outputs);
+      const isValid = await bundle.task.validateInput(input);
       if (!isValid) {
-        throw new Error(`Input validation failed for task '${machine.task.ident}'`);
+        throw new Error(`Input validation failed for task '${bundle.task.ident}'`);
       }
-      const result = await machine.task.run(input);
-      outputs[machine.task.ident] = result;
+      const result = await bundle.task.run(input);
+      outputs[bundle.task.ident] = result;
     }
     if (this.finalizer) {
       await this.finalizer(source, outputs);
@@ -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

@@ -68,7 +68,7 @@ type InputBuilder<
 /**
 * @internal Internal assembly type that couples a task with its input builder.
 */
-interface Machine<
+interface TaskBundle<
 	SourceType,
 	AllOutputTypes,
 	TaskInputType,
@@ -79,11 +79,15 @@ interface Machine<
 	builder: InputBuilder<SourceType, AllOutputTypes, TaskInputType>;
 }
 /**
-* Prevent TypeScript from inferring `T` from a builder argument so that the
-* task definition remains the source of truth. Useful for preserving safety
-* when chaining `.addTask` calls.
+* Important typing note:
+*
+* We intentionally do NOT wrap the builder return in `NoInfer<...>`.
+* Doing so breaks contextual typing for object literals, causing string literal unions
+* (e.g. `"low" | "critical"`) to widen to `string` inside input builder callbacks.
+*
+* By letting `TaskInputType` be inferred from the `task` argument (and then checking the
+* builder against it), literal unions are preserved and DX stays sane.
 */
-type NoInfer<T> = [T][T extends any ? 0 : never];
 /**
 * An ordered sequence of Tasks executed with strong type inference.
 *
@@ -108,12 +112,12 @@ declare class Playlist<
 	/**
 	* Internal list of task + builder pairs in the order they will run.
 	*/
-	machines: Machine<any, any, any, any, string>[];
+	bundles: TaskBundle<any, any, any, any, string>[];
 	/**
 	* Optional finalizer invoked after all tasks complete (successfully or not).
 	*/
 	finalizer?: (source: SourceType, outputs: Record<string, any>) => void | Promise<void>;
-	constructor(machines?: Machine<any, any, any, any, string>[], finalizer?: (source: SourceType, outputs: Record<string, any>) => void | Promise<void>);
+	constructor(bundles?: TaskBundle<any, any, any, any, string>[], finalizer?: (source: SourceType, outputs: Record<string, any>) => void | Promise<void>);
 	/**
 	* Append a task to the end of the playlist.
 	*
@@ -134,7 +138,7 @@ declare class Playlist<
 		const IdentType extends string
 	>(task: Task<TaskInputType, TaskOutputType, IdentType> & {
 		ident: IdentType
-	}, builder: (source: SourceType, outputs: AllOutputTypes) => NoInfer<TaskInputType>): Playlist<AllOutputTypes & { [K in IdentType] : Railroad<TaskOutputType> }, SourceType>;
+	}, builder: (source: SourceType, outputs: AllOutputTypes) => TaskInputType): Playlist<AllOutputTypes & { [K in IdentType] : Railroad<TaskOutputType> }, SourceType>;
 	/**
 	* Register a callback to run after the playlist finishes. Use this hook to
 	* react to the last task or to adjust machine state before a transition.
@@ -282,7 +286,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 +319,6 @@ type Transition<TStateData> = {
 declare class StateNode<TStateData> {
 	transitions?: Transition<TStateData>[];
 	playlist: Playlist<any, TStateData>;
-	timeToNextTick: number;
 	ident: string;
 	tempTransitions?: {
 		to: string
@@ -316,6 +327,7 @@ declare class StateNode<TStateData> {
 	}[];
 	retry: false | number;
 	maxRetries: false | number;
+	logger?: Logger;
 	/**
 	* Create a `StateNode`.
 	*
@@ -410,13 +422,15 @@ declare class StateNode<TStateData> {
 *
 * @template TStateData - The shape of the external mutable state carried through the machine.
 */
-declare class Machine2<TStateData> {
+declare class Machine<TStateData> {
 	initialState: StateNode<TStateData> | null;
 	statesToCreate: StateNode<TStateData>[];
 	private currentState;
 	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.
@@ -437,7 +451,7 @@ declare class Machine2<TStateData> {
 	* @template TStateData
 	* @returns A new unfinalized machine instance.
 	*/
-	static create<TStateData>(): Machine2<TStateData>;
+	static create<TStateData>(): Machine<TStateData>;
 	/**
 	* Finalize the machine by resolving state transitions and locking configuration.
 	* Must be called before `start` or `run`.
@@ -448,10 +462,9 @@ 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>;
+	}): Machine<TStateData>;
 	/**
 	* Add a state to the machine.
 	*
@@ -462,21 +475,12 @@ declare class Machine2<TStateData> {
 	*/
 	addState(state: StateNode<TStateData>, options?: {
 		initial?: boolean
-	}): Machine2<TStateData>;
+	}): Machine<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): Machine<TStateData>;
 	/**
 	* Run the machine synchronously until it reaches a terminal condition:
 	* - A leaf state (no transitions)
@@ -489,6 +493,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, Machine };

package/dist/index.js

@@ -1,15 +1,15 @@
 // src/prototypes/Playlist.ts
 class Playlist {
-  machines;
+  bundles;
   finalizer;
-  constructor(machines = [], finalizer) {
-    this.machines = machines;
+  constructor(bundles = [], finalizer) {
+    this.bundles = bundles;
     this.finalizer = finalizer;
   }
   addTask(task, builder) {
-    const machine = { task, builder };
-    const newMachines = [...this.machines, machine];
-    return new Playlist(newMachines, this.finalizer);
+    const bundle = { task, builder };
+    const newBundles = [...this.bundles, bundle];
+    return new Playlist(newBundles, this.finalizer);
   }
   finally(finalizer) {
     this.finalizer = finalizer;
@@ -17,14 +17,14 @@ class Playlist {
   }
   async run(source) {
     const outputs = {};
-    for (const machine of this.machines) {
-      const input = machine.builder(source, outputs);
-      const isValid = await machine.task.validateInput(input);
+    for (const bundle of this.bundles) {
+      const input = bundle.builder(source, outputs);
+      const isValid = await bundle.task.validateInput(input);
       if (!isValid) {
-        throw new Error(`Input validation failed for task '${machine.task.ident}'`);
+        throw new Error(`Input validation failed for task '${bundle.task.ident}'`);
       }
-      const result = await machine.task.run(input);
-      outputs[machine.task.ident] = result;
+      const result = await bundle.task.run(input);
+      outputs[bundle.task.ident] = result;
     }
     if (this.finalizer) {
       await this.finalizer(source, outputs);
@@ -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.13",
+  "version": "0.0.16",
   "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": {}
 }