@fkws/klonk 0.0.17 → 0.0.19

package/README.md

@@ -19,6 +19,7 @@
 *A code-first, type-safe automation engine for TypeScript.*
 
 ## Introduction
+
 Klonk is a code-first, type-safe automation engine designed with developer experience as a top priority. It provides powerful, composable primitives to build complex workflows and state machines with world-class autocomplete and type inference. If you've ever wanted to build event-driven automations or a stateful agent, but in code, with all the benefits of TypeScript, Klonk is for you.
 
 ![Code](./.github/assets/blurry.png)
@@ -30,6 +31,7 @@ The two main features are **Workflows** and **Machines**.
 - **Machines**: Create finite state machines where each state has its own `Playlist` of tasks and conditional transitions to other states. Ideal for building agents, multi-step processes, or any system with complex, stateful logic.
 
 ## Installation
+
 ```bash
 bun add @fkws/klonk
 # or
@@ -41,26 +43,80 @@ npm i @fkws/klonk
 At the heart of Klonk are a few key concepts that work together.
 
 ### Task
+
 A `Task` is the smallest unit of work. It's an abstract class with two main methods you need to implement:
 - `validateInput(input)`: Runtime validation of the task's input (on top of strong typing).
 - `run(input)`: Executes the task's logic.
 
-Tasks use a `Railroad` return type, which is a simple way to handle success and error states without throwing exceptions. You can also use it for the rest of your application.
+Tasks use a `Railroad` return type, which is a simple discriminated union for handling success and error states without throwing exceptions. Shoutout to Rust!
 
 ### Playlist
-A `Playlist` is a sequence of `Tasks` that are executed in order. The magic of a `Playlist` is that each task has access to the outputs of all the tasks that ran before it, in a fully type-safe way. You build a `Playlist` by chaining `.addTask()` calls.
+
+A `Playlist` is a sequence of `Tasks` executed in order. The magic of a `Playlist` is that each task has access to the outputs of all previous tasks, in a fully type-safe way. You build a `Playlist` by chaining `.addTask().input()` calls:
+
+```typescript
+playlist
+    .addTask(new FetchTask("fetch"))
+    .input((source) => ({ url: source.targetUrl }))
+    .addTask(new ParseTask("parse"))
+    .input((source, outputs) => ({
+        // Full autocomplete! outputs.fetch?.success, outputs.fetch?.data, etc.
+        html: outputs.fetch?.success ? outputs.fetch.data.body : ""
+    }))
+```
+
+> **Note**: If you forget to call `.input()`, TypeScript will show an error mentioning `TaskInputRequired` - this is your hint that you need to provide the input builder!
+
+#### Skipping Tasks
+
+Need to conditionally skip a task? Just return `null` from the input builder:
+
+```typescript
+playlist
+    .addTask(new NotifyTask("notify"))
+    .input((source, outputs) => {
+        // Skip notification if previous task failed
+        if (!outputs.fetch?.success) {
+            return null;  // Task will be skipped!
+        }
+        return { message: "Success!", level: "info" };
+    })
+```
+
+When a task is skipped:
+- Its output in the `outputs` map is `null` (not a `Railroad`)
+- The playlist continues to the next task
+- Subsequent tasks can check `if (outputs.notify === null)` to know it was skipped
+
+This gives you Rust-like `Option` semantics using TypeScript's native `null` - no extra types needed!
 
 ### Trigger
+
 A `Trigger` is what kicks off a `Workflow`. It's an event source. Klonk can be extended with triggers for anything: file system events, webhooks, new database entries, messages in a queue, etc.
 
 ### Workflow
+
 A `Workflow` connects one or more `Triggers` to a `Playlist`. When a trigger fires an event, the workflow runs the playlist, passing the event data as the initial input. This allows you to create powerful, event-driven automations.
 
 ### Machine
-A `Machine` is a finite state machine. It's made up of `StateNode`s. Each `StateNode` represents a state and has two key components:
-1.  A `Playlist` that runs when the machine enters that state.
-2.  A set of conditional `Transitions` to other states.
-3.  Retry rules for when a transition fails to resolve.
+
+A `Machine` is a finite state machine. You build it by declaring all state identifiers upfront with `.withStates<...>()`, then adding states with `.addState()`:
+
+```typescript
+Machine.create<MyStateData>()
+    .withStates<"idle" | "running" | "complete">()  // Declare all states
+    .addState("idle", node => node
+        .setPlaylist(p => p.addTask(...).input(...))
+        .addTransition({ to: "running", condition: ..., weight: 1 })  // Autocomplete!
+    , { initial: true })
+    .addState("running", node => node...)
+    .finalize({ ident: "my-machine" });
+```
+
+Each state has:
+1. A `Playlist` that runs when the machine enters that state.
+2. A set of conditional `Transitions` to other states (with autocomplete!).
+3. Retry rules for when a transition fails to resolve.
 
 The `Machine` carries a mutable `stateData` object that can be read from and written to by playlists and transition conditions throughout its execution.
 
@@ -75,15 +131,18 @@ Notes:
 - 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` 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.
 
 ## Code Examples
+
 <details>
 <summary><b>Creating a Task</b></summary>
 
