@promptbook/remote-server 0.89.0-1 → 0.89.0-11

package/esm/index.es.js

@@ -3,6 +3,8 @@ import express from 'express';
 import http from 'http';
 import { Server } from 'socket.io';
 import spaceTrim$1, { spaceTrim } 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-1';
+const PROMPTBOOK_ENGINE_VERSION = '0.89.0-11';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -156,6 +158,7 @@ const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
  */
 const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
 // <- TODO: [🕝] Make also `BOOKS_DIRNAME_ALTERNATIVES`
+// TODO: !!!!!! Just .promptbook dir, hardocode others
 /**
  * Where to store the temporary downloads
  *
@@ -207,9 +210,22 @@ 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
  */
 
+/**
+ * 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
  *
@@ -438,6 +454,19 @@ class PipelineUrlError extends Error {
     }
 }
 
+/**
+ * Error thrown when a fetch request fails
+ *
+ * @public exported from `@promptbook/core`
+ */
+class PromptbookFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptbookFetchError';
+        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+    }
+}
+
 /**
  * Make error report URL for the given error
  *
@@ -543,6 +572,8 @@ const COMMON_JAVASCRIPT_ERRORS = {
     TypeError,
     URIError,
     AggregateError,
+    AuthenticationError,
+    PromptbookFetchError,
     /*
   Note: Not widely supported
   > InternalError,
@@ -578,6 +609,10 @@ function serializeError(error) {
 
                     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)}
 
                 `));
@@ -694,6 +729,7 @@ function $execCommand(options) {
                 }
                 else {
                     console.warn(`Command "${humanReadableCommand}" exceeded time limit of ${timeout}ms but continues running`);
+                    // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
                     resolve('Command exceeded time limit');
                 }
             });
@@ -719,6 +755,7 @@ function $execCommand(options) {
                 output.push(stderr.toString());
                 if (isVerbose && stderr.toString().trim()) {
                     console.warn(stderr.toString());
+                    // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
                 }
             });
             const finishWithCode = (code) => {
@@ -730,6 +767,7 @@ function $execCommand(options) {
                     else {
                         if (isVerbose) {
                             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')));
                     }
@@ -751,6 +789,7 @@ function $execCommand(options) {
                 else {
                     if (isVerbose) {
                         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')));
                 }
@@ -1819,6 +1858,7 @@ function assertsTaskSuccessful(executionResult) {
     const { isSuccessful, errors, warnings } = executionResult;
     for (const warning of warnings) {
         console.warn(warning.message);
+        // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
     }
     if (isSuccessful === true) {
         return;
@@ -2420,30 +2460,42 @@ async function forEachAsync(array, options, callbackfunction) {
     await Promise.all(tasks);
 }
 
+/**
+ * Represents the uncertain value
+ *
+ * @public exported from `@promptbook/core`
+ */
+const ZERO_VALUE = $deepFreeze({ value: 0 });
+/**
+ * Represents the uncertain value
+ *
+ * @public exported from `@promptbook/core`
+ */
+const UNCERTAIN_ZERO_VALUE = $deepFreeze({ value: 0, isUncertain: true });
 /**
  * Represents the usage with no resources consumed
  *
  * @public exported from `@promptbook/core`
  */
 const ZERO_USAGE = $deepFreeze({
-    price: { value: 0 },
+    price: ZERO_VALUE,
     input: {
-        tokensCount: { value: 0 },
-        charactersCount: { value: 0 },
-        wordsCount: { value: 0 },
-        sentencesCount: { value: 0 },
-        linesCount: { value: 0 },
-        paragraphsCount: { value: 0 },
-        pagesCount: { value: 0 },
+        tokensCount: ZERO_VALUE,
+        charactersCount: ZERO_VALUE,
+        wordsCount: ZERO_VALUE,
+        sentencesCount: ZERO_VALUE,
+        linesCount: ZERO_VALUE,
+        paragraphsCount: ZERO_VALUE,
+        pagesCount: ZERO_VALUE,
     },
     output: {
-        tokensCount: { value: 0 },
-        charactersCount: { value: 0 },
-        wordsCount: { value: 0 },
-        sentencesCount: { value: 0 },
-        linesCount: { value: 0 },
-        paragraphsCount: { value: 0 },
-        pagesCount: { value: 0 },
+        tokensCount: ZERO_VALUE,
+        charactersCount: ZERO_VALUE,
+        wordsCount: ZERO_VALUE,
+        sentencesCount: ZERO_VALUE,
+        linesCount: ZERO_VALUE,
+        paragraphsCount: ZERO_VALUE,
+        pagesCount: ZERO_VALUE,
     },
 });
 /**
@@ -2452,24 +2504,24 @@ const ZERO_USAGE = $deepFreeze({
  * @public exported from `@promptbook/core`
  */
 $deepFreeze({
-    price: { value: 0, isUncertain: true },
+    price: UNCERTAIN_ZERO_VALUE,
     input: {
-        tokensCount: { value: 0, isUncertain: true },
-        charactersCount: { value: 0, isUncertain: true },
-        wordsCount: { value: 0, isUncertain: true },
-        sentencesCount: { value: 0, isUncertain: true },
-        linesCount: { value: 0, isUncertain: true },
-        paragraphsCount: { value: 0, isUncertain: true },
-        pagesCount: { value: 0, isUncertain: true },
+        tokensCount: UNCERTAIN_ZERO_VALUE,
+        charactersCount: UNCERTAIN_ZERO_VALUE,
+        wordsCount: UNCERTAIN_ZERO_VALUE,
+        sentencesCount: UNCERTAIN_ZERO_VALUE,
+        linesCount: UNCERTAIN_ZERO_VALUE,
+        paragraphsCount: UNCERTAIN_ZERO_VALUE,
+        pagesCount: UNCERTAIN_ZERO_VALUE,
     },
     output: {
-        tokensCount: { value: 0, isUncertain: true },
-        charactersCount: { value: 0, isUncertain: true },
-        wordsCount: { value: 0, isUncertain: true },
-        sentencesCount: { value: 0, isUncertain: true },
-        linesCount: { value: 0, isUncertain: true },
-        paragraphsCount: { value: 0, isUncertain: true },
-        pagesCount: { value: 0, isUncertain: true },
+        tokensCount: UNCERTAIN_ZERO_VALUE,
+        charactersCount: UNCERTAIN_ZERO_VALUE,
+        wordsCount: UNCERTAIN_ZERO_VALUE,
+        sentencesCount: UNCERTAIN_ZERO_VALUE,
+        linesCount: UNCERTAIN_ZERO_VALUE,
+        paragraphsCount: UNCERTAIN_ZERO_VALUE,
+        pagesCount: UNCERTAIN_ZERO_VALUE,
     },
 });
 /**
@@ -2757,6 +2809,7 @@ function joinLlmExecutionTools(...llmExecutionTools) {
         `);
         // TODO: [🟥] Detect browser / node and make it colorfull
         console.warn(warningMessage);
+        // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
         /*
         return {
             async listModels() {
@@ -3528,17 +3581,24 @@ 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;
         }
-        throw new KnowledgeScrapeError(spaceTrim$1((block) => `
+        let url;
+        if (typeof urlOrRequest === 'string') {
+            url = urlOrRequest;
+        }
+        else if (urlOrRequest instanceof Request) {
+            url = urlOrRequest.url;
+        }
+        throw new PromptbookFetchError(spaceTrim$1((block) => `
                     Can not fetch "${url}"
 
                     Fetch error:
@@ -3559,7 +3619,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, 
@@ -3700,63 +3760,73 @@ 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) => {
-        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);
-            if (partialPiecesUnchecked !== null) {
-                partialPieces = [...partialPiecesUnchecked];
-                // <- TODO: [🪓] Here should be no need for spreading new array, just `partialPieces = partialPiecesUnchecked`
-                break;
-            }
-            console.warn(spaceTrim$1((block) => `
-                        Cannot scrape knowledge from source despite the scraper \`${scraper.metadata.className}\` supports the mime type "${sourceHandler.mimeType}".
+        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);
+                if (partialPiecesUnchecked !== null) {
+                    partialPieces = [...partialPiecesUnchecked];
+                    // <- TODO: [🪓] Here should be no need for spreading new array, just `partialPieces = partialPiecesUnchecked`
+                    break;
+                }
+                console.warn(spaceTrim$1((block) => `
+                            Cannot scrape knowledge from source despite the scraper \`${scraper.metadata.className}\` supports the mime type "${sourceHandler.mimeType}".
 
-                        The source:
-                        ${block(knowledgeSource.knowledgeSourceContent
-                .split('\n')
-                .map((line) => `> ${line}`)
-                .join('\n'))}
+                            The source:
+                            ${block(knowledgeSource.knowledgeSourceContent
+                    .split('\n')
+                    .map((line) => `> ${line}`)
+                    .join('\n'))}
 
-                        ${block($registeredScrapersMessage(scrapers))}
+                            ${block($registeredScrapersMessage(scrapers))}
 
 
-                    `));
-        }
-        if (partialPieces === null) {
-            throw new KnowledgeScrapeError(spaceTrim$1((block) => `
-                        Cannot scrape knowledge
+                        `));
+                // <- 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) => `
+                            Cannot scrape knowledge
 
-                        The source:
-                        > ${block(knowledgeSource.knowledgeSourceContent
-                .split('\n')
-                .map((line) => `> ${line}`)
-                .join('\n'))}
+                            The source:
+                            > ${block(knowledgeSource.knowledgeSourceContent
+                    .split('\n')
+                    .map((line) => `> ${line}`)
+                    .join('\n'))}
 
-                        No scraper found for the mime type "${sourceHandler.mimeType}"
+                            No scraper found for the mime type "${sourceHandler.mimeType}"
 
-                        ${block($registeredScrapersMessage(scrapers))}
+                            ${block($registeredScrapersMessage(scrapers))}
 
 
-                    `));
+                        `));
+            }
+            const pieces = partialPieces.map((partialPiece) => ({
+                ...partialPiece,
+                sources: [
+                    {
+                        name: knowledgeSource.name,
+                        // line, column <- TODO: [☀]
+                        // <- TODO: [❎]
+                    },
+                ],
+            }));
+            knowledgePreparedUnflatten[index] = pieces;
+        }
+        catch (error) {
+            if (!(error instanceof Error)) {
+                throw error;
+            }
+            console.warn(error);
+            // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
         }
-        const pieces = partialPieces.map((partialPiece) => ({
-            ...partialPiece,
-            sources: [
-                {
-                    name: knowledgeSource.name,
-                    // line, column <- TODO: [☀]
-                    // <- TODO: [❎]
-                },
-            ],
-        }));
-        knowledgePreparedUnflatten[index] = pieces;
     });
     const knowledgePrepared = knowledgePreparedUnflatten.flat();
     return knowledgePrepared;
@@ -4174,7 +4244,7 @@ function extractParameterNamesFromTask(task) {
             if (parameterNames.has(subparameterName)) {
                 parameterNames.delete(subparameterName);
                 parameterNames.add(foreach.parameterName);
-                // <- TODO: [🚎] Warn/logic error when `subparameterName` not used
+                // <- TODO: [🏮] Warn/logic error when `subparameterName` not used
             }
         }
     }
@@ -5787,6 +5857,7 @@ function createPipelineExecutor(options) {
 
                     @see more at https://ptbk.io/prepare-pipeline
                 `));
+        // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
     }
     let runCount = 0;
     const pipelineExecutorWithCallback = async (inputParameters, onProgress) => {
@@ -6682,11 +6753,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, 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
@@ -6753,9 +6825,38 @@ 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')) {
@@ -6792,9 +6893,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'))}
 
@@ -6812,7 +6916,96 @@ function startRemoteServer(options) {
                     https://github.com/webgptorg/promptbook
                 `));
     });
-    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) {
+            if (!(error instanceof Error)) {
+                throw 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;
@@ -6822,7 +7015,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');
@@ -6876,10 +7092,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');
@@ -6888,7 +7120,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);
@@ -6900,7 +7132,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;
@@ -7077,6 +7338,15 @@ function startRemoteServer(options) {
     }
     let isDestroyed = false;
     return {
+        get httpServer() {
+            return httpServer;
+        },
+        get expressApp() {
+            return app;
+        },
+        get socketIoServer() {
+            return server;
+        },
         get isDestroyed() {
             return isDestroyed;
         },