@promptbook/remote-server 0.89.0-2 → 0.89.0-20

package/esm/index.es.js

@@ -2,7 +2,9 @@ import colors from 'colors';
 import express from 'express';
 import http from 'http';
 import { Server } from 'socket.io';
-import spaceTrim$1, { spaceTrim } from 'spacetrim';
+import spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
+import swaggerJsdoc from 'swagger-jsdoc';
+import swaggerUi from 'swagger-ui-express';
 import { forTime } from 'waitasecond';
 import { randomBytes } from 'crypto';
 import { spawn } from 'child_process';
@@ -31,7 +33,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.89.0-2';
+const PROMPTBOOK_ENGINE_VERSION = '0.89.0-20';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -85,6 +87,7 @@ const ADMIN_GITHUB_NAME = 'hejny';
  * @public exported from `@promptbook/core`
  */
 const CLAIM = `It's time for a paradigm shift. The future of software in plain English, French or Latin`;
+//            <- TODO: [🐊] Pick the best claim
 /**
  * When the title is not provided, the default title is used
  *
@@ -117,6 +120,7 @@ const VALUE_STRINGS = {
     infinity: '(infinity; ∞)',
     negativeInfinity: '(negative infinity; -∞)',
     unserializable: '(unserializable value)',
+    circular: '(circular JSON)',
 };
 /**
  * Small number limit
@@ -156,6 +160,7 @@ const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
  */
 const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
 // <- TODO: [🕝] Make also `BOOKS_DIRNAME_ALTERNATIVES`
+// TODO: Just `.promptbook` in config, hardcode subfolders like `download-cache` or `execution-cache`
 /**
  * Where to store the temporary downloads
  *
@@ -207,9 +212,138 @@ const IS_PIPELINE_LOGIC_VALIDATED = just(
 true);
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
- * TODO: [🧠][🧜‍♂️] Maybe join remoteUrl and path into single value
+ * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
  */
 