@@ -106,9 +165,9 @@ type TABasicTextInferenceOutput = {
 
 // A Task is a generic class. You provide the Input, Output, and an Ident (a unique string literal for the task).
 export class TABasicTextInference<IdentType extends string> extends Task<
-    TABasicTextInferenceInput,  // These type parameters are part of the secret sauce typing system Klonk uses.
-    TABasicTextInferenceOutput, // Input Type, Output Type, Ident Type
-    IdentType
+    TABasicTextInferenceInput,  // Input Type
+    TABasicTextInferenceOutput, // Output Type
+    IdentType                   // Ident Type (string literal for type-safe output keys)
 > {
     constructor(ident: IdentType, public client: OpenRouterClient) {
         super(ident);
@@ -135,13 +194,11 @@ export class TABasicTextInference<IdentType extends string> extends Task<
             });
             // On success, return a success object with your data.
             return {
-                success: true, // Railroad is a simple result type
-                data: {
-                    text: result
-                }
+                success: true,
+                data: { text: result }
             };
         } catch (error) {
-            // On failure, return an error object. The next Task's input builder will react to this.
+            // On failure, return an error object.
             return {
                 success: false,
                 error: error instanceof Error ? error : new Error(String(error))
@@ -174,7 +231,7 @@ export class IntervalTrigger<TIdent extends string> extends Trigger<TIdent, { no
         if (this.intervalId) return; // Prevent multiple intervals.
 
         this.intervalId = setInterval(() => {
-            // When an event occurs, use pushEvent to add it to the internal queue for the workflow to poll.
+            // When an event occurs, use pushEvent to add it to the internal queue.
             this.pushEvent({ now: new Date() });
         }, this.intervalMs);
     }
@@ -195,21 +252,21 @@ export class IntervalTrigger<TIdent extends string> extends Trigger<TIdent, { no
 
 Workflows are perfect for event-driven automations. This example creates a workflow that triggers when a new invoice PDF is added to a Dropbox folder. It then parses the invoice and creates a new item in a Notion database.
 
-Notice how the `builder` function for each task (`(source, outputs) => { ... }`) has access to the initial `source` data (from the trigger) and the `outputs` of all previous tasks. Klonk automatically infers the types for `source` and `outputs`!
+Notice the fluent `.addTask(task).input(builder)` syntax - each task's input builder has access to `source` (trigger data) and `outputs` (all previous task results), with full type inference!
 
 ```typescript
 import { z } from 'zod';
 import { Workflow } from '@fkws/klonk';
 
-// The following example requires a lot of tasks, integrations and a trigger.
+// The following example requires tasks, integrations and a trigger.
 // Soon, you will be able to import these from @fkws/klonkworks.
 import { TACreateNotionDatabaseItem, TANotionGetTitlesAndIdsForDatabase, TAParsePdfAi, TADropboxDownloadFile } from '@fkws/klonkworks/tasks';
 import { INotion, IOpenRouter, IDropbox } from '@fkws/klonkworks/integrations';
 import { TRDropboxFileAdded } from '@fkws/klonkworks/triggers';
 
 // Providers and clients are instantiated as usual.
-const notionProvider = new INotion({apiKey: process.env.NOTION_API_KEY!});
-const openrouterProvider = new IOpenRouter({apiKey: process.env.OPENROUTER_API_KEY!});
+const notionProvider = new INotion({ apiKey: process.env.NOTION_API_KEY! });
+const openrouterProvider = new IOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY! });
 const dropboxProvider = new IDropbox({
     appKey: process.env.DROPBOX_APP_KEY!,
     appSecret: process.env.DROPBOX_APP_SECRET!,
@@ -217,108 +274,100 @@ const dropboxProvider = new IDropbox({
 });
 
 // Start building a workflow.
-const workflow = Workflow.create().addTrigger(
-    // A workflow is initiated by one or more triggers.
-    new TRDropboxFileAdded("dropbox-trigger", {
-        client: dropboxProvider,
-        folderPath: process.env.DROPBOX_INVOICES_FOLDER_PATH ?? "",
-    })
-).setPlaylist(p => p // Builder function allows complex types to be assembled!
-    .addTask( // .addTask() adds a task to the playlist.
-        new TANotionGetTitlesAndIdsForDatabase("get-payees", notionProvider),
-        // The second argument to addTask builds the input for that task.
-        // `source` is the data from the trigger, `outputs` contains all previous task outputs.
-        (source, outputs) => {
-            return { database_id: process.env.NOTION_PAYEES_DATABASE_ID!}
-        }
-    ).addTask(
-        new TANotionGetTitlesAndIdsForDatabase("get-expense-types", notionProvider),
-        (source, outputs) => { // Type inference works for source and outputs!
-            return { database_id: process.env.NOTION_EXPENSE_TYPES_DATABASE_ID!}
-        }
-    ).addTask(
-        new TADropboxDownloadFile("download-invoice-pdf", dropboxProvider),
-        (source, outputs) => {
-            // The `source` object contains the trigger ident, so you can handle multiple triggers.
-            if (source.triggerIdent == "dropbox-trigger") {
-                return { file_metadata: source.data}
-            } else {
-                throw new Error(`Trigger ${source.triggerIdent} is not implemented for task download-invoice-pdf.`)
+const workflow = Workflow.create()
+    .addTrigger(
+        new TRDropboxFileAdded("dropbox-trigger", {
+            client: dropboxProvider,
+            folderPath: process.env.DROPBOX_INVOICES_FOLDER_PATH ?? "",
+        })
+    )
+    .setPlaylist(p => p
+        // Get payees from Notion
+        .addTask(new TANotionGetTitlesAndIdsForDatabase("get-payees", notionProvider))
+        .input((source, outputs) => ({
+            database_id: process.env.NOTION_PAYEES_DATABASE_ID!
+        }))
+
+        // Get expense types from Notion
+        .addTask(new TANotionGetTitlesAndIdsForDatabase("get-expense-types", notionProvider))
+        .input((source, outputs) => ({
+            database_id: process.env.NOTION_EXPENSE_TYPES_DATABASE_ID!
+        }))
+
+        // Download the invoice PDF from Dropbox
+        .addTask(new TADropboxDownloadFile("download-invoice-pdf", dropboxProvider))
+        .input((source, outputs) => {
+            // The `source` object contains the trigger ident for discrimination
+            if (source.triggerIdent === "dropbox-trigger") {
+                return { file_metadata: source.data }
             }
-        }
-    ).addTask(
-        new TAParsePdfAi("parse-invoice", openrouterProvider),
-        (source, outputs) => {
-            // Access the outputs of previous tasks via the `outputs` object.
-            // The keys are the idents you provided to the tasks.
+            throw new Error(`Trigger ${source.triggerIdent} not implemented`);
+        })
+
+        // Parse the PDF with AI
+        .addTask(new TAParsePdfAi("parse-invoice", openrouterProvider))
+        .input((source, outputs) => {
+            // Access outputs of previous tasks - fully typed!
+            // Check for null (skipped) and success
             const downloadResult = outputs['download-invoice-pdf'];
-            if (!downloadResult.success) {
-                throw downloadResult.error ?? new Error('Failed to download invoice PDF');
+            if (!downloadResult?.success) {
+                throw downloadResult?.error ?? new Error('Failed to download invoice PDF');
             }
 
             const payeesResult = outputs['get-payees'];
-            if (!payeesResult.success) {
-                throw payeesResult.error ?? new Error('Failed to load payees');
+            if (!payeesResult?.success) {
+                throw payeesResult?.error ?? new Error('Failed to load payees');
             }
 
             const expenseTypesResult = outputs['get-expense-types'];
-            if (!expenseTypesResult.success) {
-                throw expenseTypesResult.error ?? new Error('Failed to load expense types');
+            if (!expenseTypesResult?.success) {
+                throw expenseTypesResult?.error ?? new Error('Failed to load expense types');
             }
 
-            const payees = payeesResult.data;
-            const expenseTypes = expenseTypesResult.data;
-
             return {
                 pdf: downloadResult.data.file,
                 instructions: "Extract data from the invoice",
                 schema: z.object({
-                    payee: z.enum(payees.map(p => p.id) as [string, ...string[]])
-                        .describe("The payee id of the invoice according to this map: " + JSON.stringify(payees, null, 2)),
+                    payee: z.enum(payeesResult.data.map(p => p.id) as [string, ...string[]])
+                        .describe("The payee id"),
                     total: z.number()
-                        .describe("The total amount of the invoice."),
+                        .describe("The total amount"),
                     invoice_date: z.string()
                         .regex(/^\d{4}-\d{2}-\d{2}$/)
-                        .describe("The date of the invoice as an ISO 8601 string (YYYY-MM-DD)."),
-                    expense_type: z.enum(expenseTypes.map(e => e.id) as [string, ...string[]])
-                        .describe("The expense type id of the invoice according to this map: " + JSON.stringify(expenseTypes, null, 2))
+                        .describe("Date as YYYY-MM-DD"),
+                    expense_type: z.enum(expenseTypesResult.data.map(e => e.id) as [string, ...string[]])
+                        .describe("The expense type id")
                 })
             }
-        }
-    ).addTask(
-        new TACreateNotionDatabaseItem("create-notion-invoice", notionProvider),
-        (source, outputs) => {
+        })
+
+        // Create the invoice entry in Notion
+        .addTask(new TACreateNotionDatabaseItem("create-notion-invoice", notionProvider))
+        .input((source, outputs) => {
             const invoiceResult = outputs['parse-invoice'];
-            if (!invoiceResult.success) {
-                throw invoiceResult.error ?? new Error('Failed to parse invoice');
+            if (!invoiceResult?.success) {
+                throw invoiceResult?.error ?? new Error('Failed to parse invoice');
             }
             const invoiceData = invoiceResult.data;
-            const properties = {
-                'Name': { 'title': [{ 'text': { 'content': 'Invoice' } }] },
-                'Payee': { 'relation': [{ 'id': invoiceData.payee }] },
-                'Total': { 'number': invoiceData.total },
-                'Invoice Date': { 'date': { 'start': invoiceData.invoice_date } },
-                'Expense Type': { 'relation': [{ 'id': invoiceData.expense_type }] }
-            };
             return {
                 database_id: process.env.NOTION_INVOICES_DATABASE_ID!,
-                properties: properties
+                properties: {
+                    'Name': { 'title': [{ 'text': { 'content': 'Invoice' } }] },
+                    'Payee': { 'relation': [{ 'id': invoiceData.payee }] },
+                    'Total': { 'number': invoiceData.total },
+                    'Invoice Date': { 'date': { 'start': invoiceData.invoice_date } },
+                    'Expense Type': { 'relation': [{ 'id': invoiceData.expense_type }] }
+                }
             }
-        }
-    )
-)
+        })
+    );
 
 // Run the workflow
 console.log('[WCreateNotionInvoiceFromFile] Starting workflow...');
-// .start() begins the workflow's trigger polling loop.
 workflow.start({
-    // The callback is executed every time the playlist successfully completes.
     callback: (source, outputs) => {
         console.log('[WCreateNotionInvoiceFromFile] Workflow completed');
-        console.dir({
-            source,
-            outputs
-        }, { depth: null });
+        console.dir({ source, outputs }, { depth: null });
     }
 });
 ```
@@ -327,12 +376,12 @@ workflow.start({
 <details>
 <summary><b>Building a Machine</b></summary>
 
-`Machines` are ideal for building complex, stateful agents. This example shows a simple AI agent that takes a user's query, refines it, performs a web search, and then generates a final response.
+`Machines` are ideal for building complex, stateful agents. This example shows an AI agent that takes a user's query, refines it, performs a web search, and generates a final response.
 
-The `Machine` manages a `StateData` object. Each `StateNode`'s `Playlist` can modify this state, and the `Transitions` between states can use it to decide which state to move to next.
+The `Machine` manages a `StateData` object. Each `StateNode`'s `Playlist` can modify this state, and the `Transitions` between states use it to decide which state to move to next.
 
 ```typescript
-import { Machine, StateNode } from "@fkws/klonk"
+import { Machine } from "@fkws/klonk"
 import { OpenRouterClient } from "./tasks/common/OpenrouterClient" 
 import { Model } from "./tasks/common/models"
 import { TABasicTextInference } from "./tasks/TABasicTextInference"
@@ -349,15 +398,15 @@ type StateData = {
             url: string;
             title: string;
             content: string;
-            raw_content?: string | undefined;
+            raw_content?: string;
             score: string;
         }[];
         query: string;
-        answer?: string | undefined;
-        images?: string[] | undefined;
-        follow_up_questions?: string[] | undefined;
+        answer?: string;
+        images?: string[];
+        follow_up_questions?: string[];
         response_time: string;
-    },
+    };
     finalResponse?: string;
 }
 
@@ -365,116 +414,140 @@ const client = new OpenRouterClient(process.env.OPENROUTER_API_KEY!)
 
 const webSearchAgent = Machine
     .create<StateData>()
-    .addState(StateNode
-        .create<StateData>()
-        .setIdent("refine_and_extract")
-        .setPlaylist(p => p // Builder function allows complex types to be assembled!
-            .addTask(new TABasicTextInference("refine", client),
-                (state, outputs) => { // This function constructs the INPUT of the task from the state and outputs of previous tasks
-                    const input = state.input;
-                    const model = state.model ? state.model : "openai/gpt-5"
-                    const instructions = `You are a prompt refiner. Any prompts you receive, you will refine to improve LLM performance. Break down the prompt by Intent, Mood, and Instructions. Do NOT reply or answer the user's message! ONLY refine the prompt.`;
-                    return {
-                        inputText: input,
-                        model: model,
-                        instructions: instructions
-                    }
-                })
-            .addTask(new TABasicTextInference("extract_search_terms", client),
-                (state, outputs) => {
-                    const input = `Original request: ${state.input}\n\nRefined prompt: ${state.refinedInput}`;
-                    const model = state.model ? state.model : "openai/gpt-5"
-                    const instructions = `You will receive the original user request AND an LLM refined version of the prompt. Please use both to extract one short web search query that will retrieve useful results.`;
-                    return {
-                        inputText: input,
-                        model: model,
-                        instructions: instructions
-                    }
-                })
-            .finally((state, outputs) => { // The finally block allows the playlist to react to the last task and to modify state data before the run ends.
-                if (outputs.refine.success) {
-                    state.refinedInput = outputs.refine.data.text
-                } else {
-                    state.refinedInput = "Sorry, an error occurred: " + outputs.refine.error
-                }
+    // Declare all states upfront for transition autocomplete
+    .withStates<"refine_and_extract" | "search_web" | "generate_response">()
+    .addState("refine_and_extract", node => node
+        .setPlaylist(p => p
+            // Refine the user's input
+            .addTask(new TABasicTextInference("refine", client))
+            .input((state, outputs) => ({
+                inputText: state.input,
+                model: state.model ?? "openai/gpt-5.2",
+                instructions: `You are a prompt refiner. Refine the prompt to improve LLM performance. 
+                               Break down by Intent, Mood, and Instructions. Do NOT answer - ONLY refine.`
+            }))
 
-                if (outputs.extract_search_terms.success) {
-                    state.searchTerm = outputs.extract_search_terms.data.text
-                }
+            // Extract search terms from refined input
+            .addTask(new TABasicTextInference("extract_search_terms", client))
+            .input((state, outputs) => ({
+                inputText: `Original: ${state.input}\n\nRefined: ${outputs.refine?.success ? outputs.refine.data.text : state.input}`,
+                model: state.model ?? "openai/gpt-5.2",
+                instructions: `Extract one short web search query from the user request and refined prompt.`
             }))
-        .retryLimit(3) // Simple retry rule setters. Also includes .preventRetry() to disable retries entirely and .retryDelayMs(delayMs) to set the delay between retries. Default is infinite retries at 1000ms delay.
+
+            // Update state with results
+            .finally((state, outputs) => {
+                if (outputs.refine?.success) {
+                    state.refinedInput = outputs.refine.data.text;
+                }
+                if (outputs.extract_search_terms?.success) {
+                    state.searchTerm = outputs.extract_search_terms.data.text;
+                }
+            })
+        )
+        .retryLimit(3) // Retry up to 3 times if no transition available
         .addTransition({
-            to: "search_web", // Transitions refer to states by their ident.
-            condition: async (stateData: StateData) => stateData.searchTerm ? true : false,
-            weight: 2 // Weight determines the order in which transitions are tried. Higher weight = higher priority.
+            to: "search_web",  // Autocomplete works!
+            condition: async (state) => !!state.searchTerm,
+            weight: 2 // Higher weight = higher priority
         })
         .addTransition({
-            to: "generate_response",
-            condition: async (stateData: StateData) => true,
+            to: "generate_response",  // Autocomplete works!
+            condition: async () => true, // Fallback
             weight: 1
-        }),
-        { initial: true } // The machine needs an initial state.
-    )
-    .addState(StateNode.create<StateData>()
-        .setIdent("search_web")
+        })
+    , { initial: true })
+
+    .addState("search_web", node => node
         .setPlaylist(p => p
-            .addTask(new TASearchOnline("search"),
-            (state, outputs) => {
-                return {
-                    query: state.searchTerm! // We are sure that the searchTerm is not undefined because of the transition condition.
-                }
-            })
+            .addTask(new TASearchOnline("search"))
+            .input((state, outputs) => ({
+                query: state.searchTerm!
+            }))
             .finally((state, outputs) => {
-                if(outputs.search.success) {
-                    state.searchResults = outputs.search.data
+                if (outputs.search?.success) {
+                    state.searchResults = outputs.search.data;
                 }
-            }))
+            })
+        )
         .addTransition({
             to: "generate_response",
-            condition: async (stateData: StateData) => true,
+            condition: async () => true,
             weight: 1
         })
     )
-    .addState(StateNode.create<StateData>()
-        .setIdent("generate_response")
+
+    .addState("generate_response", node => node
         .setPlaylist(p => p
-            .addTask(new TABasicTextInference("generate_response", client),
-            (state, outputs) => {
-                return {
-                    inputText: state.input,
-                    model: state.model ? state.model : "openai/gpt-5",
-                    instructions: "You will receive a user request and a refined prompt. There may also be search results. Based on the information, please write a professional response to the user's request."
-                }
-            })
+            .addTask(new TABasicTextInference("generate_response", client))
+            .input((state, outputs) => ({
+                inputText: state.input,
+                model: state.model ?? "openai/gpt-5.2",
+                instructions: `You received a user request and refined prompt. 
+                               ${state.searchResults ? 'Search results are also available.' : ''}
+                               Write a professional response.`
+            }))
             .finally((state, outputs) => {
-                if(outputs.generate_response.success) {
-                    state.finalResponse = outputs.generate_response.data.text
-                }
-                else {
-                    state.finalResponse = "Sorry, an error occurred: " + outputs.generate_response.error
-                }
+                state.finalResponse = outputs.generate_response?.success
+                    ? outputs.generate_response.data.text
+                    : "Sorry, an error occurred: " + (outputs.generate_response?.error ?? "unknown");
             })
-    ))
-    .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"
-    })
+        )
+    )
+    .addLogger(pino()) // Optional: Add structured logging (pino recommended)
+    .finalize({ ident: "web-search-agent" });
 
