@promptbook/markdown-utils 0.112.0-71 → 0.112.0-73

package/esm/index.es.js

@@ -23,7 +23,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-71';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-73';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1691,6 +1691,60 @@ function validatePipelineString(pipelineString) {
 }
 // TODO: [🧠][🈴] Where is the best location for this file
 
+/**
+ * Appends one markdown block to an existing markdown document.
+ *
+ * @private internal utility of `pipelineJsonToString`
+ */
+function appendMarkdownBlock(pipelineString, markdownBlock) {
+    return spaceTrim$1((block) => `
+            ${block(pipelineString)}
+
+            ${block(markdownBlock)}
+        `);
+}
+
+/**
+ * Collects pipeline-level commands in the existing serialization order.
+ *
+ * @private internal utility of `pipelineJsonToString`
+ */
+function createPipelineCommands(pipelineJson) {
+    const { pipelineUrl, bookVersion, parameters } = pipelineJson;
+    const commands = [];
+    if (pipelineUrl) {
+        commands.push(`PIPELINE URL ${pipelineUrl}`);
+    }
+    if (bookVersion !== `undefined`) {
+        commands.push(`BOOK VERSION ${bookVersion}`);
+    }
+    commands.push(...createParameterCommands(parameters, 'INPUT PARAMETER', ({ isInput }) => isInput));
+    commands.push(...createParameterCommands(parameters, 'OUTPUT PARAMETER', ({ isOutput }) => isOutput));
+    return commands;
+}
+/**
+ * Builds one group of parameter commands while preserving the original parameter order.
+ *
+ * @private internal utility of `createPipelineCommands`
+ */
+function createParameterCommands(parameters, commandPrefix, isIncluded) {
+    return parameters
+        .filter((parameter) => isIncluded(parameter))
+        .map((parameter) => `${commandPrefix} ${parameterJsonToString(parameter)}`);
+}
+/**
+ * Converts one parameter JSON declaration to the serialized inline form.
+ *
+ * @private internal utility of `createPipelineCommands`
+ */
+function parameterJsonToString(parameterJson) {
+    const { name, description } = parameterJson;
+    if (!description) {
+        return `{${name}}`;
+    }
+    return `{${name}} ${description}`;
+}
+
 /**
  * Prettify the html code
  *
@@ -1705,141 +1759,211 @@ function prettifyMarkdown(content) {
 }
 
 /**
- * Converts promptbook in JSON format to string format
- *
- * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
- * @param pipelineJson Promptbook in JSON format (.bookc)
- * @returns Promptbook in string format (.book.md)
+ * Creates the initial markdown heading and description of a pipeline.
  *
- * @public exported from `@promptbook/core`
+ * @private internal utility of `pipelineJsonToString`
  */
-function pipelineJsonToString(pipelineJson) {
-    const { title, pipelineUrl, bookVersion, description, parameters, tasks } = pipelineJson;
-    let pipelineString = spaceTrim$1((block) => `
+function createPipelineIntroduction(pipelineJson) {
+    const { title, description } = pipelineJson;
+    const pipelineIntroduction = spaceTrim$1((block) => `
             # ${title}
 
             ${block(description || '')}
         `);
+    // TODO: [main] !!5 This increases size of the bundle and is probably not necessary
+    return prettifyMarkdown(pipelineIntroduction);
+}
+
+/**
+ * Renders commands as markdown bullet items.
+ *
+ * @private internal utility of `pipelineJsonToString`
+ */
+function stringifyCommands(commands) {
+    return commands.map((command) => `- ${command}`).join('\n');
+}
+
+/**
+ * Collects all task-specific serialization details.
+ *
+ * @private internal utility of `pipelineJsonToString`
+ */
+function createTaskSerialization(task) {
+    const taskTypeSerialization = createTaskTypeSerialization(task);
+    return {
+        commands: [
+            ...taskTypeSerialization.commands,
+            ...createJokerCommands(task),
+            ...createPostprocessingCommands(task),
+            ...createExpectationCommands(task),
+            ...createFormatCommands(task),
+        ],
+        contentLanguage: taskTypeSerialization.contentLanguage,
+    };
+}
+/**
+ * Collects commands and content language driven by the task type.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createTaskTypeSerialization(task) {
+    if (task.taskType === 'PROMPT_TASK') {
+        return {
+            commands: createPromptTaskCommands(task),
+            contentLanguage: 'text',
+        };
+    }
+    if (task.taskType === 'SIMPLE_TASK') {
+        return {
+            commands: ['SIMPLE TEMPLATE'],
+            contentLanguage: 'text',
+        };
+    }
+    if (task.taskType === 'SCRIPT_TASK') {
+        return {
+            commands: ['SCRIPT'],
+            contentLanguage: task.contentLanguage || '',
+        };
+    }
+    if (task.taskType === 'DIALOG_TASK') {
+        return {
+            commands: ['DIALOG'],
+            contentLanguage: 'text',
+        };
+    }
+    return {
+        commands: [],
+        contentLanguage: 'text',
+    };
+}
+/**
+ * Collects prompt-task-specific commands.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createPromptTaskCommands(task) {
+    const { modelName, modelVariant } = task.modelRequirements || {};
     const commands = [];
-    if (pipelineUrl) {
-        commands.push(`PIPELINE URL ${pipelineUrl}`);
+    // Note: Do nothing, it is default
+    // commands.push(`PROMPT`);
+    if (modelVariant) {
+        commands.push(`MODEL VARIANT ${capitalize(modelVariant)}`);
     }
-    if (bookVersion !== `undefined`) {
-        commands.push(`BOOK VERSION ${bookVersion}`);
+    if (modelName) {
+        commands.push(`MODEL NAME \`${modelName}\``);
     }
-    // TODO: [main] !!5 This increases size of the bundle and is probably not necessary
-    pipelineString = prettifyMarkdown(pipelineString);
-    for (const parameter of parameters.filter(({ isInput }) => isInput)) {
-        commands.push(`INPUT PARAMETER ${taskParameterJsonToString(parameter)}`);
+    return commands;
+}
+/**
+ * Collects joker commands.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createJokerCommands(task) {
+    var _a;
+    return ((_a = task.jokerParameterNames) === null || _a === void 0 ? void 0 : _a.map((joker) => `JOKER {${joker}}`)) || [];
+}
+/**
+ * Collects postprocessing commands.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createPostprocessingCommands(task) {
+    var _a;
+    return ((_a = task.postprocessingFunctionNames) === null || _a === void 0 ? void 0 : _a.map((postprocessingFunctionName) => `POSTPROCESSING \`${postprocessingFunctionName}\``)) || [];
+}
+/**
+ * Collects expectation commands.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createExpectationCommands(task) {
+    if (!task.expectations) {
+        return [];
     }
-    for (const parameter of parameters.filter(({ isOutput }) => isOutput)) {
-        commands.push(`OUTPUT PARAMETER ${taskParameterJsonToString(parameter)}`);
+    return Object.entries(task.expectations).flatMap(([unit, expectation]) => createExpectationCommandsForUnit(unit, expectation.min, expectation.max));
+}
+/**
+ * Collects expectation commands for a single unit.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createExpectationCommandsForUnit(unit, min, max) {
+    if (min === max) {
+        return [`EXPECT EXACTLY ${min} ${formatExpectationUnit(unit, min)}`];
     }
-    pipelineString = spaceTrim$1((block) => `
-            ${block(pipelineString)}
-
-            ${block(commands.map((command) => `- ${command}`).join('\n'))}
-        `);
-    for (const task of tasks) {
-        const { 
-        /* Note: Not using:> name, */
-        title, description, 
-        /* Note: dependentParameterNames, */
-        jokerParameterNames: jokers, taskType, content, postprocessingFunctionNames: postprocessing, expectations, format, resultingParameterName, } = task;
-        const commands = [];
-        let contentLanguage = 'text';
-        if (taskType === 'PROMPT_TASK') {
-            const { modelRequirements } = task;
-            const { modelName, modelVariant } = modelRequirements || {};
-            // Note: Do nothing, it is default
-            // commands.push(`PROMPT`);
-            if (modelVariant) {
-                commands.push(`MODEL VARIANT ${capitalize(modelVariant)}`);
-            }
-            if (modelName) {
-                commands.push(`MODEL NAME \`${modelName}\``);
-            }
-        }
-        else if (taskType === 'SIMPLE_TASK') {
-            commands.push(`SIMPLE TEMPLATE`);
-            // Note: Nothing special here
-        }
-        else if (taskType === 'SCRIPT_TASK') {
-            commands.push(`SCRIPT`);
-            if (task.contentLanguage) {
-                contentLanguage = task.contentLanguage;
-            }
-            else {
-                contentLanguage = '';
-            }
-        }
-        else if (taskType === 'DIALOG_TASK') {
-            commands.push(`DIALOG`);
-            // Note: Nothing special here
-        } // <- }else if([🅱]
-        if (jokers) {
-            for (const joker of jokers) {
-                commands.push(`JOKER {${joker}}`);
-            }
-        } /* not else */
-        if (postprocessing) {
-            for (const postprocessingFunctionName of postprocessing) {
-                commands.push(`POSTPROCESSING \`${postprocessingFunctionName}\``);
-            }
-        } /* not else */
-        if (expectations) {
-            for (const [unit, { min, max }] of Object.entries(expectations)) {
-                if (min === max) {
-                    commands.push(`EXPECT EXACTLY ${min} ${capitalize(unit + (min > 1 ? 's' : ''))}`);
-                }
-                else {
-                    if (min !== undefined) {
-                        commands.push(`EXPECT MIN ${min} ${capitalize(unit + (min > 1 ? 's' : ''))}`);
-                    } /* not else */
-                    if (max !== undefined) {
-                        commands.push(`EXPECT MAX ${max} ${capitalize(unit + (max > 1 ? 's' : ''))}`);
-                    }
-                }
-            }
-        } /* not else */
-        if (format) {
-            if (format === 'JSON') {
-                // TODO: @deprecated remove
-                commands.push(`FORMAT JSON`);
-            }
-        } /* not else */
-        pipelineString = spaceTrim$1((block) => `
-                ${block(pipelineString)}
+    const commands = [];
+    if (min !== undefined) {
+        commands.push(`EXPECT MIN ${min} ${formatExpectationUnit(unit, min)}`);
+    }
+    if (max !== undefined) {
+        commands.push(`EXPECT MAX ${max} ${formatExpectationUnit(unit, max)}`);
+    }
+    return commands;
+}
+/**
+ * Formats the expectation unit exactly as the legacy serializer does.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function formatExpectationUnit(unit, amount) {
+    return capitalize(unit + (amount > 1 ? 's' : ''));
+}
+/**
+ * Collects format commands.
+ *
+ * @private internal utility of `createTaskSerialization`
+ */
+function createFormatCommands(task) {
+    if (task.format === 'JSON') {
+        // TODO: @deprecated remove
+        return ['FORMAT JSON'];
+    }
+    return [];
+}
 
-                ## ${title}
+/**
+ * Stringifies one task section of the pipeline.
+ *
+ * @private internal utility of `pipelineJsonToString`
+ */
+function stringifyTask(task) {
+    const { title, description, content, resultingParameterName } = task;
+    const { commands, contentLanguage } = createTaskSerialization(task);
+    return spaceTrim$1((block) => `
+            ## ${title}
 
-                ${block(description || '')}
+            ${block(description || '')}
 
-                ${block(commands.map((command) => `- ${command}`).join('\n'))}
+            ${block(stringifyCommands(commands))}
 
-                \`\`\`${contentLanguage}
-                ${block(spaceTrim$1(content))}
-                \`\`\`
+            \`\`\`${contentLanguage}
+            ${block(spaceTrim$1(content))}
+            \`\`\`
 
-                \`-> {${resultingParameterName}}\`
-            `); // <- TODO: [main] !!3 If the parameter here has description, add it and use taskParameterJsonToString
-        // <- TODO: [main] !!3 Escape
-        // <- TODO: [🧠] Some clear strategy how to spaceTrim the blocks
-    }
-    return validatePipelineString(pipelineString);
+            \`-> {${resultingParameterName}}\`
+        `); // <- TODO: [main] !!3 If the parameter here has description, add it and use taskParameterJsonToString
+    // <- TODO: [main] !!3 Escape
+    // <- TODO: [🧠] Some clear strategy how to spaceTrim the blocks
 }
