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

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-72';
+    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 @@
     }
     // 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.spaceTrim((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 @@
     }
 
     /**
-     * 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.spaceTrim((block) => `
+    function createPipelineIntroduction(pipelineJson) {
+        const { title, description } = pipelineJson;
+        const pipelineIntroduction = spacetrim.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((block) => `
+            ## ${title}
 
-                ${block(description || '')}
+            ${block(description || '')}
 
-                ${block(commands.map((command) => `- ${command}`).join('\n'))}
+            ${block(stringifyCommands(commands))}
 
-                \`\`\`${contentLanguage}
-                ${block(spacetrim.spaceTrim(content))}
-                \`\`\`
+            \`\`\`${contentLanguage}
+            ${block(spacetrim.spaceTrim(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_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.spaceTrim((block) => `
-                    Invalid promptbook URL "${pipeline.pipelineUrl}"
-
-                    ${block(pipelineIdentification)}
-                `));
+            dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
         }
-        if (pipeline.bookVersion !== undefined && !isValidPromptbookVersion(pipeline.bookVersion)) {
-            // <- Note: [🚲]
-            throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((block) => `
-                    Pipeline is valid JSON but with wrong structure
+        // <- Note: [🚲]
+        throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((block) => `
+        const parameterName = parameter.name;
+        throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((block) => `
-                        Parameter \`{${task.resultingParameterName}}\` is defined multiple times
+        if (RESERVED_PARAMETER_NAMES.includes(task.resultingParameterName)) {
+            throw new PipelineLogicError(spacetrim.spaceTrim((block) => `
+                    Parameter name {${task.resultingParameterName}} is reserved, please use different name
 
-                        ${block(pipelineIdentification)}
-                    `));
-            }
-            if (RESERVED_PARAMETER_NAMES.includes(task.resultingParameterName)) {
-                throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((block) => `
-                                Parameter \`{${joker}}\` is used for {${task.resultingParameterName}} as joker but not in \`dependentParameterNames\`
+            throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((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.spaceTrim((block) => `
+                Min expectation (=${min}) of ${unit} is higher than max expectation (=${max})
 
-                                ${block(pipelineIdentification)}
-                            `));
-                    }
-                    if (min !== undefined && min < 0) {
-                        throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((block) => `
+                Min expectation of ${unit} must be zero or positive
 
-                                ${block(pipelineIdentification)}
-                            `));
-                    }
-                    if (max !== undefined && max <= 0) {
-                        throw new PipelineLogicError(spacetrim.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim((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 @@
     // 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 rxjs.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 rxjs.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 @@
                 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 @@
      * @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__default["default"](hexEncoder__default["default"].parse(url)).toString( /* hex */);
-            //    <- TODO: [🥬] Encapsulate sha256 to some private utility function
-            const rootDirname = path.join(process.cwd(), DEFAULT_DOWNLOAD_CACHE_DIRNAME);
-            const filepath = path.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(path.dirname(path.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(path.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 "${path.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 = path.isAbsolute(knowledgeSourceContent)
-                ? knowledgeSourceContent
-                : path.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.spaceTrim((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 = path.join(process.cwd(), DEFAULT_DOWNLOAD_CACHE_DIRNAME);
+        const filepath = createDownloadedKnowledgeSourceFilepath(url, mimeType);
+        const fullFilepath = path.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__default["default"](hexEncoder__default["default"].parse(url)).toString( /* hex */);
+        //    <- TODO: [🥬] Encapsulate sha256 to some private utility function
+        return path.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(path.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 = path.isAbsolute(knowledgeSourceContent)
+            ? knowledgeSourceContent
+            : path.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.spaceTrim((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 @@
         }
     }
 
-    /**
-     * 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.spaceTrim((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 @@
         // 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 @@
         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.spaceTrim((block) => {
@@ -6609,7 +7103,9 @@
                     ${block(quoteMultilineText(((_b = failure.error) === null || _b === void 0 ? void 0 : _b.message) || ''))}
 
                     Result:
-                    ${block(failure.result === null ? 'null' : quoteMultilineText(spacetrim.spaceTrim(failure.result)))}
+                    ${block(failure.result === null
+            ? 'null'
+            : quoteMultilineText(spacetrim.spaceTrim(failure.result)))}
                 `;
         }))
             .join('\n\n---\n\n');
@@ -6623,6 +7119,136 @@
             .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.spaceTrim((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.
      */