-// ------------- EXECUTION: -------------
+// ------------- EXECUTION -------------
 
-const state: StateData = { // The state object is mutable and is passed to the machine and playlists.
+const state: StateData = {
     input: "How do I update AMD graphic driver?",
-    model: "openai/gpt-4o-mini"
-}
+    model: "openai/gpt-5.2-mini"
+};
 
-// 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' })
+// Run until it completes a roundtrip to the initial state
+const finalState = await webSearchAgent.run(state, { mode: 'roundtrip' });
 
-console.log(finalState.finalResponse) // The final state is returned.
-// Or simply:
-console.log(state.finalResponse) // original state object is also mutated.
+console.log(finalState.finalResponse);
+// The original state object is also mutated:
+console.log(state.finalResponse);
 ```
 </details>
+
+## Type System
+
+Klonk's type system is designed to be minimal yet powerful. Here's what makes it tick:
+
+### Core Types
+
+| Type | Parameters | Purpose |
+|------|------------|---------|
+| `Task<Input, Output, Ident>` | Input shape, output shape, string literal ident | Base class for all tasks |
+| `Railroad<Output>` | Success data type | Discriminated union for success/error results |
+| `Playlist<AllOutputs, Source>` | Accumulated output map, source data type | Ordered task sequence with typed chaining |
+| `Trigger<Ident, Data>` | String literal ident, event payload type | Event source for workflows |
+| `Workflow<Events>` | Union of trigger event types | Connects triggers to playlists |
+| `Machine<StateData, AllStateIdents>` | Mutable state shape, union of state idents | Finite state machine with typed transitions |
+| `StateNode<StateData, Ident, AllStateIdents>` | State shape, this node's ident, all valid transition targets | Individual state with playlist and transitions |
+
+### How Output Chaining Works
+
+When you add a task to a playlist, Klonk extends the output type:
+
+```typescript
+// Start with empty outputs
+Playlist<{}, Source>
+    .addTask(new FetchTask("fetch")).input(...)
+// Now outputs include: { fetch: Railroad<FetchOutput> | null }
+Playlist<{ fetch: Railroad<FetchOutput> | null }, Source>
+    .addTask(new ParseTask("parse")).input(...)  
+// Now outputs include both: { fetch: ..., parse: Railroad<ParseOutput> | null }
+```
+
+The `| null` accounts for the possibility that a task was skipped (when its input builder returns `null`). This is why you'll use optional chaining like `outputs.fetch?.success` - TypeScript knows the output could be `null` if the task was skipped!
+
+This maps cleanly to Rust's types:
+| Rust | Klonk (TypeScript) |
+|------|-------------------|
+| `Option<T>` | `T \| null` |
+| `Result<T, E>` | `Railroad<T>` |
+| `Option<Result<T, E>>` | `Railroad<T> \| null` |

package/dist/index.cjs

@@ -47,10 +47,14 @@ class Playlist {
     this.bundles = bundles;
     this.finalizer = finalizer;
   }
-  addTask(task, builder) {
-    const bundle = { task, builder };
-    const newBundles = [...this.bundles, bundle];
-    return new Playlist(newBundles, this.finalizer);
+  addTask(task) {
+    return {
+      input: (builder) => {
+        const bundle = { task, builder };
+        const newBundles = [...this.bundles, bundle];
+        return new Playlist(newBundles, this.finalizer);
+      }
+    };
   }
   finally(finalizer) {
     this.finalizer = finalizer;
@@ -60,6 +64,10 @@ class Playlist {
     const outputs = {};
     for (const bundle of this.bundles) {
       const input = bundle.builder(source, outputs);
+      if (input === null) {
+        outputs[bundle.task.ident] = null;
+        continue;
+      }
       const isValid = await bundle.task.validateInput(input);
       if (!isValid) {
         throw new Error(`Input validation failed for task '${bundle.task.ident}'`);
@@ -177,16 +185,13 @@ class StateNode {
   retry;
   maxRetries;
   logger;
-  constructor(transitions, playlist) {
-    this.transitions = transitions;
-    this.playlist = playlist;
-    this.ident = "";
+  constructor(ident) {
+    this.transitions = [];
+    this.playlist = new Playlist;
+    this.ident = ident;
     this.retry = 1000;
     this.maxRetries = false;
   }
-  static create() {
-    return new StateNode([], new Playlist);
-  }
   addTransition({ to, condition, weight }) {
     if (!this.tempTransitions) {
       this.tempTransitions = [];
@@ -216,10 +221,6 @@ class StateNode {
     this.maxRetries = maxRetries;
     return this;
   }
-  setIdent(ident) {
-    this.ident = ident;
-    return this;
-  }
   getByIdent(ident, visited = []) {
     if (this.ident === ident) {
       return this;
@@ -294,6 +295,9 @@ class Machine {
   static create() {
     return new Machine;
   }
+  withStates() {
+    return this;
+  }
   finalize({
     ident
   } = {}) {
@@ -342,14 +346,16 @@ class Machine {
     logger?.info({ phase: "end" }, `Machine ${this.ident} finalized.`);
     return this;
   }
-  addState(state, options = {}) {
+  addState(ident, builder, options = {}) {
     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);
+    logger?.info({ phase: "start", state: ident, isInitial: !!options.initial }, "Adding state");
+    const node = new StateNode(ident);
+    const configuredNode = builder(node);
+    this.statesToCreate.push(configuredNode);
     if (options.initial) {
-      this.initialState = state;
+      this.initialState = configuredNode;
     }
-    logger?.info({ phase: "end", state: state.ident }, "State added");
+    logger?.info({ phase: "end", state: ident }, "State added");
     return this;
   }
   addLogger(logger) {
@@ -432,7 +438,7 @@ class Machine {
       }
       const resolvedNext = next;
       if (resolvedNext === this.initialState) {
-        if (options.mode !== "infinitely") {
+        if (options.mode === "roundtrip" || options.mode === "any") {
           logger?.info({ phase: "end", reason: "roundtrip" }, "Stop condition met.");
           return stateData;
         }

package/dist/index.d.ts

@@ -54,36 +54,32 @@ declare abstract class Task<
 	abstract run(input: InputType): Promise<Railroad<OutputType>>;
 }
 /**
-* Function used to build the input for a Task from the Playlist context.
-*
-* @template SourceType - The source object passed to `run` (e.g., trigger event or machine state).
-* @template AllOutputTypes - Accumulated outputs from previously executed tasks.
-* @template TaskInputType - Concrete input type required by the target Task.
-*/
-type InputBuilder<
-	SourceType,
-	AllOutputTypes,
-	TaskInputType
-> = (source: SourceType, outputs: AllOutputTypes) => TaskInputType;
-/**
 * @internal Internal assembly type that couples a task with its input builder.
 */
-interface TaskBundle<
-	SourceType,
-	AllOutputTypes,
-	TaskInputType,
-	TaskOutputType,
-	IdentType extends string
-> {
-	task: Task<TaskInputType, TaskOutputType, IdentType>;
-	builder: InputBuilder<SourceType, AllOutputTypes, TaskInputType>;
+interface TaskBundle {
+	task: Task<any, any, string>;
+	builder: (source: any, outputs: any) => any;
 }
 /**
-* 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.
+* Returned by `Playlist.addTask()` - you must call `.input()` to provide the task's input builder.
+* 
+* If you see this type in an error message, it means you forgot to call `.input()` after `.addTask()`.
 */
-type NoInfer<T> = [T][T extends any ? 0 : never];
+interface TaskInputRequired<
+	TInput,
+	TOutput,
+	TIdent extends string,
+	AllOutputTypes extends Record<string, any>,
+	SourceType
+> {
+	/**
+	* Provide the input builder for this task.
+	* The builder receives the source and outputs from previous tasks.
+	* 
+	* Return `null` to skip this task - its output will be `null` in the outputs map.
+	*/
+	input(builder: (source: SourceType, outputs: AllOutputTypes) => TInput | null): Playlist<AllOutputTypes & { [K in TIdent] : Railroad<TOutput> | null }, SourceType>;
+}
 /**
 * An ordered sequence of Tasks executed with strong type inference.
 *
@@ -108,38 +104,44 @@ declare class Playlist<
 	/**
 	* Internal list of task + builder pairs in the order they will run.
 	*/
-	bundles: TaskBundle<any, any, any, any, string>[];
+	bundles: TaskBundle[];
 	/**
 	* Optional finalizer invoked after all tasks complete (successfully or not).
 	*/
 	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>);
+	constructor(bundles?: TaskBundle[], finalizer?: (source: SourceType, outputs: Record<string, any>) => void | Promise<void>);
 	/**
 	* Append a task to the end of the playlist.
+	* 
+	* Returns an object with an `input` method that accepts a builder function.
+	* The builder receives the source and all previous task outputs, and must
+	* return the input shape required by the task.
 	*
-	* The task's `ident` is used as a key in the aggregated `outputs` object made
-	* available to subsequent builders. The value under that key is the task's
-	* `Railroad<Output>` result, enabling type-safe success/error handling.
+	* @example
+	* playlist
+	*     .addTask(new MyTask("myTask"))
+	*     .input((source, outputs) => ({ value: source.startValue }))
+	*     .addTask(new AnotherTask("another"))
+	*     .input((source, outputs) => ({ 
+	*         prev: outputs.myTask.success ? outputs.myTask.data : null 
+	*     }))
 	*
-	* @template TaskInputType - Input required by the task.
-	* @template TaskOutputType - Output produced by the task.
-	* @template IdentType - The task's ident (string literal recommended).
-	* @param task - The task instance to run at this step.
-	* @param builder - Function that builds the task input from `source` and prior `outputs`.
-	* @returns A new Playlist with the output map extended to include this task's result.
+	* @template TInput - Input type required by the task.
+	* @template TOutput - Output type produced by the task.
+	* @template TIdent - The task's identifier (string literal).
+	* @param task - The task instance to add.
+	* @returns An object with an `input` method for providing the builder.
 	*/
 	addTask<
-		TaskInputType,
-		TaskOutputType,
-		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>;
+		TInput,
+		TOutput,
+		const TIdent extends string
+	>(task: Task<TInput, TOutput, TIdent>): TaskInputRequired<TInput, TOutput, TIdent, AllOutputTypes, 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.
 	*
-	* Note: The callback receives the strongly-typed `outputs` object.
+	* Note: The callback receives the strongly-typed `outputs` and `source` objects.
 	*
 	* @param finalizer - Callback executed once after all tasks complete.
 	* @returns This playlist for chaining.
@@ -148,6 +150,7 @@ declare class Playlist<
 	/**
 	* Execute all tasks in order, building each task's input via its builder
 	* and storing each result under the task's ident in the outputs map.
+	* If a builder returns `null`, the task is skipped and its output is `null`.
 	* If a task's `validateInput` returns false, execution stops with an error.
 	*
 	* @param source - The source object for this run (e.g., trigger event or machine state).
@@ -225,17 +228,11 @@ declare abstract class Trigger<
 * See README Code Examples for building a full workflow.
 *
 * @template AllTriggerEvents - Union of all trigger event shapes in this workflow.
-* @template TAllOutputs - Aggregated outputs map shape produced by the playlist.
-* @template TPlaylist - Concrete playlist type or `null` before configuration.
 */
-declare class Workflow<
-	AllTriggerEvents extends TriggerEvent<string, any>,
-	TAllOutputs extends Record<string, any>,
-	TPlaylist extends Playlist<TAllOutputs, AllTriggerEvents> | null
-> {
-	playlist: TPlaylist;
+declare class Workflow<AllTriggerEvents extends TriggerEvent<string, any>> {
+	playlist: Playlist<any, AllTriggerEvents> | null;
 	triggers: Trigger<string, any>[];
-	constructor(triggers: Trigger<string, any>[], playlist: TPlaylist);
+	constructor(triggers: Trigger<string, any>[], playlist: Playlist<any, AllTriggerEvents> | null);
 	/**
 	* Register a new trigger to feed events into the workflow.
 	* The resulting workflow type widens its `AllTriggerEvents` union accordingly.
@@ -248,23 +245,15 @@ declare class Workflow<
 	addTrigger<
 		const TIdent extends string,
 		TData
-	>(trigger: Trigger<TIdent, TData>): Workflow<AllTriggerEvents | TriggerEvent<TIdent, TData>, TAllOutputs, Playlist<TAllOutputs, AllTriggerEvents | TriggerEvent<TIdent, TData>> | null>;
+	>(trigger: Trigger<TIdent, TData>): Workflow<AllTriggerEvents | TriggerEvent<TIdent, TData>>;
 	/**
 	* Configure the playlist by providing a builder that starts from an empty
 	* `Playlist<{}, AllTriggerEvents>` and returns your fully configured playlist.
 	*
-	* This method ensures type inference flows from your tasks and idents into
-	* the resulting `TBuilderOutputs` map used by the workflow's callback.
-	*
-	* @template TBuilderOutputs - Aggregated outputs map (deduced from your tasks).
-	* @template TFinalPlaylist - Concrete playlist type returned by the builder.
 	* @param builder - Receives an empty playlist and must return a configured one.
-	* @returns A new Workflow with the concrete playlist and output types.
+	* @returns A new Workflow with the configured playlist.
 	*/
-	setPlaylist<
-		TBuilderOutputs extends Record<string, any>,
-		TFinalPlaylist extends Playlist<TBuilderOutputs, AllTriggerEvents>
-	>(builder: (p: Playlist<{}, AllTriggerEvents>) => TFinalPlaylist): Workflow<AllTriggerEvents, TBuilderOutputs, TFinalPlaylist>;
+	setPlaylist(builder: (p: Playlist<{}, AllTriggerEvents>) => Playlist<any, AllTriggerEvents>): Workflow<AllTriggerEvents>;
 	/**
 	* Begin polling triggers and run the playlist whenever an event is available.
 	* The loop uses `setTimeout` with the given `interval` and returns immediately.
@@ -275,12 +264,12 @@ declare class Workflow<
 	*/
 	start({ interval, callback }?: {
 		interval?: number
-		callback?: (source: AllTriggerEvents, outputs: TAllOutputs) => any
+		callback?: (source: AllTriggerEvents, outputs: Record<string, any>) => any
 	}): Promise<void>;
 	/**
 	* Create a new, empty workflow. Add triggers and set a playlist before starting.
 	*/
-	static create(): Workflow<never, {}, null>;
+	static create(): Workflow<never>;
 }
 type Logger = {
 	info: (...args: any[]) => void
@@ -311,11 +300,17 @@ type Transition<TStateData> = {
 * contains weighted conditional transitions to other nodes.
 *
 * @template TStateData - The shape of the external mutable state carried through the machine.
+* @template TIdent - This node's identifier (string literal).
+* @template AllStateIdents - Union of all valid state idents for transition targets.
 */
-declare class StateNode<TStateData> {
+declare class StateNode<
+	TStateData,
+	TIdent extends string = string,
+	AllStateIdents extends string = string
+> {
 	transitions?: Transition<TStateData>[];
 	playlist: Playlist<any, TStateData>;
-	ident: string;
+	ident: TIdent;
 	tempTransitions?: {
 		to: string
 		condition: (stateData: TStateData) => Promise<boolean>
@@ -327,32 +322,23 @@ declare class StateNode<TStateData> {
 	/**
 	* Create a `StateNode`.
 	*
-	* @param transitions - The resolved transitions from this node.
-	* @param playlist - The playlist to run when the node is entered.
-	*/
-	constructor(transitions: Transition<TStateData>[], playlist: Playlist<any, TStateData>);
-	/**
-	* Convenience factory for a new `StateNode` with no transitions and an empty playlist.
-	*
-	* @template TStateData
-	* @returns A new, unconfigured `StateNode`.
+	* @param ident - The unique identifier for this node.
 	*/
-	static create<TStateData>(): StateNode<TStateData>;
+	constructor(ident: TIdent);
 	/**
 	* Queue a transition to be resolved later during machine finalization.
-	* Use the target node `ident` instead of a direct reference; it will be
-	* resolved to a node instance by the machine.
+	* The `to` parameter is constrained to known state idents for autocomplete.
 	*
-	* @param to - Target state `ident`.
+	* @param to - Target state `ident` (autocompleted from known states).
 	* @param condition - Async predicate that decides if the transition should fire.
 	* @param weight - Higher weight wins when multiple conditions are true; ties keep insertion order.
 	* @returns This node for chaining.
 	*/
 	addTransition({ to, condition, weight }: {
-		to: string
+		to: AllStateIdents
 		condition: (stateData: TStateData) => Promise<boolean>
 		weight: number
-	}): StateNode<TStateData>;
+	}): StateNode<TStateData, TIdent, AllStateIdents>;
 	/**
 	* Set or build the playlist that runs when entering this node.
 	*
@@ -362,24 +348,21 @@ declare class StateNode<TStateData> {
 	* @param arg - Either a `Playlist` instance or a builder function that returns one.
 	* @returns This node for chaining.
 	*/
-	setPlaylist(playlist: Playlist<any, TStateData>): StateNode<TStateData>;
-	setPlaylist<
-		TBuilderOutputs extends Record<string, any>,
-		TFinalPlaylist extends Playlist<TBuilderOutputs, TStateData>
-	>(builder: (p: Playlist<{}, TStateData>) => TFinalPlaylist): StateNode<TStateData>;
+	setPlaylist(playlist: Playlist<any, TStateData>): StateNode<TStateData, TIdent, AllStateIdents>;
+	setPlaylist(builder: (p: Playlist<{}, TStateData>) => Playlist<any, TStateData>): StateNode<TStateData, TIdent, AllStateIdents>;
 	/**
 	* Disable retry behavior for this node during `Machine.run` when no transition is available.
 	*
 	* @returns This node for chaining.
 	*/
-	preventRetry(): StateNode<TStateData>;
+	preventRetry(): StateNode<TStateData, TIdent, AllStateIdents>;
 	/**
 	* Set the delay between retry attempts for this node during `Machine.run`.
 	*
 	* @param delayMs - Delay in milliseconds between retries.
 	* @returns This node for chaining.
 	*/
-	retryDelayMs(delayMs: number): StateNode<TStateData>;
+	retryDelayMs(delayMs: number): StateNode<TStateData, TIdent, AllStateIdents>;
 	/**
 	* Set the maximum number of retries for this node during `Machine.run`.
 	* Use `preventRetry()` to disable retries entirely.
@@ -387,14 +370,7 @@ declare class StateNode<TStateData> {
 	* @param maxRetries - Maximum number of retry attempts before giving up.
 	* @returns This node for chaining.
 	*/
-	retryLimit(maxRetries: number): StateNode<TStateData>;
-	/**
-	* Assign a unique identifier for this node. Required for transition resolution.
-	*
-	* @param ident - Unique node identifier.
-	* @returns This node for chaining.
-	*/
-	setIdent(ident: string): StateNode<TStateData>;
+	retryLimit(maxRetries: number): StateNode<TStateData, TIdent, AllStateIdents>;
 	/**
 	* Depth-first search for a node by `ident` within the reachable subgraph from this node.
 	*
@@ -413,12 +389,38 @@ declare class StateNode<TStateData> {
 	next(data: TStateData): Promise<StateNode<TStateData> | null>;
 }
 /**
+* Returned by `Machine.create()` - you must call `.withStates<...>()` to declare state idents.
+* 
+* This ensures all state identifiers are known upfront for full transition autocomplete.
+*/
+interface MachineNeedsStates<TStateData> {
+	/**
+	* Declare all state identifiers that will be used in this machine.
+	* This enables full autocomplete for transition targets.
+	* 
+	* @template TIdents - Union of all state idents (e.g., `"idle" | "running" | "complete"`).
+	* @returns The machine, ready for adding states.
+	* 
+	* @example
+	* Machine.create<MyState>()
+	*     .withStates<"idle" | "running" | "complete">()
+	*     .addState("idle", node => node
+	*         .addTransition({ to: "running", ... })  // Autocomplete works!
+	*     )
+	*/
+	withStates<TIdents extends string>(): Machine<TStateData, TIdents>;
+}
+/**
 * A finite state machine that coordinates execution of `StateNode` playlists
 * and transitions between them based on async conditions.
 *
 * @template TStateData - The shape of the external mutable state carried through the machine.
+* @template AllStateIdents - Union of all declared state identifiers.
 */
-declare class Machine<TStateData> {
+declare class Machine<
+	TStateData,
+	AllStateIdents extends string = never
+> {
 	initialState: StateNode<TStateData> | null;
 	statesToCreate: StateNode<TStateData>[];
 	private currentState;
@@ -442,12 +444,25 @@ declare class Machine<TStateData> {
 	*/
 	private sleep;
 	/**
-	* Convenience factory for a new `Machine`.
+	* Create a new Machine. You must call `.withStates<...>()` next to declare
+	* all state identifiers before adding states.
 	*
-	* @template TStateData
-	* @returns A new unfinalized machine instance.
+	* @template TStateData - The shape of the mutable state carried through the machine.
+	* @returns A machine builder that requires `.withStates()` to be called.
+	* 
+	* @example
+	* Machine.create<MyState>()
+	*     .withStates<"idle" | "running">()
+	*     .addState("idle", node => ...)
+	*/
+	static create<TStateData>(): MachineNeedsStates<TStateData>;
+	/**
+	* Declare all state identifiers for this machine.
+	* Called automatically via the `MachineNeedsStates` interface.
+	* 
+	* @internal
 	*/
-	static create<TStateData>(): Machine<TStateData>;
+	withStates<TIdents extends string>(): Machine<TStateData, TIdents>;
 	/**
 	* Finalize the machine by resolving state transitions and locking configuration.
 	* Must be called before `start` or `run`.
@@ -462,16 +477,30 @@ declare class Machine<TStateData> {
 		ident?: string
 	}): Machine<TStateData>;
 	/**
-	* Add a state to the machine.
+	* Add a state to the machine using a builder pattern.
+	* 
+	* The builder receives a StateNode with the ident already set, and with
+	* transition targets constrained to all known state idents (for autocomplete).
 	*
-	* @param state - The state node to add.
+	* @param ident - Unique identifier for this state (use a string literal).
+	* @param builder - Function that configures the state node.
 	* @param options - Options controlling how the state is added.
 	* @param options.initial - If true, marks this state as the initial state.
-	* @returns This machine for chaining.
-	*/
-	addState(state: StateNode<TStateData>, options?: {
+	* @returns This machine for chaining (with the new ident added to known states).
+	* 
+	* @example
+	* Machine.create<MyState>()
+	*     .addState("idle", node => node
+	*         .setPlaylist(p => p.addTask(...).input(...))
+	*         .addTransition({ to: "running", condition: async (s) => s.ready, weight: 1 })
+	*     , { initial: true })
+	*     .addState("running", node => node
+	*         .addTransition({ to: "idle", condition: async () => true, weight: 1 })
+	*     )
+	*/
+	addState<const TIdent extends string>(ident: TIdent, builder: (node: StateNode<TStateData, TIdent, AllStateIdents | TIdent>) => StateNode<TStateData, TIdent, AllStateIdents | TIdent>, options?: {
 		initial?: boolean
-	}): Machine<TStateData>;
+	}): Machine<TStateData, AllStateIdents | TIdent>;
 	/**
 	* Attach a logger to this machine. If the machine has an initial state set,
 	* the logger will be propagated to all currently reachable states.

package/dist/index.js

@@ -6,10 +6,14 @@ class Playlist {
     this.bundles = bundles;
     this.finalizer = finalizer;
   }
-  addTask(task, builder) {
-    const bundle = { task, builder };
-    const newBundles = [...this.bundles, bundle];
-    return new Playlist(newBundles, this.finalizer);
+  addTask(task) {
+    return {
+      input: (builder) => {
+        const bundle = { task, builder };
+        const newBundles = [...this.bundles, bundle];
+        return new Playlist(newBundles, this.finalizer);
+      }
+    };
   }
   finally(finalizer) {
     this.finalizer = finalizer;
@@ -19,6 +23,10 @@ class Playlist {
     const outputs = {};
     for (const bundle of this.bundles) {
       const input = bundle.builder(source, outputs);
+      if (input === null) {
+        outputs[bundle.task.ident] = null;
+        continue;
+      }
       const isValid = await bundle.task.validateInput(input);
       if (!isValid) {
         throw new Error(`Input validation failed for task '${bundle.task.ident}'`);
@@ -136,16 +144,13 @@ class StateNode {
   retry;
   maxRetries;
   logger;
-  constructor(transitions, playlist) {
-    this.transitions = transitions;
-    this.playlist = playlist;
-    this.ident = "";
+  constructor(ident) {
+    this.transitions = [];
+    this.playlist = new Playlist;
+    this.ident = ident;
     this.retry = 1000;
     this.maxRetries = false;
   }
-  static create() {
-    return new StateNode([], new Playlist);
-  }
   addTransition({ to, condition, weight }) {
     if (!this.tempTransitions) {
       this.tempTransitions = [];
@@ -175,10 +180,6 @@ class StateNode {
     this.maxRetries = maxRetries;
     return this;
   }
-  setIdent(ident) {
-    this.ident = ident;
-    return this;
-  }
   getByIdent(ident, visited = []) {
     if (this.ident === ident) {
       return this;
@@ -253,6 +254,9 @@ class Machine {
   static create() {
     return new Machine;
   }
+  withStates() {
+    return this;
+  }
   finalize({
     ident
   } = {}) {
@@ -301,14 +305,16 @@ class Machine {
     logger?.info({ phase: "end" }, `Machine ${this.ident} finalized.`);
     return this;
   }
-  addState(state, options = {}) {
+  addState(ident, builder, options = {}) {
     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);
+    logger?.info({ phase: "start", state: ident, isInitial: !!options.initial }, "Adding state");
+    const node = new StateNode(ident);
+    const configuredNode = builder(node);
+    this.statesToCreate.push(configuredNode);
     if (options.initial) {
-      this.initialState = state;
+      this.initialState = configuredNode;
     }
-    logger?.info({ phase: "end", state: state.ident }, "State added");
+    logger?.info({ phase: "end", state: ident }, "State added");
     return this;
   }
   addLogger(logger) {
@@ -391,7 +397,7 @@ class Machine {
       }
       const resolvedNext = next;
       if (resolvedNext === this.initialState) {
-        if (options.mode !== "infinitely") {
+        if (options.mode === "roundtrip" || options.mode === "any") {
           logger?.info({ phase: "end", reason: "roundtrip" }, "Stop condition met.");
           return stateData;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fkws/klonk",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "A lightweight, extensible workflow automation engine for Node.js and Bun",
   "repository": "https://github.com/klar-web-services/klonk",
   "homepage": "https://klonk.dev",