+/**
+ * Make error report URL for the given error
+ *
+ * @private private within the repository
+ */
+function getErrorReportUrl(error) {
+    const report = {
+        title: `🐜 Error report from ${NAME}`,
+        body: spaceTrim((block) => `
+
+
+            \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
+
+            \`\`\`
+            ${block(error.message || '(no error message)')}
+            \`\`\`
+
+
+            ## More info:
+
+            - **Promptbook engine version:** ${PROMPTBOOK_ENGINE_VERSION}
+            - **Book language version:** ${BOOK_LANGUAGE_VERSION}
+            - **Time:** ${new Date().toISOString()}
+
+            <details>
+            <summary>Stack trace:</summary>
+
+            ## Stack trace:
+
+            \`\`\`stacktrace
+            ${block(error.stack || '(empty)')}
+            \`\`\`
+            </details>
+
+        `),
+    };
+    const reportUrl = new URL(`https://github.com/webgptorg/promptbook/issues/new`);
+    reportUrl.searchParams.set('labels', 'bug');
+    reportUrl.searchParams.set('assignees', ADMIN_GITHUB_NAME);
+    reportUrl.searchParams.set('title', report.title);
+    reportUrl.searchParams.set('body', report.body);
+    return reportUrl;
+}
+
+/**
+ * This error type indicates that the error should not happen and its last check before crashing with some other error
+ *
+ * @public exported from `@promptbook/core`
+ */
+class UnexpectedError extends Error {
+    constructor(message) {
+        super(spaceTrim$1((block) => `
+                    ${block(message)}
+
+                    Note: This error should not happen.
+                    It's probbably a bug in the pipeline collection
+
+                    Please report issue:
+                    ${block(getErrorReportUrl(new Error(message)).href)}
+
+                    Or contact us on ${ADMIN_EMAIL}
+
+                `));
+        this.name = 'UnexpectedError';
+        Object.setPrototypeOf(this, UnexpectedError.prototype);
+    }
+}
+
+/**
+ * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+ *
+ * @public exported from `@promptbook/core`
+ */
+class WrappedError extends Error {
+    constructor(whatWasThrown) {
+        const tag = `[🤮]`;
+        console.error(tag, whatWasThrown);
+        super(spaceTrim$1(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+        this.name = 'WrappedError';
+        Object.setPrototypeOf(this, WrappedError.prototype);
+    }
+}
+
+/**
+ * Helper used in catch blocks to assert that the error is an instance of `Error`
+ *
+ * @param whatWasThrown Any object that was thrown
+ * @returns Nothing if the error is an instance of `Error`
+ * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ *
+ * @private within the repository
+ */
+function assertsError(whatWasThrown) {
+    // Case 1: Handle error which was rethrown as `WrappedError`
+    if (whatWasThrown instanceof WrappedError) {
+        const wrappedError = whatWasThrown;
+        throw wrappedError;
+    }
+    // Case 2: Handle unexpected errors
+    if (whatWasThrown instanceof UnexpectedError) {
+        const unexpectedError = whatWasThrown;
+        throw unexpectedError;
+    }
+    // Case 3: Handle standard errors - keep them up to consumer
+    if (whatWasThrown instanceof Error) {
+        return;
+    }
+    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+    throw new WrappedError(whatWasThrown);
+}
+
+/**
+ * AuthenticationError is thrown from login function which is dependency of remote server
+ *
+ * @public exported from `@promptbook/core`
+ */
+class AuthenticationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+
 /**
  * Generates random token
  *
@@ -241,7 +375,7 @@ class PipelineExecutionError extends Error {
     }
 }
 /**
- * TODO: !!!!!! Add id to all errors
+ * TODO: [🧠][🌂] Add id to all errors
  */
 
 /**
@@ -349,7 +483,7 @@ class LimitReachedError extends Error {
  */
 class MissingToolsError extends Error {
     constructor(message) {
-        super(spaceTrim((block) => `
+        super(spaceTrim$1((block) => `
                     ${block(message)}
 
                     Note: You have probbably forgot to provide some tools for pipeline execution or preparation
@@ -380,7 +514,7 @@ class NotFoundError extends Error {
  */
 class NotYetImplementedError extends Error {
     constructor(message) {
-        super(spaceTrim((block) => `
+        super(spaceTrim$1((block) => `
                     ${block(message)}
 
                     Note: This feature is not implemented yet but it will be soon.
@@ -439,70 +573,15 @@ class PipelineUrlError extends Error {
 }
 
 /**
- * Make error report URL for the given error
- *
- * @private private within the repository
- */
-function getErrorReportUrl(error) {
-    const report = {
-        title: `🐜 Error report from ${NAME}`,
-        body: spaceTrim$1((block) => `
-
-
-            \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
-
-            \`\`\`
-            ${block(error.message || '(no error message)')}
-            \`\`\`
-
-
-            ## More info:
-
-            - **Promptbook engine version:** ${PROMPTBOOK_ENGINE_VERSION}
-            - **Book language version:** ${BOOK_LANGUAGE_VERSION}
-            - **Time:** ${new Date().toISOString()}
-
-            <details>
-            <summary>Stack trace:</summary>
-
-            ## Stack trace:
-
-            \`\`\`stacktrace
-            ${block(error.stack || '(empty)')}
-            \`\`\`
-            </details>
-
-        `),
-    };
-    const reportUrl = new URL(`https://github.com/webgptorg/promptbook/issues/new`);
-    reportUrl.searchParams.set('labels', 'bug');
-    reportUrl.searchParams.set('assignees', ADMIN_GITHUB_NAME);
-    reportUrl.searchParams.set('title', report.title);
-    reportUrl.searchParams.set('body', report.body);
-    return reportUrl;
-}
-
-/**
- * This error type indicates that the error should not happen and its last check before crashing with some other error
+ * Error thrown when a fetch request fails
  *
  * @public exported from `@promptbook/core`
  */
-class UnexpectedError extends Error {
+class PromptbookFetchError extends Error {
     constructor(message) {
-        super(spaceTrim((block) => `
-                    ${block(message)}
-
-                    Note: This error should not happen.
-                    It's probbably a bug in the pipeline collection
-
-                    Please report issue:
-                    ${block(getErrorReportUrl(new Error(message)).href)}
-
-                    Or contact us on ${ADMIN_EMAIL}
-
-                `));
-        this.name = 'UnexpectedError';
-        Object.setPrototypeOf(this, UnexpectedError.prototype);
+        super(message);
+        this.name = 'PromptbookFetchError';
+        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
     }
 }
 
@@ -526,7 +605,10 @@ const PROMPTBOOK_ERRORS = {
     PipelineExecutionError,
     PipelineLogicError,
     PipelineUrlError,
+    AuthenticationError,
+    PromptbookFetchError,
     UnexpectedError,
+    WrappedError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -574,10 +656,14 @@ function serializeError(error) {
     const { name, message, stack } = error;
     const { id } = error;
     if (!Object.keys(ALL_ERRORS).includes(name)) {
-        console.error(spaceTrim$1((block) => `
+        console.error(spaceTrim((block) => `
 
                     Cannot serialize error with name "${name}"
 
+                    Authors of Promptbook probably forgot to add this error into the list of errors:
+                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
+
+
                     ${block(stack || message)}
 
                 `));
@@ -734,11 +820,11 @@ function $execCommand(options) {
                             console.warn(`Command "${humanReadableCommand}" exited with code ${code}`);
                             // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
                         }
-                        resolve(spaceTrim(output.join('\n')));
+                        resolve(spaceTrim$1(output.join('\n')));
                     }
                 }
                 else {
-                    resolve(spaceTrim(output.join('\n')));
+                    resolve(spaceTrim$1(output.join('\n')));
                 }
             };
             commandProcess.on('close', finishWithCode);
@@ -756,7 +842,7 @@ function $execCommand(options) {
                         console.warn(error);
                         // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
                     }
-                    resolve(spaceTrim(output.join('\n')));
+                    resolve(spaceTrim$1(output.join('\n')));
                 }
             });
         }
@@ -781,9 +867,7 @@ async function locateAppOnLinux({ linuxWhich, }) {
         return result.trim();
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         return null;
     }
 }
@@ -861,9 +945,7 @@ async function locateAppOnMacOs({ macOsName, }) {
         return result.trim() + toExec;
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         return null;
     }
 }
@@ -894,9 +976,7 @@ async function locateAppOnWindows({ appName, windowsSuffix, }) {
         throw new Error(`Can not locate app ${appName} on Windows.`);
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         return null;
     }
 }
@@ -1093,7 +1173,7 @@ function checkSerializableAsJson(options) {
     }
     else if (typeof value === 'object') {
         if (value instanceof Date) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
+            throw new UnexpectedError(spaceTrim((block) => `
                         \`${name}\` is Date
 
                         Use \`string_date_iso8601\` instead
@@ -1112,7 +1192,7 @@ function checkSerializableAsJson(options) {
             throw new UnexpectedError(`${name} is RegExp`);
         }
         else if (value instanceof Error) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
+            throw new UnexpectedError(spaceTrim((block) => `
                         \`${name}\` is unserialized Error
 
                         Use function \`serializeError\`
@@ -1134,10 +1214,8 @@ function checkSerializableAsJson(options) {
                 JSON.stringify(value); // <- TODO: [0]
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
-                throw new UnexpectedError(spaceTrim$1((block) => `
+                assertsError(error);
+                throw new UnexpectedError(spaceTrim((block) => `
                             \`${name}\` is not serializable
 
                             ${block(error.stack || error.message)}
@@ -1169,7 +1247,7 @@ function checkSerializableAsJson(options) {
         }
     }
     else {
-        throw new UnexpectedError(spaceTrim$1((block) => `
+        throw new UnexpectedError(spaceTrim((block) => `
                     \`${name}\` is unknown type
 
                     Additional message for \`${name}\`:
@@ -1432,7 +1510,7 @@ function validatePipeline(pipeline) {
             if (!(error instanceof PipelineLogicError)) {
                 throw error;
             }
-            console.error(spaceTrim((block) => `
+            console.error(spaceTrim$1((block) => `
                         Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
 
                         ${block(error.message)}
@@ -1459,7 +1537,7 @@ function validatePipeline_InnerFunction(pipeline) {
     })();
     if (pipeline.pipelineUrl !== undefined && !isValidPipelineUrl(pipeline.pipelineUrl)) {
         // <- Note: [🚲]
-        throw new PipelineLogicError(spaceTrim((block) => `
+        throw new PipelineLogicError(spaceTrim$1((block) => `
                     Invalid promptbook URL "${pipeline.pipelineUrl}"
 
                     ${block(pipelineIdentification)}
@@ -1467,7 +1545,7 @@ function validatePipeline_InnerFunction(pipeline) {
     }
     if (pipeline.bookVersion !== undefined && !isValidPromptbookVersion(pipeline.bookVersion)) {
         // <- Note: [🚲]
-        throw new PipelineLogicError(spaceTrim((block) => `
+        throw new PipelineLogicError(spaceTrim$1((block) => `
                     Invalid Promptbook Version "${pipeline.bookVersion}"
 
                     ${block(pipelineIdentification)}
@@ -1476,7 +1554,7 @@ function validatePipeline_InnerFunction(pipeline) {
     // TODO: [🧠] Maybe do here some propper JSON-schema / ZOD checking
     if (!Array.isArray(pipeline.parameters)) {
         // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-        throw new ParseError(spaceTrim((block) => `
+        throw new ParseError(spaceTrim$1((block) => `
                     Pipeline is valid JSON but with wrong structure
 
                     \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
@@ -1487,7 +1565,7 @@ function validatePipeline_InnerFunction(pipeline) {
     // TODO: [🧠] Maybe do here some propper JSON-schema / ZOD checking
     if (!Array.isArray(pipeline.tasks)) {
         // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-        throw new ParseError(spaceTrim((block) => `
+        throw new ParseError(spaceTrim$1((block) => `
                     Pipeline is valid JSON but with wrong structure
 
                     \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
@@ -1513,7 +1591,7 @@ function validatePipeline_InnerFunction(pipeline) {
     // Note: Check each parameter individually
     for (const parameter of pipeline.parameters) {
         if (parameter.isInput && parameter.isOutput) {
-            throw new PipelineLogicError(spaceTrim((block) => `
+            throw new PipelineLogicError(spaceTrim$1((block) => `
 
                         Parameter \`{${parameter.name}}\` can not be both input and output
 
@@ -1524,7 +1602,7 @@ function validatePipeline_InnerFunction(pipeline) {
         if (!parameter.isInput &&
             !parameter.isOutput &&
             !pipeline.tasks.some((task) => task.dependentParameterNames.includes(parameter.name))) {
-            throw new PipelineLogicError(spaceTrim((block) => `
+            throw new PipelineLogicError(spaceTrim$1((block) => `
                         Parameter \`{${parameter.name}}\` is created but not used
 
                         You can declare {${parameter.name}} as output parameter by adding in the header:
@@ -1536,7 +1614,7 @@ function validatePipeline_InnerFunction(pipeline) {
         }
         // 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((block) => `
+            throw new PipelineLogicError(spaceTrim$1((block) => `
                         Parameter \`{${parameter.name}}\` is declared but not defined
 
                         You can do one of these:
@@ -1552,14 +1630,14 @@ function validatePipeline_InnerFunction(pipeline) {
     // Note: Checking each task individually
     for (const task of pipeline.tasks) {
         if (definedParameters.has(task.resultingParameterName)) {
-            throw new PipelineLogicError(spaceTrim((block) => `
+            throw new PipelineLogicError(spaceTrim$1((block) => `
                         Parameter \`{${task.resultingParameterName}}\` is defined multiple times
 
                         ${block(pipelineIdentification)}
                     `));
         }
         if (RESERVED_PARAMETER_NAMES.includes(task.resultingParameterName)) {
-            throw new PipelineLogicError(spaceTrim((block) => `
+            throw new PipelineLogicError(spaceTrim$1((block) => `
                         Parameter name {${task.resultingParameterName}} is reserved, please use different name
 
                         ${block(pipelineIdentification)}
@@ -1569,7 +1647,7 @@ function validatePipeline_InnerFunction(pipeline) {
         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((block) => `
+                throw new PipelineLogicError(spaceTrim$1((block) => `
                             Joker parameters are used for {${task.resultingParameterName}} but no expectations are defined
 
                             ${block(pipelineIdentification)}
@@ -1577,7 +1655,7 @@ function validatePipeline_InnerFunction(pipeline) {
             }
             for (const joker of task.jokerParameterNames) {
                 if (!task.dependentParameterNames.includes(joker)) {
-                    throw new PipelineLogicError(spaceTrim((block) => `
+                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                 Parameter \`{${joker}}\` is used for {${task.resultingParameterName}} as joker but not in \`dependentParameterNames\`
 
                                 ${block(pipelineIdentification)}
@@ -1588,21 +1666,21 @@ function validatePipeline_InnerFunction(pipeline) {
         if (task.expectations) {
             for (const [unit, { min, max }] of Object.entries(task.expectations)) {
                 if (min !== undefined && max !== undefined && min > max) {
-                    throw new PipelineLogicError(spaceTrim((block) => `
+                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                 Min expectation (=${min}) of ${unit} is higher than max expectation (=${max})
 
                                 ${block(pipelineIdentification)}
                             `));
                 }
                 if (min !== undefined && min < 0) {
-                    throw new PipelineLogicError(spaceTrim((block) => `
+                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                 Min expectation of ${unit} must be zero or positive
 
                                 ${block(pipelineIdentification)}
                             `));
                 }
                 if (max !== undefined && max <= 0) {
-                    throw new PipelineLogicError(spaceTrim((block) => `
+                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                 Max expectation of ${unit} must be positive
 
                                 ${block(pipelineIdentification)}
@@ -1624,7 +1702,7 @@ function validatePipeline_InnerFunction(pipeline) {
     while (unresovedTasks.length > 0) {
         if (loopLimit-- < 0) {
             // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
-            throw new UnexpectedError(spaceTrim((block) => `
+            throw new UnexpectedError(spaceTrim$1((block) => `
                         Loop limit reached during detection of circular dependencies in \`validatePipeline\`
 
                         ${block(pipelineIdentification)}
@@ -1634,7 +1712,7 @@ function validatePipeline_InnerFunction(pipeline) {
         if (currentlyResovedTasks.length === 0) {
             throw new PipelineLogicError(
             // TODO: [🐎] DRY
-            spaceTrim((block) => `
+            spaceTrim$1((block) => `
 
                         Can not resolve some parameters:
                         Either you are using a parameter that is not defined, or there are some circular dependencies.
@@ -1744,9 +1822,7 @@ function isValidJsonString(value /* <- [👨‍⚖️] */) {
         return true;
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         if (error.message.includes('Unexpected token')) {
             return false;
         }
@@ -1798,7 +1874,7 @@ function deserializeError(error) {
         message = `${name}: ${message}`;
     }
     if (stack !== undefined && stack !== '') {
-        message = spaceTrim$1((block) => `
+        message = spaceTrim((block) => `
                 ${block(message)}
 
                 Original stack trace:
@@ -1835,11 +1911,11 @@ function assertsTaskSuccessful(executionResult) {
         throw deserializeError(errors[0]);
     }
     else {
-        throw new PipelineExecutionError(spaceTrim((block) => `
+        throw new PipelineExecutionError(spaceTrim$1((block) => `
                     Multiple errors occurred during Promptbook execution
 
                     ${block(errors
-            .map(({ name, stack, message }, index) => spaceTrim((block) => `
+            .map(({ name, stack, message }, index) => spaceTrim$1((block) => `
                                         ${name} ${index + 1}:
                                         ${block(stack || message)}
                                     `))
@@ -1884,8 +1960,8 @@ function createTask(options) {
                 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`
+                // <- 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);
@@ -1895,6 +1971,7 @@ function createTask(options) {
                 partialResultSubject.next(executionResult);
             }
             catch (error) {
+                assertsError(error);
                 status = 'ERROR';
                 errors.push(error);
                 partialResultSubject.error(error);
@@ -2197,7 +2274,7 @@ function pipelineJsonToString(pipelineJson) {
         pipelineString += '\n\n';
         pipelineString += '```' + contentLanguage;
         pipelineString += '\n';
-        pipelineString += spaceTrim$1(content);
+        pipelineString += spaceTrim(content);
         //                   <- TODO: [main] !!3 Escape
         //                   <- TODO: [🧠] Some clear strategy how to spaceTrim the blocks
         pipelineString += '\n';
@@ -2302,7 +2379,7 @@ class SimplePipelineCollection {
         for (const pipeline of pipelines) {
             // TODO: [👠] DRY
             if (pipeline.pipelineUrl === undefined) {
-                throw new PipelineUrlError(spaceTrim(`
+                throw new PipelineUrlError(spaceTrim$1(`
                         Pipeline with name "${pipeline.title}" does not have defined URL
 
                         File:
@@ -2324,7 +2401,7 @@ class SimplePipelineCollection {
                 pipelineJsonToString(unpreparePipeline(pipeline)) !==
                     pipelineJsonToString(unpreparePipeline(this.collection.get(pipeline.pipelineUrl)))) {
                 const existing = this.collection.get(pipeline.pipelineUrl);
-                throw new PipelineUrlError(spaceTrim(`
+                throw new PipelineUrlError(spaceTrim$1(`
                         Pipeline with URL ${pipeline.pipelineUrl} is already in the collection 🍎
 
                         Conflicting files:
@@ -2356,13 +2433,13 @@ class SimplePipelineCollection {
         const pipeline = this.collection.get(url);
         if (!pipeline) {
             if (this.listPipelines().length === 0) {
-                throw new NotFoundError(spaceTrim(`
+                throw new NotFoundError(spaceTrim$1(`
                             Pipeline with url "${url}" not found
 
                             No pipelines available
                         `));
             }
-            throw new NotFoundError(spaceTrim((block) => `
+            throw new NotFoundError(spaceTrim$1((block) => `
                         Pipeline with url "${url}" not found
 
                         Available pipelines:
@@ -2705,14 +2782,15 @@ class MultipleLlmExecutionTools {
                 }
             }
             catch (error) {
-                if (!(error instanceof Error) || error instanceof UnexpectedError) {
+                assertsError(error);
+                if (error instanceof UnexpectedError) {
                     throw error;
                 }
                 errors.push({ llmExecutionTools, error });
             }
         }
         if (errors.length === 1) {
-            throw errors[0];
+            throw errors[0].error;
         }
         else if (errors.length > 1) {
             throw new PipelineExecutionError(
@@ -2720,7 +2798,7 @@ class MultipleLlmExecutionTools {
             //     1) OpenAI throw PipelineExecutionError: Parameter `{knowledge}` is not defined
             //     2) AnthropicClaude throw PipelineExecutionError: Parameter `{knowledge}` is not defined
             //     3) ...
-            spaceTrim$1((block) => `
+            spaceTrim((block) => `
                           All execution tools failed:
 
                           ${block(errors
@@ -2733,7 +2811,7 @@ class MultipleLlmExecutionTools {
             throw new PipelineExecutionError(`You have not provided any \`LlmExecutionTools\``);
         }
         else {
-            throw new PipelineExecutionError(spaceTrim$1((block) => `
+            throw new PipelineExecutionError(spaceTrim((block) => `
                           You have not provided any \`LlmExecutionTools\` that support model variant "${prompt.modelRequirements.modelVariant}"
 
                           Available \`LlmExecutionTools\`:
@@ -2766,7 +2844,7 @@ class MultipleLlmExecutionTools {
  */
 function joinLlmExecutionTools(...llmExecutionTools) {
     if (llmExecutionTools.length === 0) {
-        const warningMessage = spaceTrim$1(`
+        const warningMessage = spaceTrim(`
             You have not provided any \`LlmExecutionTools\`
             This means that you won't be able to execute any prompts that require large language models like GPT-4 or Anthropic's Claude.
 
@@ -3057,14 +3135,14 @@ function $registeredScrapersMessage(availableScrapers) {
         return { ...metadata, isMetadataAviailable, isInstalled, isAvilableInTools };
     });
     if (metadata.length === 0) {
-        return spaceTrim$1(`
+        return spaceTrim(`
             **No scrapers are available**
 
             This is a unexpected behavior, you are probably using some broken version of Promptbook
             At least there should be available the metadata of the scrapers
         `);
     }
-    return spaceTrim$1((block) => `
+    return spaceTrim((block) => `
             Available scrapers are:
             ${block(metadata
         .map(({ packageName, className, isMetadataAviailable, isInstalled, mimeTypes, isAvilableInBrowser, isAvilableInTools, }, i) => {
@@ -3546,17 +3624,22 @@ function titleToName(value) {
 /**
  * The built-in `fetch' function with a lightweight error handling wrapper as default fetch function used in Promptbook scrapers
  *
- * @private as default `fetch` function used in Promptbook scrapers
+ * @public exported from `@promptbook/core`
  */
-const scraperFetch = async (url, init) => {
+const promptbookFetch = async (urlOrRequest, init) => {
     try {
-        return await fetch(url, init);
+        return await fetch(urlOrRequest, init);
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
+        assertsError(error);
+        let url;
+        if (typeof urlOrRequest === 'string') {
+            url = urlOrRequest;
+        }
+        else if (urlOrRequest instanceof Request) {
+            url = urlOrRequest.url;
         }
-        throw new KnowledgeScrapeError(spaceTrim$1((block) => `
+        throw new PromptbookFetchError(spaceTrim((block) => `
                     Can not fetch "${url}"
 
                     Fetch error:
@@ -3577,7 +3660,7 @@ const scraperFetch = async (url, init) => {
 async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
     // console.log('!! makeKnowledgeSourceHandler', knowledgeSource);
     var _a;
-    const { fetch = scraperFetch } = tools;
+    const { fetch = promptbookFetch } = tools;
     const { knowledgeSourceContent } = knowledgeSource;
     let { name } = knowledgeSource;
     const { rootDirname = null, 
@@ -3647,7 +3730,7 @@ async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
         const fileExtension = getFileExtension(filename);
         const mimeType = extensionToMimeType(fileExtension || '');
         if (!(await isFileExisting(filename, tools.fs))) {
-            throw new NotFoundError(spaceTrim$1((block) => `
+            throw new NotFoundError(spaceTrim((block) => `
                           Can not make source handler for file which does not exist:
 
                           File:
@@ -3734,7 +3817,7 @@ async function prepareKnowledgePieces(knowledgeSources, tools, options) {
                     // <- TODO: [🪓] Here should be no need for spreading new array, just `partialPieces = partialPiecesUnchecked`
                     break;
                 }
-                console.warn(spaceTrim$1((block) => `
+                console.warn(spaceTrim((block) => `
                             Cannot scrape knowledge from source despite the scraper \`${scraper.metadata.className}\` supports the mime type "${sourceHandler.mimeType}".
 
                             The source:
@@ -3750,7 +3833,7 @@ async function prepareKnowledgePieces(knowledgeSources, tools, options) {
                 // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
             }
             if (partialPieces === null) {
-                throw new KnowledgeScrapeError(spaceTrim$1((block) => `
+                throw new KnowledgeScrapeError(spaceTrim((block) => `
                             Cannot scrape knowledge
 
                             The source:
@@ -3779,9 +3862,7 @@ async function prepareKnowledgePieces(knowledgeSources, tools, options) {
             knowledgePreparedUnflatten[index] = pieces;
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             console.warn(error);
             // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
         }
@@ -3828,7 +3909,7 @@ async function prepareTasks(pipeline, tools, options) {
         if (task.taskType === 'PROMPT_TASK' &&
             knowledgePiecesCount > 0 &&
             !dependentParameterNames.includes('knowledge')) {
-            preparedContent = spaceTrim(`
+            preparedContent = spaceTrim$1(`
                     {content}
 
                     ## Knowledge
@@ -4073,13 +4154,19 @@ function valueToString(value) {
             return value.toISOString();
         }
         else {
-            return JSON.stringify(value);
+            try {
+                return JSON.stringify(value);
+            }
+            catch (error) {
+                if (error instanceof TypeError && error.message.includes('circular structure')) {
+                    return VALUE_STRINGS.circular;
+                }
+                throw error;
+            }
         }
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         console.error(error);
         return VALUE_STRINGS.unserializable;
     }
@@ -4136,10 +4223,8 @@ function extractVariablesFromJavascript(script) {
             }
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
-        throw new ParseError(spaceTrim((block) => `
+        assertsError(error);
+        throw new ParseError(spaceTrim$1((block) => `
                     Can not extract variables from the script
                     ${block(error.stack || error.message)}
 
@@ -4282,7 +4367,7 @@ const CsvFormatDefinition = {
                 // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
                 const csv = parse(value, { ...settings, ...MANDATORY_CSV_SETTINGS });
                 if (csv.errors.length !== 0) {
-                    throw new CsvFormatError(spaceTrim$1((block) => `
+                    throw new CsvFormatError(spaceTrim((block) => `
                                 CSV parsing error
 
                                 Error(s) from CSV parsing:
@@ -4313,7 +4398,7 @@ const CsvFormatDefinition = {
                 // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
                 const csv = parse(value, { ...settings, ...MANDATORY_CSV_SETTINGS });
                 if (csv.errors.length !== 0) {
-                    throw new CsvFormatError(spaceTrim$1((block) => `
+                    throw new CsvFormatError(spaceTrim((block) => `
                                 CSV parsing error
 
                                 Error(s) from CSV parsing:
@@ -4503,7 +4588,7 @@ function mapAvailableToExpectedParameters(options) {
     }
     // Phase 2️⃣: Non-matching mapping
     if (expectedParameterNames.size !== availableParametersNames.size) {
-        throw new PipelineExecutionError(spaceTrim$1((block) => `
+        throw new PipelineExecutionError(spaceTrim((block) => `
                     Can not map available parameters to expected parameters
 
                     Mapped parameters:
@@ -4905,7 +4990,7 @@ async function executeAttempts(options) {
         const jokerParameterName = jokerParameterNames[jokerParameterNames.length + attempt];
         // TODO: [🧠][🍭] JOKERS, EXPECTATIONS, POSTPROCESSING and FOREACH
         if (isJokerAttempt && !jokerParameterName) {
-            throw new UnexpectedError(spaceTrim((block) => `
+            throw new UnexpectedError(spaceTrim$1((block) => `
                         Joker not found in attempt ${attempt}
 
                         ${block(pipelineIdentification)}
@@ -4916,7 +5001,7 @@ async function executeAttempts(options) {
         $ongoingTaskResult.$expectError = null;
         if (isJokerAttempt) {
             if (parameters[jokerParameterName] === undefined) {
-                throw new PipelineExecutionError(spaceTrim((block) => `
+                throw new PipelineExecutionError(spaceTrim$1((block) => `
                             Joker parameter {${jokerParameterName}} not defined
 
                             ${block(pipelineIdentification)}
@@ -4974,7 +5059,7 @@ async function executeAttempts(options) {
                                     $ongoingTaskResult.$resultString = $ongoingTaskResult.$completionResult.content;
                                     break variant;
                                 case 'EMBEDDING':
-                                    throw new PipelineExecutionError(spaceTrim((block) => `
+                                    throw new PipelineExecutionError(spaceTrim$1((block) => `
                                                 Embedding model can not be used in pipeline
 
                                                 This should be catched during parsing
@@ -4985,7 +5070,7 @@ async function executeAttempts(options) {
                                     break variant;
                                 // <- case [🤖]:
                                 default:
-                                    throw new PipelineExecutionError(spaceTrim((block) => `
+                                    throw new PipelineExecutionError(spaceTrim$1((block) => `
                                                 Unknown model variant "${task.modelRequirements.modelVariant}"
 
                                                 ${block(pipelineIdentification)}
@@ -4996,14 +5081,14 @@ async function executeAttempts(options) {
                         break;
                     case 'SCRIPT_TASK':
                         if (arrayableToArray(tools.script).length === 0) {
-                            throw new PipelineExecutionError(spaceTrim((block) => `
+                            throw new PipelineExecutionError(spaceTrim$1((block) => `
                                         No script execution tools are available
 
                                         ${block(pipelineIdentification)}
                                     `));
                         }
                         if (!task.contentLanguage) {
-                            throw new PipelineExecutionError(spaceTrim((block) => `
+                            throw new PipelineExecutionError(spaceTrim$1((block) => `
                                         Script language is not defined for SCRIPT TASK "${task.name}"
 
                                         ${block(pipelineIdentification)}
@@ -5020,9 +5105,7 @@ async function executeAttempts(options) {
                                 break scripts;
                             }
                             catch (error) {
-                                if (!(error instanceof Error)) {
-                                    throw error;
-                                }
+                                assertsError(error);
                                 if (error instanceof UnexpectedError) {
                                     throw error;
                                 }
@@ -5036,7 +5119,7 @@ async function executeAttempts(options) {
                             throw $ongoingTaskResult.$scriptPipelineExecutionErrors[0];
                         }
                         else {
-                            throw new PipelineExecutionError(spaceTrim((block) => `
+                            throw new PipelineExecutionError(spaceTrim$1((block) => `
                                         Script execution failed ${$ongoingTaskResult.$scriptPipelineExecutionErrors.length}x
 
                                         ${block(pipelineIdentification)}
@@ -5050,7 +5133,7 @@ async function executeAttempts(options) {
                         break taskType;
                     case 'DIALOG_TASK':
                         if (tools.userInterface === undefined) {
-                            throw new PipelineExecutionError(spaceTrim((block) => `
+                            throw new PipelineExecutionError(spaceTrim$1((block) => `
                                         User interface tools are not available
 
                                         ${block(pipelineIdentification)}
@@ -5068,7 +5151,7 @@ async function executeAttempts(options) {
                         break taskType;
                     // <- case: [🅱]
                     default:
-                        throw new PipelineExecutionError(spaceTrim((block) => `
+                        throw new PipelineExecutionError(spaceTrim$1((block) => `
                                     Unknown execution type "${task.taskType}"
 
                                     ${block(pipelineIdentification)}
@@ -5092,9 +5175,7 @@ async function executeAttempts(options) {
                             break scripts;
                         }
                         catch (error) {
-                            if (!(error instanceof Error)) {
-                                throw error;
-                            }
+                            assertsError(error);
                             if (error instanceof UnexpectedError) {
                                 throw error;
                             }
@@ -5117,7 +5198,7 @@ async function executeAttempts(options) {
                         }
                         catch (error) {
                             keepUnused(error);
-                            throw new ExpectError(spaceTrim((block) => `
+                            throw new ExpectError(spaceTrim$1((block) => `
                                         Expected valid JSON string
 
                                         ${block(
@@ -5127,7 +5208,7 @@ async function executeAttempts(options) {
                     }
                 }
                 else {
-                    throw new UnexpectedError(spaceTrim((block) => `
+                    throw new UnexpectedError(spaceTrim$1((block) => `
                                 Unknown format "${task.format}"
 
                                 ${block(pipelineIdentification)}
@@ -5167,7 +5248,7 @@ async function executeAttempts(options) {
             }
         }
         if ($ongoingTaskResult.$expectError !== null && attempt === maxAttempts - 1) {
-            throw new PipelineExecutionError(spaceTrim((block) => {
+            throw new PipelineExecutionError(spaceTrim$1((block) => {
                 var _a, _b, _c;
                 return `
                         LLM execution failed ${maxExecutionAttempts}x
@@ -5190,7 +5271,7 @@ async function executeAttempts(options) {
                         Last result:
                         ${block($ongoingTaskResult.$resultString === null
                     ? 'null'
-                    : spaceTrim($ongoingTaskResult.$resultString)
+                    : spaceTrim$1($ongoingTaskResult.$resultString)
                         .split('\n')
                         .map((line) => `> ${line}`)
                         .join('\n'))}
@@ -5200,7 +5281,7 @@ async function executeAttempts(options) {
         }
     }
     if ($ongoingTaskResult.$resultString === null) {
-        throw new UnexpectedError(spaceTrim((block) => `
+        throw new UnexpectedError(spaceTrim$1((block) => `
                     Something went wrong and prompt result is null
 
                     ${block(pipelineIdentification)}
@@ -5223,7 +5304,7 @@ async function executeFormatSubvalues(options) {
         return /* not await */ executeAttempts(options);
     }
     if (jokerParameterNames.length !== 0) {
-        throw new UnexpectedError(spaceTrim$1((block) => `
+        throw new UnexpectedError(spaceTrim((block) => `
                     JOKER parameters are not supported together with FOREACH command
 
                     [🧞‍♀️] This should be prevented in \`validatePipeline\`
@@ -5236,7 +5317,7 @@ async function executeFormatSubvalues(options) {
     if (formatDefinition === undefined) {
         throw new UnexpectedError(
         // <- TODO: [🧠][🧐] Should be formats fixed per promptbook version or behave as plugins (=> change UnexpectedError)
-        spaceTrim$1((block) => `
+        spaceTrim((block) => `
                     Unsupported format "${task.foreach.formatName}"
 
                     Available formats:
@@ -5253,7 +5334,7 @@ async function executeFormatSubvalues(options) {
     if (subvalueDefinition === undefined) {
         throw new UnexpectedError(
         // <- TODO: [🧠][🧐] Should be formats fixed per promptbook version or behave as plugins (=> change UnexpectedError)
-        spaceTrim$1((block) => `
+        spaceTrim((block) => `
                     Unsupported subformat name "${task.foreach.subformatName}" for format "${task.foreach.formatName}"
 
                     Available subformat names for format "${formatDefinition.formatName}":
@@ -5286,7 +5367,7 @@ async function executeFormatSubvalues(options) {
             if (!(error instanceof PipelineExecutionError)) {
                 throw error;
             }
-            throw new PipelineExecutionError(spaceTrim$1((block) => `
+            throw new PipelineExecutionError(spaceTrim((block) => `
                         ${error.message}
 
                         This is error in FOREACH command
@@ -5306,7 +5387,7 @@ async function executeFormatSubvalues(options) {
             ...options,
             priority: priority + index,
             parameters: allSubparameters,
-            pipelineIdentification: spaceTrim$1((block) => `
+            pipelineIdentification: spaceTrim((block) => `
                         ${block(pipelineIdentification)}
                         Subparameter index: ${index}
                     `),
@@ -5368,7 +5449,7 @@ async function getReservedParametersForTask(options) {
     // Note: Doublecheck that ALL reserved parameters are defined:
     for (const parameterName of RESERVED_PARAMETER_NAMES) {
         if (reservedParameters[parameterName] === undefined) {
-            throw new UnexpectedError(spaceTrim((block) => `
+            throw new UnexpectedError(spaceTrim$1((block) => `
                         Reserved parameter {${parameterName}} is not defined
 
                         ${block(pipelineIdentification)}
@@ -5396,7 +5477,7 @@ async function executeTask(options) {
     const dependentParameterNames = new Set(currentTask.dependentParameterNames);
     // TODO: [👩🏾‍🤝‍👩🏻] Use here `mapAvailableToExpectedParameters`
     if (union(difference(usedParameterNames, dependentParameterNames), difference(dependentParameterNames, usedParameterNames)).size !== 0) {
-        throw new UnexpectedError(spaceTrim((block) => `
+        throw new UnexpectedError(spaceTrim$1((block) => `
                     Dependent parameters are not consistent with used parameters:
 
                     Dependent parameters:
@@ -5436,7 +5517,7 @@ async function executeTask(options) {
         else if (!definedParameterNames.has(parameterName) && usedParameterNames.has(parameterName)) {
             // Houston, we have a problem
             // Note: Checking part is also done in `validatePipeline`, but it’s good to doublecheck
-            throw new UnexpectedError(spaceTrim((block) => `
+            throw new UnexpectedError(spaceTrim$1((block) => `
                         Parameter \`{${parameterName}}\` is NOT defined
                         BUT used in task "${currentTask.title || currentTask.name}"
 
@@ -5502,7 +5583,7 @@ function filterJustOutputParameters(options) {
     for (const parameter of preparedPipeline.parameters.filter(({ isOutput }) => isOutput)) {
         if (parametersToPass[parameter.name] === undefined) {
             // [4]
-            $warnings.push(new PipelineExecutionError(spaceTrim((block) => `
+            $warnings.push(new PipelineExecutionError(spaceTrim$1((block) => `
                             Parameter \`{${parameter.name}}\` should be an output parameter, but it was not generated during pipeline execution
 
                             ${block(pipelineIdentification)}
@@ -5577,7 +5658,7 @@ async function executePipeline(options) {
     for (const parameterName of Object.keys(inputParameters)) {
         const parameter = preparedPipeline.parameters.find(({ name }) => name === parameterName);
         if (parameter === undefined) {
-            warnings.push(new PipelineExecutionError(spaceTrim((block) => `
+            warnings.push(new PipelineExecutionError(spaceTrim$1((block) => `
                             Extra parameter {${parameterName}} is being passed which is not part of the pipeline.
 
                             ${block(pipelineIdentification)}
@@ -5592,7 +5673,7 @@ async function executePipeline(options) {
             // TODO: [🧠] This should be also non-critical error
             return exportJson({
                 name: 'pipelineExecutorResult',
-                message: spaceTrim((block) => `
+                message: spaceTrim$1((block) => `
                         Unuccessful PipelineExecutorResult (with extra parameter {${parameter.name}}) PipelineExecutorResult
 
                         ${block(pipelineIdentification)}
@@ -5601,7 +5682,7 @@ async function executePipeline(options) {
                 value: {
                     isSuccessful: false,
                     errors: [
-                        new PipelineExecutionError(spaceTrim((block) => `
+                        new PipelineExecutionError(spaceTrim$1((block) => `
                                     Parameter \`{${parameter.name}}\` is passed as input parameter but it is not input
 
                                     ${block(pipelineIdentification)}
@@ -5628,7 +5709,7 @@ async function executePipeline(options) {
         while (unresovedTasks.length > 0) {
             if (loopLimit-- < 0) {
                 // Note: Really UnexpectedError not LimitReachedError - this should be catched during validatePipeline
-                throw new UnexpectedError(spaceTrim((block) => `
+                throw new UnexpectedError(spaceTrim$1((block) => `
                             Loop limit reached during resolving parameters pipeline execution
 
                             ${block(pipelineIdentification)}
@@ -5638,7 +5719,7 @@ async function executePipeline(options) {
             if (!currentTask && resolving.length === 0) {
                 throw new UnexpectedError(
                 // TODO: [🐎] DRY
-                spaceTrim((block) => `
+                spaceTrim$1((block) => `
                             Can not resolve some parameters:
 
                             ${block(pipelineIdentification)}
@@ -5678,7 +5759,7 @@ async function executePipeline(options) {
                     tools,
                     onProgress(newOngoingResult) {
                         if (isReturned) {
-                            throw new UnexpectedError(spaceTrim((block) => `
+                            throw new UnexpectedError(spaceTrim$1((block) => `
                                         Can not call \`onProgress\` after pipeline execution is finished
 
                                         ${block(pipelineIdentification)}
@@ -5694,7 +5775,7 @@ async function executePipeline(options) {
                         }
                     },
                     $executionReport: executionReport,
-                    pipelineIdentification: spaceTrim((block) => `
+                    pipelineIdentification: spaceTrim$1((block) => `
                             ${block(pipelineIdentification)}
                             Task name: ${currentTask.name}
                             Task title: ${currentTask.title}
@@ -5715,9 +5796,7 @@ async function executePipeline(options) {
         await Promise.all(resolving);
     }
     catch (error /* <- Note: [3] */) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         // Note: No need to rethrow UnexpectedError
         // if (error instanceof UnexpectedError) {
         // Note: Count usage, [🧠] Maybe put to separate function executionReportJsonToUsage + DRY [🤹‍♂️]
@@ -5805,7 +5884,7 @@ function createPipelineExecutor(options) {
         preparedPipeline = pipeline;
     }
     else if (isNotPreparedWarningSupressed !== true) {
-        console.warn(spaceTrim((block) => `
+        console.warn(spaceTrim$1((block) => `
                     Pipeline is not prepared
 
                     ${block(pipelineIdentification)}
@@ -5829,7 +5908,7 @@ function createPipelineExecutor(options) {
             inputParameters,
             tools,
             onProgress,
-            pipelineIdentification: spaceTrim((block) => `
+            pipelineIdentification: spaceTrim$1((block) => `
                     ${block(pipelineIdentification)}
                     ${runCount === 1 ? '' : `Run #${runCount}`}
                 `),
@@ -5927,13 +6006,13 @@ function $registeredLlmToolsMessage() {
     });
     const usedEnvMessage = `Unknown \`.env\` file` ;
     if (metadata.length === 0) {
-        return spaceTrim$1((block) => `
+        return spaceTrim((block) => `
                 No LLM providers are available.
 
                 ${block(usedEnvMessage)}
           `);
     }
-    return spaceTrim$1((block) => `
+    return spaceTrim((block) => `
 
             ${block(usedEnvMessage)}
 
@@ -5979,7 +6058,7 @@ function $registeredLlmToolsMessage() {
                 morePieces.push(`Not configured`); // <- Note: Can not be configured via environment variables
             }
         }
-        let providerMessage = spaceTrim$1(`
+        let providerMessage = spaceTrim(`
                                 ${i + 1}) **${title}** \`${className}\` from \`${packageName}\`
                                     ${morePieces.join('; ')}
                             `);
@@ -6019,7 +6098,7 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
             .list()
             .find(({ packageName, className }) => llmConfiguration.packageName === packageName && llmConfiguration.className === className);
         if (registeredItem === undefined) {
-            throw new Error(spaceTrim$1((block) => `
+            throw new Error(spaceTrim((block) => `
                         There is no constructor for LLM provider \`${llmConfiguration.className}\` from \`${llmConfiguration.packageName}\`
 
                         You have probably forgotten install and import the provider package.
@@ -6303,13 +6382,13 @@ function removeQuotes(text) {
  * @public exported from `@promptbook/utils`
  */
 function trimCodeBlock(value) {
-    value = spaceTrim(value);
+    value = spaceTrim$1(value);
     if (!/^```[a-z]*(.*)```$/is.test(value)) {
         return value;
     }
     value = value.replace(/^```[a-z]*/i, '');
     value = value.replace(/```$/i, '');
-    value = spaceTrim(value);
+    value = spaceTrim$1(value);
     return value;
 }
 
@@ -6322,9 +6401,9 @@ function trimCodeBlock(value) {
  * @public exported from `@promptbook/utils`
  */
 function trimEndOfCodeBlock(value) {
-    value = spaceTrim(value);
+    value = spaceTrim$1(value);
     value = value.replace(/```$/g, '');
-    value = spaceTrim(value);
+    value = spaceTrim$1(value);
     return value;
 }
 
@@ -6346,7 +6425,7 @@ function unwrapResult(text, options) {
     let trimmedText = text;
     // Remove leading and trailing spaces and newlines
     if (isTrimmed) {
-        trimmedText = spaceTrim(trimmedText);
+        trimmedText = spaceTrim$1(trimmedText);
     }
     let processedText = trimmedText;
     if (isIntroduceSentenceRemoved) {
@@ -6355,7 +6434,7 @@ function unwrapResult(text, options) {
             // Remove the introduce sentence and quotes by replacing it with an empty string
             processedText = processedText.replace(introduceSentenceRegex, '');
         }
-        processedText = spaceTrim(processedText);
+        processedText = spaceTrim$1(processedText);
     }
     if (processedText.length < 3) {
         return trimmedText;
@@ -6418,7 +6497,7 @@ function unwrapResult(text, options) {
 function extractOneBlockFromMarkdown(markdown) {
     const codeBlocks = extractAllBlocksFromMarkdown(markdown);
     if (codeBlocks.length !== 1) {
-        throw new ParseError(spaceTrim$1((block) => `
+        throw new ParseError(spaceTrim((block) => `
                     There should be exactly 1 code block in task section, found ${codeBlocks.length} code blocks
 
                     ${block(codeBlocks.map((block, i) => `Block ${i + 1}:\n${block.content}`).join('\n\n\n'))}
@@ -6500,8 +6579,8 @@ class JavascriptEvalExecutionTools {
         }
         // Note: [💎]
         // Note: Using direct eval, following variables are in same scope as eval call so they are accessible from inside the evaluated script:
-        const spaceTrim = (_) => spaceTrim$1(_);
-        preserve(spaceTrim);
+        const spaceTrim$1 = (_) => spaceTrim(_);
+        preserve(spaceTrim$1);
         const removeQuotes$1 = removeQuotes;
         preserve(removeQuotes$1);
         const unwrapResult$1 = unwrapResult;
@@ -6554,7 +6633,7 @@ class JavascriptEvalExecutionTools {
         // TODO: DRY [🍯]
         const buildinFunctions = {
             // TODO: [🍯] DRY all these functions across the file
-            spaceTrim,
+            spaceTrim: spaceTrim$1,
             removeQuotes: removeQuotes$1,
             unwrapResult: unwrapResult$1,
             trimEndOfCodeBlock: trimEndOfCodeBlock$1,
@@ -6591,7 +6670,7 @@ class JavascriptEvalExecutionTools {
             .join('\n');
         // script = templateParameters(script, parameters);
         // <- TODO: [🧠][🥳] Should be this is one of two variants how to use parameters in script
-        const statementToEvaluate = spaceTrim$1((block) => `
+        const statementToEvaluate = spaceTrim((block) => `
 
                 // Build-in functions:
                 ${block(buildinFunctionsStatement)}
@@ -6606,7 +6685,7 @@ class JavascriptEvalExecutionTools {
                 (()=>{ ${script} })()
             `);
         if (this.options.isVerbose) {
-            console.info(spaceTrim$1((block) => `
+            console.info(spaceTrim((block) => `
                         🚀 Evaluating ${scriptLanguage} script:
 
                         ${block(statementToEvaluate)}`));
@@ -6619,9 +6698,7 @@ class JavascriptEvalExecutionTools {
             }
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             if (error instanceof ReferenceError) {
                 const undefinedName = error.message.split(' ')[0];
                 /*
@@ -6630,7 +6707,7 @@ class JavascriptEvalExecutionTools {
                       To:   [PipelineExecutionError: Parameter `{thing}` is not defined],
                 */
                 if (!statementToEvaluate.includes(undefinedName + '(')) {
-                    throw new PipelineExecutionError(spaceTrim$1((block) => `
+                    throw new PipelineExecutionError(spaceTrim((block) => `
 
                                 Parameter \`{${undefinedName}}\` is not defined
 
@@ -6652,7 +6729,7 @@ class JavascriptEvalExecutionTools {
                             `));
                 }
                 else {
-                    throw new PipelineExecutionError(spaceTrim$1((block) => `
+                    throw new PipelineExecutionError(spaceTrim((block) => `
                                   Function ${undefinedName}() is not defined
 
                                   -  Make sure that the function is one of built-in functions
@@ -6711,11 +6788,12 @@ async function $provideScriptingForNode(options) {
  * @public exported from `@promptbook/remote-server`
  */
 function startRemoteServer(options) {
-    const { port, collection, createLlmExecutionTools, isAnonymousModeAllowed, isApplicationModeAllowed, isVerbose = DEFAULT_IS_VERBOSE, } = {
+    const { port, collection, createLlmExecutionTools, createExecutionTools, isAnonymousModeAllowed, isApplicationModeAllowed, isVerbose = DEFAULT_IS_VERBOSE, login, } = {
         isAnonymousModeAllowed: false,
         isApplicationModeAllowed: false,
         collection: null,
         createLlmExecutionTools: null,
+        login: null,
         ...options,
     };
     // <- TODO: [🦪] Some helper type to be able to use discriminant union types with destructuring
@@ -6758,6 +6836,7 @@ function startRemoteServer(options) {
             // Note: Application mode
             const { appId, userId, customOptions } = identification;
             llm = await createLlmExecutionTools({
+                isAnonymous: false,
                 appId,
                 userId,
                 customOptions,
@@ -6766,13 +6845,20 @@ function startRemoteServer(options) {
         else {
             throw new PipelineExecutionError(`You must provide either llmToolsConfiguration or non-anonymous mode must be propperly configured`);
         }
-        const fs = $provideFilesystemForNode();
-        const executables = await $provideExecutablesForNode();
+        const customExecutionTools = createExecutionTools ? await createExecutionTools(identification) : {};
+        const fs = customExecutionTools.fs || $provideFilesystemForNode();
+        const executables = customExecutionTools.executables || (await $provideExecutablesForNode());
+        const scrapers = customExecutionTools.scrapers || (await $provideScrapersForNode({ fs, llm, executables }));
+        const script = customExecutionTools.script || (await $provideScriptingForNode({}));
+        const fetch = customExecutionTools.fetch || promptbookFetch;
+        const userInterface = customExecutionTools.userInterface || undefined;
         const tools = {
             llm,
             fs,
-            scrapers: await $provideScrapersForNode({ fs, llm, executables }),
-            script: await $provideScriptingForNode({}),
+            scrapers,
+            script,
+            fetch,
+            userInterface,
         };
         return tools;
     }
@@ -6782,15 +6868,44 @@ function startRemoteServer(options) {
         response.setHeader('X-Powered-By', 'Promptbook engine');
         next();
     });
+    const swaggerOptions = {
+        definition: {
+            openapi: '3.0.0',
+            info: {
+                title: 'Promptbook Remote Server API',
+                version: '1.0.0',
+                description: 'API documentation for the Promptbook Remote Server',
+            },
+            servers: [
+                {
+                    url: `http://localhost:${port}${rootPath}`,
+                    // <- TODO: !!!!! Probbably: Pass `remoteServerUrl` instead of `port` and `rootPath`
+                },
+            ],
+        },
+        apis: ['./src/remote-server/**/*.ts'], // Adjust path as needed
+    };
+    const swaggerSpec = swaggerJsdoc(swaggerOptions);
+    app.use([`/api-docs`, `${rootPath}/api-docs`], swaggerUi.serve, swaggerUi.setup(swaggerSpec));
     const runningExecutionTasks = [];
     // <- TODO: [🤬] Identify the users
     // TODO: [🧠] Do here some garbage collection of finished tasks
+    /**
+     * @swagger
+     * /:
+     *   get:
+     *     summary: Get server details
+     *     description: Returns details about the Promptbook server.
+     *     responses:
+     *       200:
+     *         description: Server details in markdown format.
+     */
     app.get(['/', rootPath], async (request, response) => {
         var _a;
         if ((_a = request.url) === null || _a === void 0 ? void 0 : _a.includes('socket.io')) {
             return;
         }
-        response.type('text/markdown').send(await spaceTrim(async (block) => `
+        response.type('text/markdown').send(await spaceTrim$1(async (block) => `
                     # Promptbook
 
                     > ${block(CLAIM)}
@@ -6821,9 +6936,12 @@ function startRemoteServer(options) {
 
                     ## Paths
 
-                    ${block(app._router.stack
-            .map(({ route }) => (route === null || route === void 0 ? void 0 : route.path) || null)
-            .filter((path) => path !== null)
+                    ${block([
+            ...app._router.stack
+                .map(({ route }) => (route === null || route === void 0 ? void 0 : route.path) || null)
+                .filter((path) => path !== null),
+            '/api-docs',
+        ]
             .map((path) => `- ${path}`)
             .join('\n'))}
 
@@ -6841,8 +6959,94 @@ function startRemoteServer(options) {
                     https://github.com/webgptorg/promptbook
                 `));
     });
-    // TODO: !!!!!! Add login route
-    app.get(`${rootPath}/books`, async (request, response) => {
+    /**
+     * @swagger
+     *
+     * /login:
+     *  post:
+     *   summary: Login to the server
+     *   description: Login to the server and get identification.
+     *   requestBody:
+     *    required: true
+     *    content:
+     *     application/json:
+     *      schema:
+     *       type: object
+     *       properties:
+     *        username:
+     *         type: string
+     *        password:
+     *         type: string
+     *        appId:
+     *         type: string
+     *   responses:
+     *    200:
+     *     description: Successful login
+     *     content:
+     *      application/json:
+     *       schema:
+     *        type: object
+     *        properties:
+     *         identification:
+     *          type: object
+     */
+    app.post([`/login`, `${rootPath}/login`], async (request, response) => {
+        if (!isApplicationModeAllowed || login === null) {
+            response.status(400).send('Application mode is not allowed');
+            return;
+        }
+        try {
+            const username = request.body.username;
+            const password = request.body.password;
+            const appId = request.body.appId;
+            const { isSuccess, error, message, identification } = await login({
+                username,
+                password,
+                appId,
+                rawRequest: request,
+                rawResponse: response,
+            });
+            response.status(201).send({
+                isSuccess,
+                message,
+                error: error ? serializeError(error) : undefined,
+                identification,
+            });
+            return;
+        }
+        catch (error) {
+            assertsError(error);
+            if (error instanceof AuthenticationError) {
+                response.status(401).send({
+                    isSuccess: false,
+                    message: error.message,
+                    error: serializeError(error),
+                });
+            }
+            console.warn(`Login function thrown different error than AuthenticationError`, {
+                error,
+                serializedError: serializeError(error),
+            });
+            response.status(400).send({ error: serializeError(error) });
+        }
+    });
+    /**
+     * @swagger
+     * /books:
+     *   get:
+     *     summary: List all books
+     *     description: Returns a list of all available books in the collection.
+     *     responses:
+     *       200:
+     *         description: A list of books.
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: array
+     *               items:
+     *                 type: string
+     */
+    app.get([`/books`, `${rootPath}/books`], async (request, response) => {
         if (collection === null) {
             response.status(500).send('No collection available');
             return;
@@ -6852,7 +7056,30 @@ function startRemoteServer(options) {
         response.send(pipelines);
     });
     // TODO: [🧠] Is it secure / good idea to expose source codes of hosted books
-    app.get(`${rootPath}/books/*`, async (request, response) => {
+    /**
+     * @swagger
+     * /books/{bookId}:
+     *   get:
+     *     summary: Get book content
+     *     description: Returns the content of a specific book.
+     *     parameters:
+     *       - in: path
+     *         name: bookId
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The ID of the book to retrieve.
+     *     responses:
+     *       200:
+     *         description: The content of the book.
+     *         content:
+     *           text/markdown:
+     *             schema:
+     *               type: string
+     *       404:
+     *         description: Book not found.
+     */
+    app.get([`/books/*`, `${rootPath}/books/*`], async (request, response) => {
         try {
             if (collection === null) {
                 response.status(500).send('No collection nor books available');
@@ -6871,9 +7098,7 @@ function startRemoteServer(options) {
                 .send(source.content);
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             response
                 .status(404)
                 .send({ error: serializeError(error) });
@@ -6906,10 +7131,26 @@ function startRemoteServer(options) {
             };
         }
     }
-    app.get(`${rootPath}/executions`, async (request, response) => {
+    /**
+     * @swagger
+     * /executions:
+     *   get:
+     *     summary: List all executions
+     *     description: Returns a list of all running execution tasks.
+     *     responses:
+     *       200:
+     *         description: A list of execution tasks.
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: array
+     *               items:
+     *                 type: object
+     */
+    app.get([`/executions`, `${rootPath}/executions`], async (request, response) => {
         response.send(runningExecutionTasks.map((runningExecutionTask) => exportExecutionTask(runningExecutionTask, false)));
     });
-    app.get(`${rootPath}/executions/last`, async (request, response) => {
+    app.get([`/executions/last`, `${rootPath}/executions/last`], async (request, response) => {
         // TODO: [🤬] Filter only for user
         if (runningExecutionTasks.length === 0) {
             response.status(404).send('No execution tasks found');
@@ -6918,7 +7159,7 @@ function startRemoteServer(options) {
         const lastExecutionTask = runningExecutionTasks[runningExecutionTasks.length - 1];
         response.send(exportExecutionTask(lastExecutionTask, true));
     });
-    app.get(`${rootPath}/executions/:taskId`, async (request, response) => {
+    app.get([`/executions/:taskId`, `${rootPath}/executions/:taskId`], async (request, response) => {
         const { taskId } = request.params;
         // TODO: [🤬] Filter only for user
         const executionTask = runningExecutionTasks.find((executionTask) => executionTask.taskId === taskId);
@@ -6930,7 +7171,36 @@ function startRemoteServer(options) {
         }
         response.send(exportExecutionTask(executionTask, true));
     });
-    app.post(`${rootPath}/executions/new`, async (request, response) => {
+    /**
+     * @swagger
+     * /executions/new:
+     *   post:
+     *     summary: Start a new execution
+     *     description: Starts a new execution task for a given pipeline.
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             properties:
+     *               pipelineUrl:
+     *                 type: string
+     *               inputParameters:
+     *                 type: object
+     *               identification:
+     *                 type: object
+     *     responses:
+     *       200:
+     *         description: The newly created execution task.
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *       400:
+     *         description: Invalid input.
+     */
+    app.post([`/executions/new`, `${rootPath}/executions/new`], async (request, response) => {
         try {
             const { inputParameters, identification /* <- [🤬] */ } = request.body;
             const pipelineUrl = request.body.pipelineUrl || request.body.book;
@@ -6967,12 +7237,16 @@ function startRemoteServer(options) {
             */
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             response.status(400).send({ error: serializeError(error) });
         }
     });
+    /**
+     * Catch-all handler for unmatched routes
+     */
+    app.use((request, response) => {
+        response.status(404).send(`URL "${request.originalUrl}" was not found on Promptbook server.`);
+    });
     const httpServer = http.createServer(app);
     const server = new Server(httpServer, {
         path: socketioPath,
@@ -7033,9 +7307,7 @@ function startRemoteServer(options) {
                 socket.emit('prompt-response', { promptResult } /* <- Note: [🤛] */);
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 socket.emit('error', serializeError(error) /* <- Note: [🤛] */);
             }
             finally {
@@ -7057,9 +7329,7 @@ function startRemoteServer(options) {
                 socket.emit('listModels-response', { models } /* <- Note: [🤛] */);
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 socket.emit('error', serializeError(error));
             }
             finally {
@@ -7080,9 +7350,7 @@ function startRemoteServer(options) {
                 socket.emit('preparePipeline-response', { preparedPipeline } /* <- Note: [🤛] */);
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 socket.emit('error', serializeError(error));
                 // <- TODO: [🚋] There is a problem with the remote server handling errors and sending them back to the client
             }
@@ -7107,6 +7375,15 @@ function startRemoteServer(options) {
     }
     let isDestroyed = false;
     return {
+        get httpServer() {
+            return httpServer;
+        },
+        get expressApp() {
+            return app;
+        },
+        get socketIoServer() {
+            return server;
+        },
         get isDestroyed() {
             return isDestroyed;
         },
@@ -7122,7 +7399,6 @@ function startRemoteServer(options) {
 }
 /**
  * TODO: !! Add CORS and security - probbably via `helmet`
- * TODO: [👩🏾‍🤝‍🧑🏾] Allow to pass custom fetch function here - PromptbookFetch
  * TODO: Split this file into multiple functions - handler for each request
  * TODO: Maybe use `$exportJson`
  * TODO: [🧠][🛍] Maybe not `isAnonymous: boolean` BUT `mode: 'ANONYMOUS'|'COLLECTION'`