+
 /**
- * Handles task parameter Json to string.
+ * Converts promptbook in JSON format to string format
  *
- * @private internal utility of `pipelineJsonToString`
+ * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
+ * @param pipelineJson Promptbook in JSON format (.bookc)
+ * @returns Promptbook in string format (.book.md)
+ *
+ * @public exported from `@promptbook/core`
  */
-function taskParameterJsonToString(taskParameterJson) {
-    const { name, description } = taskParameterJson;
-    let parameterString = `{${name}}`;
-    if (description) {
-        parameterString = `${parameterString} ${description}`;
+function pipelineJsonToString(pipelineJson) {
+    let pipelineString = createPipelineIntroduction(pipelineJson);
+    const pipelineCommands = createPipelineCommands(pipelineJson);
+    pipelineString = appendMarkdownBlock(pipelineString, stringifyCommands(pipelineCommands));
+    for (const task of pipelineJson.tasks) {
+        pipelineString = appendMarkdownBlock(pipelineString, stringifyTask(task));
     }
-    return parameterString;
+    return validatePipelineString(pipelineString);
 }
 // TODO: [🛋] Implement new features and commands into `pipelineJsonToString` + `taskParameterJsonToString` , use `stringifyCommand`
 // TODO: [🧠] Is there a way to auto-detect missing features in pipelineJsonToString
@@ -2279,233 +2403,519 @@ function validatePipeline(pipeline) {
  */
 function validatePipeline_InnerFunction(pipeline) {
     // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
-    const pipelineIdentification = (() => {
-        // Note: This is a 😐 implementation of [🚞]
-        const _ = [];
-        if (pipeline.sourceFile !== undefined) {
-            _.push(`File: ${pipeline.sourceFile}`);
-        }
-        if (pipeline.pipelineUrl !== undefined) {
-            _.push(`Url: ${pipeline.pipelineUrl}`);
+    const context = createPipelineValidationContext(pipeline);
+    validatePipelineMetadata(context);
+    validatePipelineCollectionsStructure(context);
+    validatePipelineParameters(context);
+    validatePipelineTasks(context);
+    validatePipelineDependencyResolution(context);
+    // Note: Check that formfactor is corresponding to the pipeline interface
+    // TODO: !!6 Implement this
+    // pipeline.formfactorName
+}
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function createPipelineValidationContext(pipeline) {
+    return {
+        pipeline,
+        pipelineIdentification: getPipelineIdentification(pipeline),
+    };
+}
+/**
+ * Builds a short file/url identification block for validation errors.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getPipelineIdentification(pipeline) {
+    // Note: This is a 😐 implementation of [🚞]
+    const pipelineIdentificationParts = [];
+    if (pipeline.sourceFile !== undefined) {
+        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
+    }
+    if (pipeline.pipelineUrl !== undefined) {
+        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
+    }
+    return pipelineIdentificationParts.join('\n');
+}
+/**
+ * Validates pipeline-level metadata fields.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineMetadata({ pipeline, pipelineIdentification }) {
+    validatePipelineUrl(pipeline, pipelineIdentification);
+    validatePipelineBookVersion(pipeline, pipelineIdentification);
+}
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification }) {
+    validatePipelineParametersCollection(pipeline, pipelineIdentification);
+    validatePipelineTasksCollection(pipeline, pipelineIdentification);
+}
+/**
+ * Validates all pipeline parameter declarations.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineParameters({ pipeline, pipelineIdentification }) {
+    for (const parameter of pipeline.parameters) {
+        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
+    }
+}
+/**
+ * Validates all pipeline tasks and their per-task invariants.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineTasks({ pipeline, pipelineIdentification }) {
+    // Note: All input parameters are defined - so that they can be used as result of some task
+    const definedParameters = createInitiallyDefinedParameters(pipeline);
+    for (const task of pipeline.tasks) {
+        validatePipelineTask(task, definedParameters, pipelineIdentification);
+    }
+}
+/**
+ * Validates that task dependencies can be resolved without cycles or missing definitions.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineDependencyResolution({ pipeline, pipelineIdentification }) {
+    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
+    let loopLimit = LOOP_LIMIT;
+    while (hasUnresolvedTasks(dependencyResolutionState)) {
+        if (loopLimit-- < 0) {
+            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
         }
-        return _.join('\n');
-    })();
-    if (pipeline.pipelineUrl !== undefined && !isValidPipelineUrl(pipeline.pipelineUrl)) {
-        // <- Note: [🚲]
-        throw new PipelineLogicError(spaceTrim$1((block) => `
-                    Invalid promptbook URL "${pipeline.pipelineUrl}"
-
-                    ${block(pipelineIdentification)}
-                `));
+        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
     }
-    if (pipeline.bookVersion !== undefined && !isValidPromptbookVersion(pipeline.bookVersion)) {
-        // <- Note: [🚲]
-        throw new PipelineLogicError(spaceTrim$1((block) => `
-                    Invalid Promptbook Version "${pipeline.bookVersion}"
-
-                    ${block(pipelineIdentification)}
-                `));
+}
+/**
+ * Validates one pipeline parameter declaration.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
+    validateParameterDirection(parameter, pipelineIdentification);
+    validateParameterUsage(parameter, pipeline, pipelineIdentification);
+    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
+}
+/**
+ * Validates one pipeline task and its invariants.
+ *
+ * @private internal step of `validatePipeline`
+ */
+function validatePipelineTask(task, definedParameters, pipelineIdentification) {
+    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
+    validateTaskJokers(task, pipelineIdentification);
+    validateTaskExpectations(task, pipelineIdentification);
+}
+/**
+ * Validates the pipeline URL, when present.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validatePipelineUrl(pipeline, pipelineIdentification) {
+    if (pipeline.pipelineUrl === undefined || isValidPipelineUrl(pipeline.pipelineUrl)) {
+        return;
     }
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (!Array.isArray(pipeline.parameters)) {
-        // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-        throw new ParseError(spaceTrim$1((block) => `
-                    Pipeline is valid JSON but with wrong structure
+    // <- Note: [🚲]
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Invalid promptbook URL "${pipeline.pipelineUrl}"
 
-                    \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
-
-                    ${block(pipelineIdentification)}
-                `));
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates the Promptbook version, when present.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validatePipelineBookVersion(pipeline, pipelineIdentification) {
+    if (pipeline.bookVersion === undefined || isValidPromptbookVersion(pipeline.bookVersion)) {
+        return;
     }
+    // <- Note: [🚲]
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Invalid Promptbook Version "${pipeline.bookVersion}"
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that `pipeline.parameters` is an array.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
     // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (!Array.isArray(pipeline.tasks)) {
-        // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-        throw new ParseError(spaceTrim$1((block) => `
-                    Pipeline is valid JSON but with wrong structure
+    if (Array.isArray(pipeline.parameters)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
 
-                    \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
 
-                    ${block(pipelineIdentification)}
-                `));
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that `pipeline.tasks` is an array.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.tasks)) {
+        return;
     }
-    /*
-    TODO: [🧠][🅾] Should be empty pipeline valid or not
-    // Note: Check that pipeline has some tasks
-    if (pipeline.tasks.length === 0) {
-        throw new PipelineLogicError(
-            spaceTrim(
-                (block) => `
-                  Pipeline must have at least one task
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
 
-                  ${block(pipelineIdentification)}
-              `,
-            ),
-        );
+                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that one parameter does not declare incompatible directions.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateParameterDirection(parameter, pipelineIdentification) {
+    if (!parameter.isInput || !parameter.isOutput) {
+        return;
     }
-    */
-    // Note: Check each parameter individually
-    for (const parameter of pipeline.parameters) {
-        if (parameter.isInput && parameter.isOutput) {
-            throw new PipelineLogicError(spaceTrim$1((block) => `
+    const parameterName = parameter.name;
+    throw new PipelineLogicError(spaceTrim$1((block) => `
 
-                        Parameter \`{${parameter.name}}\` can not be both input and output
+                Parameter \`{${parameterName}}\` can not be both input and output
 
-                        ${block(pipelineIdentification)}
-                    `));
-        }
-        // Note: Testing that parameter is either intermediate or output BUT not created and unused
-        if (!parameter.isInput &&
-            !parameter.isOutput &&
-            !pipeline.tasks.some((task) => task.dependentParameterNames.includes(parameter.name))) {
-            throw new PipelineLogicError(spaceTrim$1((block) => `
-                        Parameter \`{${parameter.name}}\` is created but not used
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that one intermediate parameter is actually consumed by at least one task.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
+    if (parameter.isInput || parameter.isOutput || isParameterUsedByAnyTask(parameter, pipeline.tasks)) {
+        return;
+    }
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Parameter \`{${parameter.name}}\` is created but not used
 
-                        You can declare {${parameter.name}} as output parameter by adding in the header:
-                        - OUTPUT PARAMETER \`{${parameter.name}}\` ${parameter.description || ''}
+                You can declare {${parameter.name}} as output parameter by adding in the header:
+                - OUTPUT PARAMETER \`{${parameter.name}}\` ${parameter.description || ''}
 
-                        ${block(pipelineIdentification)}
+                ${block(pipelineIdentification)}
 
-                    `));
-        }
-        // Note: Testing that parameter is either input or result of some task
-        if (!parameter.isInput && !pipeline.tasks.some((task) => task.resultingParameterName === parameter.name)) {
-            throw new PipelineLogicError(spaceTrim$1((block) => `
-                        Parameter \`{${parameter.name}}\` is declared but not defined
+            `));
+}
+/**
+ * Validates that one non-input parameter is produced by at least one task.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateParameterDefinition(parameter, pipeline, pipelineIdentification) {
+    if (parameter.isInput || isParameterDefinedByAnyTask(parameter, pipeline.tasks)) {
+        return;
+    }
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Parameter \`{${parameter.name}}\` is declared but not defined
 
-                        You can do one of these:
-                        1) Remove declaration of \`{${parameter.name}}\`
-                        2) Add task that results in \`-> {${parameter.name}}\`
+                You can do one of these:
+                1) Remove declaration of \`{${parameter.name}}\`
+                2) Add task that results in \`-> {${parameter.name}}\`
 
-                        ${block(pipelineIdentification)}
-                    `));
-        }
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Checks whether one parameter is consumed by at least one task dependency list.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function isParameterUsedByAnyTask(parameter, tasks) {
+    return tasks.some((task) => task.dependentParameterNames.includes(parameter.name));
+}
+/**
+ * Checks whether one parameter is produced by at least one task.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function isParameterDefinedByAnyTask(parameter, tasks) {
+    return tasks.some((task) => task.resultingParameterName === parameter.name);
+}
+/**
+ * Collects the parameter names that are already defined before task validation starts.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function createInitiallyDefinedParameters(pipeline) {
+    return new Set(pipeline.parameters.filter(({ isInput }) => isInput).map(({ name }) => name));
+}
+/**
+ * Validates one task result parameter declaration and marks it as defined.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskResultingParameter(task, definedParameters, pipelineIdentification) {
+    if (definedParameters.has(task.resultingParameterName)) {
+        throw new PipelineLogicError(spaceTrim$1((block) => `
+                    Parameter \`{${task.resultingParameterName}}\` is defined multiple times
+
+                    ${block(pipelineIdentification)}
+                `));
     }
-    // Note: All input parameters are defined - so that they can be used as result of some task
-    const definedParameters = new Set(pipeline.parameters.filter(({ isInput }) => isInput).map(({ name }) => name));
-    // Note: Checking each task individually
-    for (const task of pipeline.tasks) {
-        if (definedParameters.has(task.resultingParameterName)) {
-            throw new PipelineLogicError(spaceTrim$1((block) => `
-                        Parameter \`{${task.resultingParameterName}}\` is defined multiple times
+    if (RESERVED_PARAMETER_NAMES.includes(task.resultingParameterName)) {
+        throw new PipelineLogicError(spaceTrim$1((block) => `
+                    Parameter name {${task.resultingParameterName}} is reserved, please use different name
 
-                        ${block(pipelineIdentification)}
-                    `));
-        }
-        if (RESERVED_PARAMETER_NAMES.includes(task.resultingParameterName)) {
-            throw new PipelineLogicError(spaceTrim$1((block) => `
-                        Parameter name {${task.resultingParameterName}} is reserved, please use different name
+                    ${block(pipelineIdentification)}
+                `));
+    }
+    definedParameters.add(task.resultingParameterName);
+}
+/**
+ * Validates joker parameters for one task.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskJokers(task, pipelineIdentification) {
+    if (!hasTaskJokers(task)) {
+        return;
+    }
+    validateTaskSupportsJokers(task, pipelineIdentification);
+    validateTaskJokerDependencies(task, pipelineIdentification);
+}
+/**
+ * Checks whether one task declares any joker parameters.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function hasTaskJokers(task) {
+    return !!task.jokerParameterNames && task.jokerParameterNames.length > 0;
+}
+/**
+ * Validates that a task has the required supporting features when using jokers.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskSupportsJokers(task, pipelineIdentification) {
+    if (task.format ||
+        task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
+        return;
+    }
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Joker parameters are used for {${task.resultingParameterName}} but no expectations are defined
 
-                        ${block(pipelineIdentification)}
-                    `));
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that every joker parameter is also listed among task dependencies.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskJokerDependencies(task, pipelineIdentification) {
+    for (const joker of task.jokerParameterNames) {
+        if (task.dependentParameterNames.includes(joker)) {
+            continue;
         }
-        definedParameters.add(task.resultingParameterName);
-        if (task.jokerParameterNames && task.jokerParameterNames.length > 0) {
-            if (!task.format &&
-                !task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
-                throw new PipelineLogicError(spaceTrim$1((block) => `
-                            Joker parameters are used for {${task.resultingParameterName}} but no expectations are defined
-
-                            ${block(pipelineIdentification)}
-                        `));
-            }
-            for (const joker of task.jokerParameterNames) {
-                if (!task.dependentParameterNames.includes(joker)) {
-                    throw new PipelineLogicError(spaceTrim$1((block) => `
-                                Parameter \`{${joker}}\` is used for {${task.resultingParameterName}} as joker but not in \`dependentParameterNames\`
+        throw new PipelineLogicError(spaceTrim$1((block) => `
+                    Parameter \`{${joker}}\` is used for {${task.resultingParameterName}} as joker but not in \`dependentParameterNames\`
 
-                                ${block(pipelineIdentification)}
-                            `));
-                }
-            }
-        }
-        if (task.expectations) {
-            for (const [unit, { min, max }] of Object.entries(task.expectations)) {
-                if (min !== undefined && max !== undefined && min > max) {
-                    throw new PipelineLogicError(spaceTrim$1((block) => `
-                                Min expectation (=${min}) of ${unit} is higher than max expectation (=${max})
+                    ${block(pipelineIdentification)}
+                `));
+    }
+}
+/**
+ * Validates all expectation bounds configured on one task.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskExpectations(task, pipelineIdentification) {
+    if (!task.expectations) {
+        return;
+    }
+    for (const [unit, { min, max }] of Object.entries(task.expectations)) {
+        validateTaskExpectationRange(unit, min, max, pipelineIdentification);
+        validateTaskExpectationMin(unit, min, pipelineIdentification);
+        validateTaskExpectationMax(unit, max, pipelineIdentification);
+    }
+}
+/**
+ * Validates the minimum and maximum expectation ordering for one unit.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
+    if (min === undefined || max === undefined || min <= max) {
+        return;
+    }
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Min expectation (=${min}) of ${unit} is higher than max expectation (=${max})
 
-                                ${block(pipelineIdentification)}
-                            `));
-                }
-                if (min !== undefined && min < 0) {
-                    throw new PipelineLogicError(spaceTrim$1((block) => `
-                                Min expectation of ${unit} must be zero or positive
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates the minimum expectation bound for one unit.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskExpectationMin(unit, min, pipelineIdentification) {
+    if (min === undefined || min >= 0) {
+        return;
+    }
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Min expectation of ${unit} must be zero or positive
 
-                                ${block(pipelineIdentification)}
-                            `));
-                }
-                if (max !== undefined && max <= 0) {
-                    throw new PipelineLogicError(spaceTrim$1((block) => `
-                                Max expectation of ${unit} must be positive
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates the maximum expectation bound for one unit.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function validateTaskExpectationMax(unit, max, pipelineIdentification) {
+    if (max === undefined || max > 0) {
+        return;
+    }
+    throw new PipelineLogicError(spaceTrim$1((block) => `
+                Max expectation of ${unit} must be positive
 
-                                ${block(pipelineIdentification)}
-                            `));
-                }
-            }
-        }
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function createInitialDependencyResolutionState(pipeline) {
+    return {
+        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
+        unresolvedTasks: [...pipeline.tasks],
+    };
+}
+/**
+ * Checks whether dependency resolution still has tasks left to process.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function hasUnresolvedTasks({ unresolvedTasks }) {
+    return unresolvedTasks.length > 0;
+}
+/**
+ * Resolves the next batch of currently satisfiable tasks.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
+    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
+    if (currentlyResolvedTasks.length === 0) {
+        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
     }
-    // Note: Detect circular dependencies
-    let resovedParameters = pipeline.parameters
+    return {
+        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
+        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
+    };
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function createInitiallyResolvedParameterNames(pipeline) {
+    let resolvedParameterNames = pipeline.parameters
         .filter(({ isInput }) => isInput)
         .map(({ name }) => name);
-    // Note: All reserved parameters are resolved
     for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
-        resovedParameters = [...resovedParameters, reservedParameterName];
+        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
     }
-    let unresovedTasks = [...pipeline.tasks];
-    let loopLimit = LOOP_LIMIT;
-    while (unresovedTasks.length > 0) {
-        if (loopLimit-- < 0) {
-            // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
-            throw new UnexpectedError(spaceTrim$1((block) => `
-                        Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+    return resolvedParameterNames;
+}
+/**
+ * Adds newly resolved task outputs to the resolved parameter list.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
+    return [
+        ...resolvedParameterNames,
+        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
+    ];
+}
+/**
+ * Selects tasks whose dependencies are already resolved.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
+    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
+}
+/**
+ * Creates the unexpected loop-limit error for dependency resolution.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function createDependencyResolutionLoopLimitError(pipelineIdentification) {
+    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
+    return new UnexpectedError(spaceTrim$1((block) => `
+                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
 
-                        ${block(pipelineIdentification)}
-                    `));
-        }
-        const currentlyResovedTasks = unresovedTasks.filter((task) => task.dependentParameterNames.every((name) => resovedParameters.includes(name)));
-        if (currentlyResovedTasks.length === 0) {
-            throw new PipelineLogicError(
-            // TODO: [🐎] DRY
-            spaceTrim$1((block) => `
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Creates the detailed error for unresolved or circular task dependencies.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
+    return new PipelineLogicError(
+    // TODO: [🐎] DRY
+    spaceTrim$1((block) => `
 
-                        Can not resolve some parameters:
-                        Either you are using a parameter that is not defined, or there are some circular dependencies.
+                Can not resolve some parameters:
+                Either you are using a parameter that is not defined, or there are some circular dependencies.
 
-                        ${block(pipelineIdentification)}
+                ${block(pipelineIdentification)}
 
-                        **Can not resolve:**
-                        ${block(unresovedTasks
-                .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
-                .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
-                .join(' and ')}`)
-                .join('\n'))}
+                **Can not resolve:**
+                ${block(unresolvedTasks
+        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
+        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
+        .join(' and ')}`)
+        .join('\n'))}
 
-                        **Resolved:**
-                        ${block(resovedParameters
-                .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
-                .map((name) => `- Parameter \`{${name}}\``)
-                .join('\n'))}
+                **Resolved:**
+                ${block(resolvedParameterNames
+        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
 
 
-                        **Reserved (which are available):**
-                        ${block(resovedParameters
-                .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
-                .map((name) => `- Parameter \`{${name}}\``)
-                .join('\n'))}
+                **Reserved (which are available):**
+                ${block(resolvedParameterNames
+        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
 
 
-                    `));
-        }
-        resovedParameters = [
-            ...resovedParameters,
-            ...currentlyResovedTasks.map(({ resultingParameterName }) => resultingParameterName),
-        ];
-        unresovedTasks = unresovedTasks.filter((task) => !currentlyResovedTasks.includes(task));
-    }
-    // Note: Check that formfactor is corresponding to the pipeline interface
-    // TODO: !!6 Implement this
-    // pipeline.formfactorName
+            `));
 }
 /**
  * TODO: [🧞‍♀️] Do not allow joker + foreach
@@ -3227,170 +3637,319 @@ function assertsTaskSuccessful(executionResult) {
 // TODO: [🧠] Can this return type be better typed than void
 
 /**
- * Helper to create a new task
+ * Resolves the short task summary shown in the UI.
  *
- * @private internal helper function
+ * @private internal helper function of `ExecutionTask`
  */
-function createTask(options) {
-    const { taskType, taskProcessCallback } = options;
-    let { title } = options;
-    // TODO: [🐙] DRY
-    const taskId = `${taskType.toLowerCase().substring(0, 4)}-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
-    let status = 'RUNNING';
-    const createdAt = new Date();
-    let updatedAt = createdAt;
-    const errors = [];
-    const warnings = [];
-    const llmCalls = [];
-    let currentValue = {};
-    let customTldr = null;
-    const partialResultSubject = new Subject();
-    // <- Note: Not using `BehaviorSubject` because on error we can't access the last value
-    const finalResultPromise = /* not await */ taskProcessCallback((newOngoingResult) => {
-        if (newOngoingResult.title) {
-            title = newOngoingResult.title;
-        }
-        updatedAt = new Date();
-        Object.assign(currentValue, newOngoingResult);
-        // <- TODO: assign deep
-        partialResultSubject.next(newOngoingResult);
-    }, (tldrInfo) => {
-        customTldr = tldrInfo;
-        updatedAt = new Date();
-    }, (llmCall) => {
-        llmCalls.push(llmCall);
-        updatedAt = new Date();
-    });
-    finalResultPromise
-        .catch((error) => {
-        errors.push(error);
-        partialResultSubject.error(error);
-    })
-        .then((executionResult) => {
-        if (executionResult) {
-            try {
-                updatedAt = new Date();
-                errors.push(...executionResult.errors);
-                warnings.push(...executionResult.warnings);
-                // <- TODO: [🌂] Only unique errors and warnings should be added (or filtered)
-                // TODO: [🧠] !! errors, warning, isSuccessful  are redundant both in `ExecutionTask` and `ExecutionTask.currentValue`
-                //            Also maybe move `ExecutionTask.currentValue.usage` -> `ExecutionTask.usage`
-                //            And delete `ExecutionTask.currentValue.preparedPipeline`
-                assertsTaskSuccessful(executionResult);
-                status = 'FINISHED';
-                currentValue = jsonStringsToJsons(executionResult);
-                // <- TODO: [🧠] Is this a good idea to convert JSON strins to JSONs?
-                partialResultSubject.next(executionResult);
-            }
-            catch (error) {
-                assertsError(error);
-                status = 'ERROR';
-                errors.push(error);
-                partialResultSubject.error(error);
-            }
-        }
-        partialResultSubject.complete();
-    });
-    async function asPromise(options) {
-        const { isCrashedOnError = true } = options || {};
-        const finalResult = await finalResultPromise;
-        if (isCrashedOnError) {
-            assertsTaskSuccessful(finalResult);
-        }
-        return finalResult;
+function resolveTaskTldr(options) {
+    const { customTldr } = options;
+    if (customTldr) {
+        return customTldr;
     }
     return {
-        taskType,
-        taskId,
-        get promptbookVersion() {
-            return PROMPTBOOK_ENGINE_VERSION;
+        percent: resolveTaskPercent(options),
+        message: `${resolveTaskMessage(options)} (!!!fallback)`,
+    };
+}
+/**
+ * Resolves the best progress percentage for the current task state.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function resolveTaskPercent(options) {
+    const explicitPercent = getExplicitTaskPercent(options.currentValue);
+    if (typeof explicitPercent === 'number') {
+        return normalizeTaskPercent(explicitPercent);
+    }
+    return normalizeTaskPercent(calculateSimulatedTaskPercent(options));
+}
+/**
+ * Picks a directly reported progress percentage from the task result snapshot.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function getExplicitTaskPercent(currentValue) {
+    var _a, _b, _c, _d, _e, _f;
+    return ((_f = (_d = (_b = (_a = currentValue === null || currentValue === void 0 ? void 0 : currentValue.tldr) === null || _a === void 0 ? void 0 : _a.percent) !== null && _b !== void 0 ? _b : (_c = currentValue === null || currentValue === void 0 ? void 0 : currentValue.usage) === null || _c === void 0 ? void 0 : _c.percent) !== null && _d !== void 0 ? _d : (_e = currentValue === null || currentValue === void 0 ? void 0 : currentValue.progress) === null || _e === void 0 ? void 0 : _e.percent) !== null && _f !== void 0 ? _f : currentValue === null || currentValue === void 0 ? void 0 : currentValue.percent);
+}
+/**
+ * Simulates progress when the task result does not expose an explicit percentage.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function calculateSimulatedTaskPercent(options) {
+    const { currentValue, status, createdAt } = options;
+    const elapsedMs = new Date().getTime() - createdAt.getTime();
+    const timeProgress = Math.min(elapsedMs / DEFAULT_TASK_SIMULATED_DURATION_MS, 1);
+    const { subtaskCount, completedSubtasks } = summarizeTaskSubtasks(currentValue);
+    if (status === 'FINISHED') {
+        return 1;
+    }
+    if (status === 'ERROR') {
+        return 0;
+    }
+    return Math.min(completedSubtasks / subtaskCount + (1 / subtaskCount) * timeProgress, 1);
+}
+/**
+ * Counts total and completed subtasks used by the fallback progress simulation.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function summarizeTaskSubtasks(currentValue) {
+    if (!Array.isArray(currentValue === null || currentValue === void 0 ? void 0 : currentValue.subtasks)) {
+        return { subtaskCount: 1, completedSubtasks: 0 };
+    }
+    return {
+        subtaskCount: currentValue.subtasks.length || 1,
+        completedSubtasks: currentValue.subtasks.filter(isTaskSubtaskCompleted).length,
+    };
+}
+/**
+ * Tells whether a task subtask is already finished.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function isTaskSubtaskCompleted(subtask) {
+    return subtask.done || subtask.completed || false;
+}
+/**
+ * Normalizes a progress percentage into the expected `0..1` range.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function normalizeTaskPercent(percentRaw) {
+    let percent = Number(percentRaw) || 0;
+    if (percent < 0) {
+        percent = 0;
+    }
+    if (percent > 1) {
+        percent = 1;
+    }
+    return percent;
+}
+/**
+ * Resolves the best human-readable status message for the current task state.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function resolveTaskMessage(options) {
+    return (getCurrentValueMessage(options.currentValue) ||
+        getCurrentSubtaskMessage(options.currentValue) ||
+        getLatestIssueMessage(options.errors, 'Error') ||
+        getLatestIssueMessage(options.warnings, 'Warning') ||
+        getStatusMessage(options.status));
+}
+/**
+ * Picks a message already reported by the current task result snapshot.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function getCurrentValueMessage(currentValue) {
+    var _a, _b, _c, _d;
+    return (_d = (_c = (_b = (_a = currentValue === null || currentValue === void 0 ? void 0 : currentValue.tldr) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : currentValue === null || currentValue === void 0 ? void 0 : currentValue.message) !== null && _c !== void 0 ? _c : currentValue === null || currentValue === void 0 ? void 0 : currentValue.summary) !== null && _d !== void 0 ? _d : currentValue === null || currentValue === void 0 ? void 0 : currentValue.statusMessage;
+}
+/**
+ * Builds a fallback message from the first unfinished subtask title.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function getCurrentSubtaskMessage(currentValue) {
+    if (!Array.isArray(currentValue === null || currentValue === void 0 ? void 0 : currentValue.subtasks) || currentValue.subtasks.length === 0) {
+        return undefined;
+    }
+    const currentSubtask = currentValue.subtasks.find((subtask) => !isTaskSubtaskCompleted(subtask));
+    if (!(currentSubtask === null || currentSubtask === void 0 ? void 0 : currentSubtask.title)) {
+        return undefined;
+    }
+    return `Working on ${currentSubtask.title}`;
+}
+/**
+ * Picks the latest error or warning message, with the legacy generic fallback label.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function getLatestIssueMessage(issues, fallbackMessage) {
+    if (issues.length === 0) {
+        return undefined;
+    }
+    return issues[issues.length - 1].message || fallbackMessage;
+}
+/**
+ * Builds the final status-based fallback message.
+ *
+ * @private internal helper function of `ExecutionTask`
+ */
+function getStatusMessage(status) {
+    if (status === 'FINISHED') {
+        return 'Finished';
+    }
+    if (status === 'ERROR') {
+        return 'Error';
+    }
+    return 'Running';
+}
+
+/**
+ * Creates the initial mutable state for a task.
+ *
+ * @private internal helper function
+ */
+function createTaskState(title, createdAt) {
+    return {
+        title,
+        status: 'RUNNING',
+        updatedAt: createdAt,
+        errors: [],
+        warnings: [],
+        llmCalls: [],
+        currentValue: {},
+        customTldr: null,
+    };
+}
+/**
+ * Creates the partial-result updater passed into the task process callback.
+ *
+ * @private internal helper function
+ */
+function createOngoingResultUpdater(taskState, partialResultSubject) {
+    return (newOngoingResult) => {
+        if (newOngoingResult.title) {
+            taskState.title = newOngoingResult.title;
+        }
+        taskState.updatedAt = new Date();
+        Object.assign(taskState.currentValue, newOngoingResult);
+        // <- TODO: assign deep
+        partialResultSubject.next(newOngoingResult);
+    };
+}
+/**
+ * Creates the custom-TLDR updater passed into the task process callback.
+ *
+ * @private internal helper function
+ */
+function createTldrUpdater(taskState) {
+    return (tldrInfo) => {
+        taskState.customTldr = tldrInfo;
+        taskState.updatedAt = new Date();
+    };
+}
+/**
+ * Creates the LLM call logger passed into the task process callback.
+ *
+ * @private internal helper function
+ */
+function createLlmCallLogger(taskState) {
+    return (llmCall) => {
+        taskState.llmCalls.push(llmCall);
+        taskState.updatedAt = new Date();
+    };
+}
+/**
+ * Wires the task promise into the observable/error lifecycle.
+ *
+ * @private internal helper function
+ */
+function settleTaskPromise(finalResultPromise, taskState, partialResultSubject) {
+    finalResultPromise
+        .catch((error) => {
+        taskState.errors.push(error);
+        partialResultSubject.error(error);
+    })
+        .then((executionResult) => {
+        if (executionResult) {
+            try {
+                finalizeTaskResult(executionResult, taskState, partialResultSubject);
+            }
+            catch (error) {
+                failTaskResult(error, taskState, partialResultSubject);
+            }
+        }
+        partialResultSubject.complete();
+    });
+}
+/**
+ * Applies the final successful task result into the mutable task state.
+ *
+ * @private internal helper function
+ */
+function finalizeTaskResult(executionResult, taskState, partialResultSubject) {
+    taskState.updatedAt = new Date();
+    taskState.errors.push(...executionResult.errors);
+    taskState.warnings.push(...executionResult.warnings);
+    // <- TODO: [🌂] Only unique errors and warnings should be added (or filtered)
+    // TODO: [🧠] !! errors, warning, isSuccessful  are redundant both in `ExecutionTask` and `ExecutionTask.currentValue`
+    //            Also maybe move `ExecutionTask.currentValue.usage` -> `ExecutionTask.usage`
+    //            And delete `ExecutionTask.currentValue.preparedPipeline`
+    assertsTaskSuccessful(executionResult);
+    taskState.status = 'FINISHED';
+    taskState.currentValue = jsonStringsToJsons(executionResult);
+    // <- TODO: [🧠] Is this a good idea to convert JSON strins to JSONs?
+    partialResultSubject.next(executionResult);
+}
+/**
+ * Records a final-result failure after the task promise itself resolved.
+ *
+ * @private internal helper function
+ */
+function failTaskResult(error, taskState, partialResultSubject) {
+    assertsError(error);
+    taskState.status = 'ERROR';
+    taskState.errors.push(error);
+    partialResultSubject.error(error);
+}
+/**
+ * Helper to create a new task
+ *
+ * @private internal helper function
+ */
+function createTask(options) {
+    const { taskType, title, taskProcessCallback } = options;
+    // TODO: [🐙] DRY
+    const taskId = `${taskType.toLowerCase().substring(0, 4)}-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
+    const createdAt = new Date();
+    const taskState = createTaskState(title, createdAt);
+    const partialResultSubject = new Subject();
+    // <- Note: Not using `BehaviorSubject` because on error we can't access the last value
+    const finalResultPromise = /* not await */ taskProcessCallback(createOngoingResultUpdater(taskState, partialResultSubject), createTldrUpdater(taskState), createLlmCallLogger(taskState));
+    settleTaskPromise(finalResultPromise, taskState, partialResultSubject);
+    async function asPromise(options) {
+        const { isCrashedOnError = true } = options || {};
+        const finalResult = await finalResultPromise;
+        if (isCrashedOnError) {
+            assertsTaskSuccessful(finalResult);
+        }
+        return finalResult;
+    }
+    return {
+        taskType,
+        taskId,
+        get promptbookVersion() {
+            return PROMPTBOOK_ENGINE_VERSION;
         },
         get title() {
-            return title;
+            return taskState.title;
             // <- Note: [1] These must be getters to allow changing the value in the future
         },
         get status() {
-            return status;
+            return taskState.status;
             // <- Note: [1] --||--
         },
         get tldr() {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
-            // Use custom tldr if available
-            if (customTldr) {
-                return customTldr;
-            }
-            // Fallback to default implementation
-            const cv = currentValue;
-            // If explicit percent is provided, use it
-            let percentRaw = (_f = (_d = (_b = (_a = cv === null || cv === void 0 ? void 0 : cv.tldr) === null || _a === void 0 ? void 0 : _a.percent) !== null && _b !== void 0 ? _b : (_c = cv === null || cv === void 0 ? void 0 : cv.usage) === null || _c === void 0 ? void 0 : _c.percent) !== null && _d !== void 0 ? _d : (_e = cv === null || cv === void 0 ? void 0 : cv.progress) === null || _e === void 0 ? void 0 : _e.percent) !== null && _f !== void 0 ? _f : cv === null || cv === void 0 ? void 0 : cv.percent;
-            // Simulate progress if not provided
-            if (typeof percentRaw !== 'number') {
-                // Simulate progress: evenly split across subtasks, based on elapsed time
-                const now = new Date();
-                const elapsedMs = now.getTime() - createdAt.getTime();
-                const totalMs = DEFAULT_TASK_SIMULATED_DURATION_MS;
-                // If subtasks are defined, split progress evenly
-                const subtaskCount = Array.isArray(cv === null || cv === void 0 ? void 0 : cv.subtasks) ? cv.subtasks.length : 1;
-                const completedSubtasks = Array.isArray(cv === null || cv === void 0 ? void 0 : cv.subtasks)
-                    ? cv.subtasks.filter((s) => s.done || s.completed).length
-                    : 0;
-                // Progress from completed subtasks
-                const subtaskProgress = subtaskCount > 0 ? completedSubtasks / subtaskCount : 0;
-                // Progress from elapsed time for current subtask
-                const timeProgress = Math.min(elapsedMs / totalMs, 1);
-                // Combine: completed subtasks + time progress for current subtask
-                percentRaw = Math.min(subtaskProgress + (1 / subtaskCount) * timeProgress, 1);
-                if (status === 'FINISHED')
-                    percentRaw = 1;
-                if (status === 'ERROR')
-                    percentRaw = 0;
-            }
-            // Clamp to [0,1]
-            let percent = Number(percentRaw) || 0;
-            if (percent < 0)
-                percent = 0;
-            if (percent > 1)
-                percent = 1;
-            // Build a short message: prefer explicit tldr.message, then common summary/message fields, then errors/warnings, then status
-            const messageFromResult = (_k = (_j = (_h = (_g = cv === null || cv === void 0 ? void 0 : cv.tldr) === null || _g === void 0 ? void 0 : _g.message) !== null && _h !== void 0 ? _h : cv === null || cv === void 0 ? void 0 : cv.message) !== null && _j !== void 0 ? _j : cv === null || cv === void 0 ? void 0 : cv.summary) !== null && _k !== void 0 ? _k : cv === null || cv === void 0 ? void 0 : cv.statusMessage;
-            let message = messageFromResult;
-            if (!message) {
-                // If subtasks, show current subtask
-                if (Array.isArray(cv === null || cv === void 0 ? void 0 : cv.subtasks) && cv.subtasks.length > 0) {
-                    const current = cv.subtasks.find((s) => !s.done && !s.completed);
-                    if (current && current.title) {
-                        message = `Working on ${current.title}`;
-                    }
-                }
-                if (!message) {
-                    if (errors.length) {
-                        message = errors[errors.length - 1].message || 'Error';
-                    }
-                    else if (warnings.length) {
-                        message = warnings[warnings.length - 1].message || 'Warning';
-                    }
-                    else if (status === 'FINISHED') {
-                        message = 'Finished';
-                    }
-                    else if (status === 'ERROR') {
-                        message = 'Error';
-                    }
-                    else {
-                        message = 'Running';
-                    }
-                }
-            }
-            return {
-                percent: percent,
-                message: message + ' (!!!fallback)',
-            };
+            return resolveTaskTldr({
+                customTldr: taskState.customTldr,
+                currentValue: taskState.currentValue,
+                status: taskState.status,
+                createdAt,
+                errors: taskState.errors,
+                warnings: taskState.warnings,
+            });
         },
         get createdAt() {
             return createdAt;
             // <- Note: [1] --||--
         },
         get updatedAt() {
-            return updatedAt;
+            return taskState.updatedAt;
             // <- Note: [1] --||--
         },
         asPromise,
@@ -3398,19 +3957,19 @@ function createTask(options) {
             return partialResultSubject.asObservable();
         },
         get errors() {
-            return errors;
+            return taskState.errors;
             // <- Note: [1] --||--
         },
         get warnings() {
-            return warnings;
+            return taskState.warnings;
             // <- Note: [1] --||--
         },
         get llmCalls() {
-            return [...llmCalls, { foo: '!!! bar' }];
+            return [...taskState.llmCalls, { foo: '!!! bar' }];
             // <- Note: [1] --||--
         },
         get currentValue() {
-            return currentValue;
+            return taskState.currentValue;
             // <- Note: [1] --||--
         },
     };
@@ -4724,231 +5283,296 @@ const promptbookFetch = async (urlOrRequest, init) => {
  * @public exported from `@promptbook/core`
  */
 async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
-    var _a;
-    const { fetch = promptbookFetch } = tools;
     const { knowledgeSourceContent } = knowledgeSource;
-    let { name } = knowledgeSource;
-    const { rootDirname = null, 
-    // <- TODO: process.cwd() if running in Node.js
-    isVerbose = DEFAULT_IS_VERBOSE, } = options || {};
-    if (!name) {
-        name = knowledgeSourceContentToName(knowledgeSourceContent);
-    }
+    const name = knowledgeSource.name || knowledgeSourceContentToName(knowledgeSourceContent);
+    const { rootDirname = null, isVerbose = DEFAULT_IS_VERBOSE } = options || {};
     if (isValidUrl(knowledgeSourceContent)) {
-        const url = knowledgeSourceContent;
-        if (isVerbose) {
-            console.info(`📄 [1] "${name}" is available at "${url}"`);
-        }
-        const response = await fetch(url); // <- TODO: [🧠] Scraping and fetch proxy
-        const mimeType = ((_a = response.headers.get('content-type')) === null || _a === void 0 ? void 0 : _a.split(';')[0]) || 'text/html';
-        if (tools.fs === undefined || !url.endsWith('.pdf' /* <- TODO: [💵] */)) {
-            if (isVerbose) {
-                console.info(`📄 [2] "${name}" tools.fs is not available or URL is not a PDF.`);
-            }
-            return {
-                source: name,
-                filename: null,
-                url,
-                mimeType,
-                /*
-              TODO: [🥽]
-                  > async asBlob() {
-                  >     // TODO: [👨🏻‍🤝‍👨🏻] This can be called multiple times BUT when called second time, response in already consumed
-                  >     const content = await response.blob();
-                  >     return content;
-                  > },
-              */
-                async asJson() {
-                    // TODO: [👨🏻‍🤝‍👨🏻]
-                    const content = await response.json();
-                    return content;
-                },
-                async asText() {
-                    // TODO: [👨🏻‍🤝‍👨🏻]
-                    const content = await response.text();
-                    return content;
-                },
-            };
-        }
-        const basename = url.split('/').pop() || titleToName(url);
-        const hash = sha256(hexEncoder.parse(url)).toString( /* hex */);
-        //    <- TODO: [🥬] Encapsulate sha256 to some private utility function
-        const rootDirname = join(process.cwd(), DEFAULT_DOWNLOAD_CACHE_DIRNAME);
-        const filepath = join(...nameToSubfolderPath(hash /* <- TODO: [🎎] Maybe add some SHA256 prefix */), `${basename.substring(0, MAX_FILENAME_LENGTH)}.${mimeTypeToExtension(mimeType)}`);
-        // Note: Try to create cache directory, but don't fail if filesystem has issues
-        try {
-            await tools.fs.mkdir(dirname(join(rootDirname, filepath)), { recursive: true });
-        }
-        catch (error) {
-            if (isVerbose) {
-                console.info(`📄 [3] "${name}" error creating cache directory`);
-            }
-            // Note: If we can't create cache directory, we'll handle it when trying to write the file
-            //       This handles read-only filesystems, permission issues, and missing parent directories
-            if (error instanceof Error &&
-                (error.message.includes('EROFS') ||
-                    error.message.includes('read-only') ||
-                    error.message.includes('EACCES') ||
-                    error.message.includes('EPERM') ||
-                    error.message.includes('ENOENT'))) ;
-            else {
-                // Re-throw other unexpected errors
-                throw error;
-            }
-        }
-        const fileContent = Buffer.from(await response.arrayBuffer());
-        if (fileContent.length > DEFAULT_MAX_FILE_SIZE /* <- TODO: Allow to pass different value to remote server */) {
-            throw new LimitReachedError(`File is too large (${Math.round(fileContent.length / 1024 / 1024)}MB). Maximum allowed size is ${Math.round(DEFAULT_MAX_FILE_SIZE / 1024 / 1024)}MB.`);
-        }
-        // Note: Try to cache the downloaded file, but don't fail if the filesystem is read-only
-        try {
-            await tools.fs.writeFile(join(rootDirname, filepath), fileContent);
-        }
-        catch (error) {
-            if (isVerbose) {
-                console.info(`📄 [4] "${name}" error writing cache file`);
-            }
-            // Note: If we can't write to cache, we'll process the file directly from memory
-            //       This handles read-only filesystems like Vercel
-            if (error instanceof Error &&
-                (error.message.includes('EROFS') ||
-                    error.message.includes('read-only') ||
-                    error.message.includes('EACCES') ||
-                    error.message.includes('EPERM') ||
-                    error.message.includes('ENOENT'))) {
-                // Return a handler that works directly with the downloaded content
-                return {
-                    source: name,
-                    filename: null,
-                    url,
-                    mimeType,
-                    async asJson() {
-                        return JSON.parse(fileContent.toString('utf-8'));
-                    },
-                    async asText() {
-                        return fileContent.toString('utf-8');
-                    },
-                };
-            }
-            else {
-                // Re-throw other unexpected errors
-                throw error;
-            }
-        }
-        // TODO: [💵] Check the file security
-        // TODO: [🧹][🧠] Delete the file after the scraping is done
-        if (isVerbose) {
-            console.info(`📄 [5] "${name}" cached at "${join(rootDirname, filepath)}"`);
-        }
-        return makeKnowledgeSourceHandler({ name, knowledgeSourceContent: filepath }, tools, {
-            ...options,
-            rootDirname,
-        });
+        return makeUrlKnowledgeSourceHandler(knowledgeSourceContent, name, tools, options, isVerbose);
     }
-    else if (isValidFilePath(knowledgeSourceContent)) {
-        if (tools.fs === undefined) {
-            throw new EnvironmentMismatchError('Can not import file knowledge without filesystem tools');
-            //          <- TODO: [🧠] What is the best error type here`
-        }
-        if (rootDirname === null) {
-            throw new EnvironmentMismatchError('Can not import file knowledge in non-file pipeline');
-            //          <- TODO: [🧠] What is the best error type here`
-        }
-        const filename = isAbsolute(knowledgeSourceContent)
-            ? knowledgeSourceContent
-            : join(rootDirname, knowledgeSourceContent).split('\\').join('/');
-        if (isVerbose) {
-            console.info(`📄 [6] "${name}" is a valid file "${filename}"`);
-        }
-        const fileExtension = getFileExtension(filename);
-        const mimeType = extensionToMimeType(fileExtension || '');
-        if (!(await isFileExisting(filename, tools.fs))) {
-            throw new NotFoundError(spaceTrim$1((block) => `
-                          Can not make source handler for file which does not exist:
-
-                          File:
-                          ${block(knowledgeSourceContent)}
-
-                          Full file path:
-                          ${block(filename)}
-                      `));
-        }
-        // TODO: [🧠][😿] Test security file - file is scoped to the project (BUT maybe do this in `filesystemTools`)
-        return {
-            source: name,
-            filename,
-            url: null,
-            mimeType,
-            /*
-            TODO: [🥽]
-                > async asBlob() {
-                >     const content = await tools.fs!.readFile(filename);
-                >     return new Blob(
-                >         [
-                >             content,
-                >             // <- TODO: [🥽] This is NOT tested, test it
-                >         ],
-                >         { type: mimeType },
-                >     );
-                > },
-            */
-            async asJson() {
-                return jsonParse(await tools.fs.readFile(filename, 'utf-8'));
-            },
-            async asText() {
-                return await tools.fs.readFile(filename, 'utf-8');
-            },
-        };
+    if (isValidFilePath(knowledgeSourceContent)) {
+        return makeFileKnowledgeSourceHandler(knowledgeSourceContent, name, tools, rootDirname, isVerbose);
     }
-    else {
-        if (isVerbose) {
-            console.info(`📄 [7] "${name}" is just a explicit string text with a knowledge source`);
-            console.info('---');
-            console.info(knowledgeSourceContent);
-            console.info('---');
-        }
-        return {
-            source: name,
-            filename: null,
-            url: null,
-            mimeType: 'text/markdown',
-            asText() {
-                return knowledgeSource.knowledgeSourceContent;
-            },
-            asJson() {
-                throw new UnexpectedError('Did not expect that `markdownScraper` would need to get the content `asJson`');
-            },
-            /*
-            TODO: [🥽]
-                > asBlob() {
-                >     throw new UnexpectedError(
-                >         'Did not expect that `markdownScraper` would need to get the content `asBlob`',
-                >     );
-                > },
-            */
-        };
+    return makeInlineTextKnowledgeSourceHandler(knowledgeSourceContent, name, isVerbose);
+}
+/**
+ * Creates a source handler for URL-based knowledge.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+async function makeUrlKnowledgeSourceHandler(url, name, tools, options, isVerbose) {
+    var _a;
+    const { fetch = promptbookFetch } = tools;
+    if (isVerbose) {
+        console.info(`📄 [1] "${name}" is available at "${url}"`);
+    }
+    const response = await fetch(url); // <- TODO: [🧠] Scraping and fetch proxy
+    const mimeType = ((_a = response.headers.get('content-type')) === null || _a === void 0 ? void 0 : _a.split(';')[0]) || 'text/html';
+    if (tools.fs === undefined || !url.endsWith('.pdf' /* <- TODO: [💵] */)) {
+        return makeRemoteResponseKnowledgeSourceHandler(name, url, mimeType, response, isVerbose);
     }
+    return cachePdfKnowledgeSourceHandler(url, name, mimeType, response, tools, options, isVerbose);
 }
-
 /**
- * Prepares the knowledge pieces
+ * Creates a source handler that reads directly from a fetched response.
  *
- * @see https://github.com/webgptorg/promptbook/discussions/41
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+function makeRemoteResponseKnowledgeSourceHandler(name, url, mimeType, response, isVerbose) {
+    if (isVerbose) {
+        console.info(`📄 [2] "${name}" tools.fs is not available or URL is not a PDF.`);
+    }
+    return {
+        source: name,
+        filename: null,
+        url,
+        mimeType,
+        /*
+      TODO: [🥽]
+          > async asBlob() {
+          >     // TODO: [👨🏻‍🤝‍👨🏻] This can be called multiple times BUT when called second time, response in already consumed
+          >     const content = await response.blob();
+          >     return content;
+          > },
+      */
+        async asJson() {
+            // TODO: [👨🏻‍🤝‍👨🏻]
+            const content = await response.json();
+            return content;
+        },
+        async asText() {
+            // TODO: [👨🏻‍🤝‍👨🏻]
+            const content = await response.text();
+            return content;
+        },
+    };
+}
+/**
+ * Downloads a PDF knowledge source into cache when possible and falls back to in-memory content otherwise.
  *
- * @public exported from `@promptbook/core`
+ * @private internal utility of `makeKnowledgeSourceHandler`
  */
-async function prepareKnowledgePieces(knowledgeSources, tools, options) {
-    const { maxParallelCount = DEFAULT_MAX_PARALLEL_COUNT, rootDirname, isVerbose = DEFAULT_IS_VERBOSE } = options;
-    const knowledgePreparedUnflatten = new Array(knowledgeSources.length);
-    await forEachAsync(knowledgeSources, { maxParallelCount }, async (knowledgeSource, index) => {
-        try {
-            let partialPieces = null;
-            const sourceHandler = await makeKnowledgeSourceHandler(knowledgeSource, tools, { rootDirname, isVerbose });
-            const scrapers = arrayableToArray(tools.scrapers);
-            for (const scraper of scrapers) {
-                if (!scraper.metadata.mimeTypes.includes(sourceHandler.mimeType)
-                // <- TODO: [🦔] Implement mime-type wildcards
-                ) {
+async function cachePdfKnowledgeSourceHandler(url, name, mimeType, response, tools, options, isVerbose) {
+    const rootDirname = join(process.cwd(), DEFAULT_DOWNLOAD_CACHE_DIRNAME);
+    const filepath = createDownloadedKnowledgeSourceFilepath(url, mimeType);
+    const fullFilepath = join(rootDirname, filepath);
+    await createCacheDirectoryIfPossible(name, fullFilepath, tools, isVerbose);
+    const fileContent = Buffer.from(await response.arrayBuffer());
+    if (fileContent.length > DEFAULT_MAX_FILE_SIZE /* <- TODO: Allow to pass different value to remote server */) {
+        throw new LimitReachedError(`File is too large (${Math.round(fileContent.length / 1024 / 1024)}MB). Maximum allowed size is ${Math.round(DEFAULT_MAX_FILE_SIZE / 1024 / 1024)}MB.`);
+    }
+    const isCached = await writeCacheFileIfPossible(name, fullFilepath, fileContent, tools, isVerbose);
+    if (!isCached) {
+        return makeBufferedKnowledgeSourceHandler(name, url, mimeType, fileContent);
+    }
+    // TODO: [💵] Check the file security
+    // TODO: [🧹][🧠] Delete the file after the scraping is done
+    if (isVerbose) {
+        console.info(`📄 [5] "${name}" cached at "${fullFilepath}"`);
+    }
+    return makeKnowledgeSourceHandler({ name, knowledgeSourceContent: filepath }, tools, {
+        ...options,
+        rootDirname,
+    });
+}
+/**
+ * Builds a stable cache filepath for a downloaded knowledge source.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+function createDownloadedKnowledgeSourceFilepath(url, mimeType) {
+    const basename = url.split('/').pop() || titleToName(url);
+    const hash = sha256(hexEncoder.parse(url)).toString( /* hex */);
+    //    <- TODO: [🥬] Encapsulate sha256 to some private utility function
+    return join(...nameToSubfolderPath(hash /* <- TODO: [🎎] Maybe add some SHA256 prefix */), `${basename.substring(0, MAX_FILENAME_LENGTH)}.${mimeTypeToExtension(mimeType)}`);
+}
+/**
+ * Tries to create the cache directory needed for a downloaded knowledge source.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+async function createCacheDirectoryIfPossible(name, fullFilepath, tools, isVerbose) {
+    try {
+        await tools.fs.mkdir(dirname(fullFilepath), { recursive: true });
+    }
+    catch (error) {
+        if (isVerbose) {
+            console.info(`📄 [3] "${name}" error creating cache directory`);
+        }
+        // Note: If we can't create cache directory, we'll handle it when trying to write the file
+        //       This handles read-only filesystems, permission issues, and missing parent directories
+        if (!isIgnorableCacheFilesystemError(error)) {
+            throw error;
+        }
+    }
+}
+/**
+ * Tries to write downloaded content into cache and reports whether the cache was usable.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+async function writeCacheFileIfPossible(name, fullFilepath, fileContent, tools, isVerbose) {
+    // Note: Try to cache the downloaded file, but don't fail if the filesystem is read-only
+    try {
+        await tools.fs.writeFile(fullFilepath, fileContent);
+        return true;
+    }
+    catch (error) {
+        if (isVerbose) {
+            console.info(`📄 [4] "${name}" error writing cache file`);
+        }
+        // Note: If we can't write to cache, we'll process the file directly from memory
+        //       This handles read-only filesystems like Vercel
+        if (isIgnorableCacheFilesystemError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Detects filesystem errors that should not fail optional caching.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+function isIgnorableCacheFilesystemError(error) {
+    return (error instanceof Error &&
+        (error.message.includes('EROFS') ||
+            error.message.includes('read-only') ||
+            error.message.includes('EACCES') ||
+            error.message.includes('EPERM') ||
+            error.message.includes('ENOENT')));
+}
+/**
+ * Creates a source handler backed by already downloaded file content kept in memory.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+function makeBufferedKnowledgeSourceHandler(name, url, mimeType, fileContent) {
+    return {
+        source: name,
+        filename: null,
+        url,
+        mimeType,
+        async asJson() {
+            return JSON.parse(fileContent.toString('utf-8'));
+        },
+        async asText() {
+            return fileContent.toString('utf-8');
+        },
+    };
+}
+/**
+ * Creates a source handler for file-based knowledge.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+async function makeFileKnowledgeSourceHandler(knowledgeSourceContent, name, tools, rootDirname, isVerbose) {
+    if (tools.fs === undefined) {
+        throw new EnvironmentMismatchError('Can not import file knowledge without filesystem tools');
+        //          <- TODO: [🧠] What is the best error type here`
+    }
+    if (rootDirname === null) {
+        throw new EnvironmentMismatchError('Can not import file knowledge in non-file pipeline');
+        //          <- TODO: [🧠] What is the best error type here`
+    }
+    const filename = isAbsolute(knowledgeSourceContent)
+        ? knowledgeSourceContent
+        : join(rootDirname, knowledgeSourceContent).split('\\').join('/');
+    if (isVerbose) {
+        console.info(`📄 [6] "${name}" is a valid file "${filename}"`);
+    }
+    const fileExtension = getFileExtension(filename);
+    const mimeType = extensionToMimeType(fileExtension || '');
+    if (!(await isFileExisting(filename, tools.fs))) {
+        throw new NotFoundError(spaceTrim$1((block) => `
+                      Can not make source handler for file which does not exist:
+
+                      File:
+                      ${block(knowledgeSourceContent)}
+
+                      Full file path:
+                      ${block(filename)}
+                  `));
+    }
+    // TODO: [🧠][😿] Test security file - file is scoped to the project (BUT maybe do this in `filesystemTools`)
+    return {
+        source: name,
+        filename,
+        url: null,
+        mimeType,
+        /*
+        TODO: [🥽]
+            > async asBlob() {
+            >     const content = await tools.fs!.readFile(filename);
+            >     return new Blob(
+            >         [
+            >             content,
+            >             // <- TODO: [🥽] This is NOT tested, test it
+            >         ],
+            >         { type: mimeType },
+            >     );
+            > },
+        */
+        async asJson() {
+            return jsonParse(await tools.fs.readFile(filename, 'utf-8'));
+        },
+        async asText() {
+            return await tools.fs.readFile(filename, 'utf-8');
+        },
+    };
+}
+/**
+ * Creates a source handler for inline text knowledge.
+ *
+ * @private internal utility of `makeKnowledgeSourceHandler`
+ */
+function makeInlineTextKnowledgeSourceHandler(knowledgeSourceContent, name, isVerbose) {
+    if (isVerbose) {
+        console.info(`📄 [7] "${name}" is just a explicit string text with a knowledge source`);
+        console.info('---');
+        console.info(knowledgeSourceContent);
+        console.info('---');
+    }
+    return {
+        source: name,
+        filename: null,
+        url: null,
+        mimeType: 'text/markdown',
+        asText() {
+            return knowledgeSourceContent;
+        },
+        asJson() {
+            throw new UnexpectedError('Did not expect that `markdownScraper` would need to get the content `asJson`');
+        },
+        /*
+        TODO: [🥽]
+            > asBlob() {
+            >     throw new UnexpectedError(
+            >         'Did not expect that `markdownScraper` would need to get the content `asBlob`',
+            >     );
+            > },
+        */
+    };
+}
+
+/**
+ * Prepares the knowledge pieces
+ *
+ * @see https://github.com/webgptorg/promptbook/discussions/41
+ *
+ * @public exported from `@promptbook/core`
+ */
+async function prepareKnowledgePieces(knowledgeSources, tools, options) {
+    const { maxParallelCount = DEFAULT_MAX_PARALLEL_COUNT, rootDirname, isVerbose = DEFAULT_IS_VERBOSE } = options;
+    const knowledgePreparedUnflatten = new Array(knowledgeSources.length);
+    await forEachAsync(knowledgeSources, { maxParallelCount }, async (knowledgeSource, index) => {
+        try {
+            let partialPieces = null;
+            const sourceHandler = await makeKnowledgeSourceHandler(knowledgeSource, tools, { rootDirname, isVerbose });
+            const scrapers = arrayableToArray(tools.scrapers);
+            for (const scraper of scrapers) {
+                if (!scraper.metadata.mimeTypes.includes(sourceHandler.mimeType)
+                // <- TODO: [🦔] Implement mime-type wildcards
+                ) {
                     continue;
                 }
                 const partialPiecesUnchecked = await scraper.scrape(sourceHandler);
@@ -6112,112 +6736,10 @@ function validatePromptResult(options) {
     }
 }
 
-/**
- * Executes a pipeline task with multiple attempts, including joker and retry logic. Handles different task types
- * (prompt, script, dialog, etc.), applies postprocessing, checks expectations, and updates the execution report.
- * Throws errors if execution fails after all attempts.
- *
- * @param options - The options for execution, including task, parameters, pipeline, and configuration.
- * @returns The result string of the executed task.
- *
- * @private internal utility of `createPipelineExecutor`
- */
-async function executeAttempts(options) {
-    const $ongoingTaskResult = createOngoingTaskResult();
-    const llmTools = getSingleLlmExecutionTools(options.tools.llm);
-    attempts: for (let attemptIndex = -options.jokerParameterNames.length; attemptIndex < options.maxAttempts; attemptIndex++) {
-        const attempt = createAttemptDescriptor({
-            attemptIndex,
-            jokerParameterNames: options.jokerParameterNames,
-            pipelineIdentification: options.pipelineIdentification,
-        });
-        resetAttemptExecutionState($ongoingTaskResult);
-        try {
-            await executeSingleAttempt({
-                attempt,
-                options,
-                llmTools,
-                $ongoingTaskResult,
-            });
-            break attempts;
-        }
-        catch (error) {
-            if (!(error instanceof ExpectError)) {
-                throw error;
-            }
-            recordFailedAttempt({
-                error,
-                attemptIndex,
-                onProgress: options.onProgress,
-                $ongoingTaskResult,
-            });
-        }
-        finally {
-            reportPromptExecution({
-                attempt,
-                task: options.task,
-                $executionReport: options.$executionReport,
-                logLlmCall: options.logLlmCall,
-                $ongoingTaskResult,
-            });
-        }
-        throwIfFinalAttemptFailed({
-            attemptIndex,
-            maxAttempts: options.maxAttempts,
-            maxExecutionAttempts: options.maxExecutionAttempts,
-            pipelineIdentification: options.pipelineIdentification,
-            $ongoingTaskResult,
-        });
-    }
-    return getSuccessfulResultString({
-        pipelineIdentification: options.pipelineIdentification,
-        $ongoingTaskResult,
-    });
-}
-/**
- * Creates mutable attempt state for one task execution lifecycle.
- */
-function createOngoingTaskResult() {
-    return {
-        $result: null,
-        $resultString: null,
-        $expectError: null,
-        $scriptPipelineExecutionErrors: [],
-        $failedResults: [],
-    };
-}
-/**
- * Resolves the bookkeeping for one loop iteration, including joker lookup.
- */
-function createAttemptDescriptor(options) {
-    const { attemptIndex, jokerParameterNames, pipelineIdentification } = options;
-    const isJokerAttempt = attemptIndex < 0;
-    const jokerParameterName = isJokerAttempt
-        ? jokerParameterNames[jokerParameterNames.length + attemptIndex]
-        : undefined;
-    if (isJokerAttempt && !jokerParameterName) {
-        throw new UnexpectedError(spaceTrim$1((block) => `
-                    Joker not found in attempt ${attemptIndex}
-
-                    ${block(pipelineIdentification)}
-                `));
-    }
-    return {
-        attemptIndex,
-        isJokerAttempt,
-        jokerParameterName,
-    };
-}
-/**
- * Clears the per-attempt result slots while preserving cumulative failure history.
- */
-function resetAttemptExecutionState($ongoingTaskResult) {
-    $ongoingTaskResult.$result = null;
-    $ongoingTaskResult.$resultString = null;
-    $ongoingTaskResult.$expectError = null;
-}
 /**
  * Executes one loop iteration, from joker resolution or task execution through validation.
+ *
+ * @private function of `executeAttempts`
  */
 async function executeSingleAttempt(options) {
     const { attempt, options: executeAttemptsOptions, llmTools, $ongoingTaskResult } = options;
@@ -6532,11 +7054,15 @@ function validateAttemptResult(options) {
     // Update the result string in case format processing modified it (e.g., JSON extraction)
     $ongoingTaskResult.$resultString = validationResult.processedResultString;
 }
+
 /**
- * Stores one failed attempt and reports the expectation error upstream.
+ * Stores one failed attempt, reports the expectation error, and throws the aggregated retry error after the final
+ * regular attempt.
+ *
+ * @private function of `executeAttempts`
  */
-function recordFailedAttempt(options) {
-    const { error, attemptIndex, onProgress, $ongoingTaskResult } = options;
+function handleAttemptFailure(options) {
+    const { error, attemptIndex, maxAttempts, maxExecutionAttempts, onProgress, pipelineIdentification, $ongoingTaskResult, } = options;
     $ongoingTaskResult.$expectError = error;
     $ongoingTaskResult.$failedResults.push({
         attemptIndex,
@@ -6546,39 +7072,7 @@ function recordFailedAttempt(options) {
     onProgress({
         errors: [error],
     });
-}
-/**
- * Appends the prompt execution report for prompt-task attempts.
- */
-function reportPromptExecution(options) {
-    const { attempt, task, $executionReport, logLlmCall, $ongoingTaskResult } = options;
-    if (attempt.isJokerAttempt || task.taskType !== 'PROMPT_TASK' || !$ongoingTaskResult.$prompt) {
-        return;
-    }
-    // Note:  [2] When some expected parameter is not defined, error will occur in templateParameters
-    //        In that case we don’t want to make a report about it because it’s not a llm execution error
-    const executionPromptReport = {
-        prompt: {
-            ...$ongoingTaskResult.$prompt,
-            // <- TODO: [🧠] How to pick everyhing except `pipelineUrl`
-        },
-        result: $ongoingTaskResult.$result || undefined,
-        error: $ongoingTaskResult.$expectError === null ? undefined : serializeError($ongoingTaskResult.$expectError),
-    };
-    $executionReport.promptExecutions.push(executionPromptReport);
-    if (logLlmCall) {
-        logLlmCall({
-            modelName: 'model' /* <- TODO: How to get model name from the report */,
-            report: executionPromptReport,
-        });
-    }
-}
-/**
- * Throws the aggregated retry error after the last regular attempt fails expectations.
- */
-function throwIfFinalAttemptFailed(options) {
-    const { attemptIndex, maxAttempts, maxExecutionAttempts, pipelineIdentification, $ongoingTaskResult } = options;
-    if ($ongoingTaskResult.$expectError === null || attemptIndex !== maxAttempts - 1) {
+    if (attemptIndex !== maxAttempts - 1) {
         return;
     }
     throw new PipelineExecutionError(spaceTrim$1((block) => {
@@ -6609,7 +7103,9 @@ function createFailuresSummary($failedResults) {
                     ${block(quoteMultilineText(((_b = failure.error) === null || _b === void 0 ? void 0 : _b.message) || ''))}
 
                     Result:
-                    ${block(failure.result === null ? 'null' : quoteMultilineText(spaceTrim$1(failure.result)))}
+                    ${block(failure.result === null
+            ? 'null'
+            : quoteMultilineText(spaceTrim$1(failure.result)))}
                 `;
     }))
         .join('\n\n---\n\n');
@@ -6623,6 +7119,136 @@ function quoteMultilineText(text) {
         .map((line) => `> ${line}`)
         .join('\n');
 }
+
+/**
+ * Appends the prompt execution report for prompt-task attempts.
+ *
+ * @private function of `executeAttempts`
+ */
+function reportPromptExecution(options) {
+    const { attempt, task, $executionReport, logLlmCall, $ongoingTaskResult } = options;
+    if (attempt.isJokerAttempt || task.taskType !== 'PROMPT_TASK' || !$ongoingTaskResult.$prompt) {
+        return;
+    }
+    // Note:  [2] When some expected parameter is not defined, error will occur in templateParameters
+    //        In that case we don’t want to make a report about it because it’s not a llm execution error
+    const executionPromptReport = {
+        prompt: {
+            ...$ongoingTaskResult.$prompt,
+            // <- TODO: [🧠] How to pick everyhing except `pipelineUrl`
+        },
+        result: $ongoingTaskResult.$result || undefined,
+        error: $ongoingTaskResult.$expectError === null ? undefined : serializeError($ongoingTaskResult.$expectError),
+    };
+    $executionReport.promptExecutions.push(executionPromptReport);
+    if (logLlmCall) {
+        logLlmCall({
+            modelName: 'model' /* <- TODO: How to get model name from the report */,
+            report: executionPromptReport,
+        });
+    }
+}
+
+/**
+ * Executes a pipeline task with multiple attempts, including joker and retry logic. Handles different task types
+ * (prompt, script, dialog, etc.), applies postprocessing, checks expectations, and updates the execution report.
+ * Throws errors if execution fails after all attempts.
+ *
+ * @param options - The options for execution, including task, parameters, pipeline, and configuration.
+ * @returns The result string of the executed task.
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+async function executeAttempts(options) {
+    const $ongoingTaskResult = createOngoingTaskResult();
+    const llmTools = getSingleLlmExecutionTools(options.tools.llm);
+    attempts: for (let attemptIndex = -options.jokerParameterNames.length; attemptIndex < options.maxAttempts; attemptIndex++) {
+        const attempt = createAttemptDescriptor({
+            attemptIndex,
+            jokerParameterNames: options.jokerParameterNames,
+            pipelineIdentification: options.pipelineIdentification,
+        });
+        resetAttemptExecutionState($ongoingTaskResult);
+        try {
+            await executeSingleAttempt({
+                attempt,
+                options,
+                llmTools,
+                $ongoingTaskResult,
+            });
+            break attempts;
+        }
+        catch (error) {
+            if (!(error instanceof ExpectError)) {
+                throw error;
+            }
+            handleAttemptFailure({
+                error,
+                attemptIndex,
+                maxAttempts: options.maxAttempts,
+                maxExecutionAttempts: options.maxExecutionAttempts,
+                onProgress: options.onProgress,
+                pipelineIdentification: options.pipelineIdentification,
+                $ongoingTaskResult,
+            });
+        }
+        finally {
+            reportPromptExecution({
+                attempt,
+                task: options.task,
+                $executionReport: options.$executionReport,
+                logLlmCall: options.logLlmCall,
+                $ongoingTaskResult,
+            });
+        }
+    }
+    return getSuccessfulResultString({
+        pipelineIdentification: options.pipelineIdentification,
+        $ongoingTaskResult,
+    });
+}
+/**
+ * Creates mutable attempt state for one task execution lifecycle.
+ */
+function createOngoingTaskResult() {
+    return {
+        $result: null,
+        $resultString: null,
+        $expectError: null,
+        $scriptPipelineExecutionErrors: [],
+        $failedResults: [],
+    };
+}
+/**
+ * Resolves the bookkeeping for one loop iteration, including joker lookup.
+ */
+function createAttemptDescriptor(options) {
+    const { attemptIndex, jokerParameterNames, pipelineIdentification } = options;
+    const isJokerAttempt = attemptIndex < 0;
+    const jokerParameterName = isJokerAttempt
+        ? jokerParameterNames[jokerParameterNames.length + attemptIndex]
+        : undefined;
+    if (isJokerAttempt && !jokerParameterName) {
+        throw new UnexpectedError(spaceTrim$1((block) => `
+                    Joker not found in attempt ${attemptIndex}
+
+                    ${block(pipelineIdentification)}
+                `));
+    }
+    return {
+        attemptIndex,
+        isJokerAttempt,
+        jokerParameterName,
+    };
+}
+/**
+ * Clears the per-attempt result slots while preserving cumulative failure history.
+ */
+function resetAttemptExecutionState($ongoingTaskResult) {
+    $ongoingTaskResult.$result = null;
+    $ongoingTaskResult.$resultString = null;
+    $ongoingTaskResult.$expectError = null;
+}
 /**
  * Returns the successful result string or raises an unexpected internal-state error.
  */