@promptbook/cli 0.112.0-109 → 0.112.0-110

package/src/version.ts

@@ -16,11 +16,11 @@ export const BOOK_LANGUAGE_VERSION: string_semantic_version = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.112.0-109';
+export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.112.0-110';
 
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-108`).
+ * It follows semantic versioning (e.g., `0.112.0-109`).
  *
  * @generated
  */

package/src/versions.txt

@@ -1143,3 +1143,4 @@
 0.112.0-107
 0.112.0-108
 0.112.0-109
+0.112.0-110

package/umd/index.umd.js

@@ -60,7 +60,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-109';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-110';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3204,34 +3204,54 @@
      * @private internal utility of `ptbk agents-server`
      */
     async function ensureAgentsServerBuild(options = {}) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         const environment = (_a = options.environment) !== null && _a !== void 0 ? _a : process.env;
-        const nextCliPath = resolveNextCliPath();
-        const nodeModulesPath = resolveNodeModulesPath(nextCliPath);
-        const appPath = await resolveAgentsServerBuildAppPath({
-            sourceAppPath: (_b = options.appPath) !== null && _b !== void 0 ? _b : (await resolveAgentsServerAppPath()),
-            nodeModulesPath,
+        const preparedRuntime = await prepareAgentsServerRuntime({
+            appPath: options.appPath,
         });
-        const buildEnvironment = createAgentsServerRuntimeEnvironment(environment, nodeModulesPath, {
-            isNextValidationIgnored: isAgentsServerAppPathMaterialized(appPath),
+        const buildEnvironment = createAgentsServerRuntimeEnvironment(environment, preparedRuntime.nodeModulesPath, {
+            isNextValidationIgnored: preparedRuntime.isAppPathMaterialized,
         });
         if (!options.isBuildForced &&
             (await isAgentsServerBuildCacheCurrent({
-                appPath,
+                appPath: preparedRuntime.appPath,
                 environment: buildEnvironment,
             }))) {
-            (_c = options.onBuildEvent) === null || _c === void 0 ? void 0 : _c.call(options, 'Using the cached Agents Server Next app build.');
-            return { appPath, nextCliPath, nodeModulesPath };
+            (_b = options.onBuildEvent) === null || _b === void 0 ? void 0 : _b.call(options, 'Using the cached Agents Server Next app build.');
+            return preparedRuntime;
         }
-        (_d = options.onBuildEvent) === null || _d === void 0 ? void 0 : _d.call(options, 'Building the Agents Server Next app.');
+        (_c = options.onBuildEvent) === null || _c === void 0 ? void 0 : _c.call(options, 'Building the Agents Server Next app.');
         await runNextBuild({
-            appPath,
+            appPath: preparedRuntime.appPath,
             environment: buildEnvironment,
-            nextCliPath,
+            nextCliPath: preparedRuntime.nextCliPath,
             onBuildOutput: options.onBuildOutput,
         });
-        await writeAgentsServerBuildCache({ appPath, environment: buildEnvironment });
-        return { appPath, nextCliPath, nodeModulesPath };
+        await writeAgentsServerBuildCache({
+            appPath: preparedRuntime.appPath,
+            environment: buildEnvironment,
+        });
+        return preparedRuntime;
+    }
+    /**
+     * Resolves the runtime app and dependency paths shared by Agents Server start and dev commands.
+     *
+     * @private internal utility of `ptbk agents-server`
+     */
+    async function prepareAgentsServerRuntime(options = {}) {
+        var _a;
+        const nextCliPath = resolveNextCliPath();
+        const nodeModulesPath = resolveNodeModulesPath(nextCliPath);
+        const appPath = await resolveAgentsServerBuildAppPath({
+            sourceAppPath: (_a = options.appPath) !== null && _a !== void 0 ? _a : (await resolveAgentsServerAppPath()),
+            nodeModulesPath,
+        });
+        return {
+            appPath,
+            nextCliPath,
+            nodeModulesPath,
+            isAppPathMaterialized: isAgentsServerAppPathMaterialized(appPath),
+        };
     }
     /**
      * Returns true when the production build marker and source fingerprint still match.
@@ -34171,12 +34191,16 @@
      * Default Codex reasoning effort preserved for backwards compatibility when no CLI override is provided.
      */
     const DEFAULT_CODEX_THINKING_LEVEL = 'xhigh';
+    /**
+     * Base delimiter used for passing large prompts through stdin.
+     */
+    const CODEX_PROMPT_DELIMITER = 'CODEX_PROMPT';
     /**
      * Builds the shell script that runs Codex with the prompt and coding context.
      */
     function buildCodexScript(options) {
         var _a;
-        const delimiter = 'CODEX_PROMPT';
+        const delimiter = resolveShellHereDocumentDelimiter(CODEX_PROMPT_DELIMITER, options.prompt);
         const projectPath = toPosixPath(options.projectPath);
         const loginMethodConfig = options.allowCredits
             ? 'CODEX_LOGIN_METHOD_ARGUMENTS=()'
@@ -34187,36 +34211,54 @@
               fi
           `);
         const thinkingLevel = (_a = options.thinkingLevel) !== null && _a !== void 0 ? _a : DEFAULT_CODEX_THINKING_LEVEL;
-        const modelReasoningEffortConfig = `  -c model_reasoning_effort="${thinkingLevel}" \\`;
-        return spaceTrim((block) => `
-
-            if [ -f .env ]; then
-            set -a
-            source .env
-            set +a
-            fi
-
-            ${loginMethodConfig}
-
-            if [ "\${PTBK_OPENAI_CODEX_USE_API_KEY:-0}" != "1" ] || [ -z "\${OPENAI_API_KEY:-}" ]; then
-            unset OPENAI_API_KEY
-            unset OPENAI_BASE_URL
-            fi
-
-            ${options.codexCommand} \\
-                "\${CODEX_LOGIN_METHOD_ARGUMENTS[@]}" \\
-                ${modelReasoningEffortConfig}
-                --ask-for-approval ${options.askForApproval} \\
-                exec --model ${options.model} \\
-                --local-provider none \\
-                --sandbox ${options.sandbox} \\
-                -C ${projectPath} \\
-                <<'${delimiter}'
-
-            ${block(options.prompt)}
-
-            ${delimiter}
-        `);
+        const lines = [
+            'if [ -f .env ]; then',
+            'set -a',
+            'source .env',
+            'set +a',
+            'fi',
+            '',
+            loginMethodConfig,
+            '',
+            'if [ "${PTBK_OPENAI_CODEX_USE_API_KEY:-0}" != "1" ] || [ -z "${OPENAI_API_KEY:-}" ]; then',
+            'unset OPENAI_API_KEY',
+            'unset OPENAI_BASE_URL',
+            'fi',
+            '',
+            `${options.codexCommand} \\`,
+            '    "${CODEX_LOGIN_METHOD_ARGUMENTS[@]}" \\',
+            `    -c model_reasoning_effort="${thinkingLevel}" \\`,
+            `    --ask-for-approval ${options.askForApproval} \\`,
+            `    exec --model ${options.model} \\`,
+            '    --local-provider none \\',
+            `    --sandbox ${options.sandbox} \\`,
+            `    -C ${projectPath} \\`,
+            '    --skip-git-repo-check \\',
+            `    <<'${delimiter}'`,
+            '',
+            options.prompt,
+            '',
+            delimiter,
+        ];
+        return lines.join('\n');
+    }
+    /**
+     * Resolves a here-document delimiter that cannot be confused with a line inside the prompt.
+     */
+    function resolveShellHereDocumentDelimiter(baseDelimiter, content) {
+        let delimiter = baseDelimiter;
+        let delimiterSuffix = 0;
+        while (isShellHereDocumentDelimiterPresent(content, delimiter)) {
+            delimiterSuffix += 1;
+            delimiter = `${baseDelimiter}_${delimiterSuffix}`;
+        }
+        return delimiter;
+    }
+    /**
+     * Checks whether a prompt already contains one exact here-document closing delimiter line.
+     */
+    function isShellHereDocumentDelimiterPresent(content, delimiter) {
+        return content.replace(/\r\n/gu, '\n').split('\n').some((line) => line === delimiter);
     }
 
     /**
@@ -37263,48 +37305,30 @@
         };
         process.once('exit', processExitHandler);
         try {
-            const buildArtifacts = await ensureAgentsServerBuild({
-                appPath: runtimePaths.appPath,
-                environment: childEnvironment,
-                isBuildForced: options.isBuildForced,
-                onBuildEvent: (event) => {
-                    logRunnerEvent(logStreams.runner, event);
-                    forwardChildOutput(`${event}\n`, {
-                        label: 'next-build',
-                        logStream: logStreams.next,
-                        state,
-                    });
-                },
-                onBuildOutput: (chunk) => {
-                    forwardChildOutput(chunk, {
-                        label: 'next-build',
-                        logStream: logStreams.next,
-                        state,
-                    });
-                },
+            const preparedLaunch = await prepareAgentsServerLaunch({
+                childEnvironment,
+                logStreams,
+                options,
+                runtimePaths,
+                state,
             });
-            const runtimeChildEnvironment = createAgentsServerRuntimeEnvironment(childEnvironment, buildArtifacts.nodeModulesPath);
-            const builtRuntimePaths = {
-                ...runtimePaths,
-                appPath: buildArtifacts.appPath,
-            };
             nextServerProcess = startNextServer({
-                nextCliPath: buildArtifacts.nextCliPath,
+                nextCliPath: preparedLaunch.runtimeArtifacts.nextCliPath,
                 options,
-                runtimePaths: builtRuntimePaths,
-                childEnvironment: runtimeChildEnvironment,
+                runtimePaths: preparedLaunch.runtimePaths,
+                childEnvironment: preparedLaunch.runtimeChildEnvironment,
                 logStreams,
                 state,
             });
             const localAgentRunnerLimits = await waitForLocalAgentRunnerLimits({
                 port: options.port,
-                environment: runtimeChildEnvironment,
+                environment: preparedLaunch.runtimeChildEnvironment,
                 logStreams,
                 state,
             });
             stopUserChatJobWorkerPump = startUserChatJobWorkerPump({
                 port: options.port,
-                environment: runtimeChildEnvironment,
+                environment: preparedLaunch.runtimeChildEnvironment,
                 logStreams,
                 state,
             });
@@ -37328,6 +37352,52 @@
             closeAgentsServerLogStreams(logStreams);
         }
     }
+    /**
+     * Prepares the shared Next runtime for either production start or hot-reloading development mode.
+     */
+    async function prepareAgentsServerLaunch(options) {
+        const runtimeArtifacts = options.options.nextRuntimeMode === 'start'
+            ? await ensureAgentsServerBuild({
+                appPath: options.runtimePaths.appPath,
+                environment: options.childEnvironment,
+                isBuildForced: options.options.isBuildForced,
+                onBuildEvent: (event) => {
+                    logRunnerEvent(options.logStreams.runner, event);
+                    forwardChildOutput(`${event}\n`, {
+                        label: 'next-build',
+                        logStream: options.logStreams.next,
+                        state: options.state,
+                    });
+                },
+                onBuildOutput: (chunk) => {
+                    forwardChildOutput(chunk, {
+                        label: 'next-build',
+                        logStream: options.logStreams.next,
+                        state: options.state,
+                    });
+                },
+            })
+            : await prepareAgentsServerDevelopmentRuntime(options.runtimePaths.appPath, options.logStreams.runner);
+        return {
+            runtimeArtifacts,
+            runtimeChildEnvironment: createAgentsServerRuntimeEnvironment(options.childEnvironment, runtimeArtifacts.nodeModulesPath, {
+                isNextValidationIgnored: runtimeArtifacts.isAppPathMaterialized,
+            }),
+            runtimePaths: {
+                ...options.runtimePaths,
+                appPath: runtimeArtifacts.appPath,
+            },
+        };
+    }
+    /**
+     * Resolves the hot-reloading Next runtime without running the production build step.
+     */
+    async function prepareAgentsServerDevelopmentRuntime(appPath, runnerLogStream) {
+        logRunnerEvent(runnerLogStream, 'Preparing the Agents Server Next development runtime.');
+        return prepareAgentsServerRuntime({
+            appPath,
+        });
+    }
     /**
      * Loads launch-directory `.env` values without overriding explicit process environment.
      *
@@ -37353,12 +37423,13 @@
         };
     }
     /**
-     * Starts the production Next server and wires its logs into the foreground dashboard.
+     * Starts the configured Next server mode and wires its logs into the foreground dashboard.
      */
     function startNextServer(options) {
         var _a;
-        logRunnerEvent(options.logStreams.runner, 'Starting the Agents Server Next process.');
-        const nextArguments = [options.nextCliPath, 'start', '--port', String(options.options.port)];
+        const nextRuntimeModeLabel = describeAgentsServerNextRuntimeMode(options.options.nextRuntimeMode);
+        logRunnerEvent(options.logStreams.runner, `Starting the Agents Server Next process in ${nextRuntimeModeLabel} mode.`);
+        const nextArguments = [options.nextCliPath, options.options.nextRuntimeMode, '--port', String(options.options.port)];
         const hostname = (_a = options.childEnvironment[PTBK_HOSTNAME_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
         if (hostname) {
             nextArguments.push('--hostname', hostname);
@@ -37386,6 +37457,12 @@
         });
         return commandProcess;
     }
+    /**
+     * Converts one Next runtime mode into a readable label for logs.
+     */
+    function describeAgentsServerNextRuntimeMode(nextRuntimeMode) {
+        return nextRuntimeMode === 'dev' ? 'development' : 'production';
+    }
     /**
      * Connects child stdout/stderr to the persisted Next log and visible terminal output.
      */
@@ -37710,7 +37787,7 @@
     // Note: [🟡] Code for CLI runtime [startAgentsServer](src/cli/cli-commands/agents-server/startAgentsServer.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Default port used by `ptbk agents-server start`.
+     * Default port used by `ptbk agents-server start` and `ptbk agents-server dev`.
      *
      * @private internal constant of `ptbk agents-server`
      */
@@ -37721,29 +37798,61 @@
      * @private internal function of `promptbookCli`
      */
     function $initializeAgentsServerStartCommand(program) {
-        const command = program.command('start');
-        command.description(_spaceTrim.spaceTrim(`
-            Start the Agents Server web app and the local coding-agent message runners
-
-            ${PROMPT_RUNNER_DESCRIPTION}
-
-            The current working directory stores:
-            - Agent runner folders in \`.promptbook/agents-server/agents\`
-            - Foreground service logs in \`.logs\`
-        `));
+        initializeAgentsServerRuntimeCommand(program, {
+            commandName: 'start',
+            description: createAgentsServerRuntimeCommandDescription('Start the Agents Server web app and the local coding-agent message runners'),
+            nextRuntimeMode: 'start',
+            isForceBuildSupported: true,
+        });
+    }
+    /**
+     * Initializes `agents-server dev` command for Promptbook CLI utilities.
+     *
+     * @private internal function of `promptbookCli`
+     */
+    function $initializeAgentsServerDevCommand(program) {
+        initializeAgentsServerRuntimeCommand(program, {
+            commandName: 'dev',
+            description: createAgentsServerRuntimeCommandDescription('Start the Agents Server web app in development mode with hot reloading and the local coding-agent message runners'),
+            nextRuntimeMode: 'dev',
+            isForceBuildSupported: false,
+        });
+    }
+    /**
+     * Initializes `agents-server build` command for Promptbook CLI utilities.
+     *
+     * @private internal function of `promptbookCli`
+     */
+    function $initializeAgentsServerBuildCommand(program) {
+        const command = program.command('build');
+        command.description('Build the Agents Server Next app for later local startup');
+        command.action(handleActionErrors(async () => {
+            console.info(colors__default["default"].gray('Building Promptbook Agents Server.'));
+            loadAgentsServerProjectEnvironment(process.cwd());
+            await ensureAgentsServerBuild({ isBuildForced: true });
+        }));
+    }
+    /**
+     * Registers one shared Agents Server runtime command backed by either `next start` or `next dev`.
+     */
+    function initializeAgentsServerRuntimeCommand(program, definition) {
+        const command = program.command(definition.commandName);
+        command.description(definition.description);
         addPromptRunnerSelectionOptions(command);
         addPromptRunnerRuntimeOptions(command);
         command.addOption(new commander.Option('--port <port>', 'Port to start the Agents Server on')
             .env('PORT')
             .default(DEFAULT_AGENTS_SERVER_PORT));
-        command.option('--force-build', 'Rebuild the Agents Server Next app before startup', false);
+        if (definition.isForceBuildSupported) {
+            command.option('--force-build', 'Rebuild the Agents Server Next app before startup', false);
+        }
         command.action(handleActionErrors(async (cliOptions) => {
             const options = cliOptions;
             const port = parseAgentsServerPort(options.port);
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(options, {
                 isAgentRequired: true,
             });
-            console.info(colors__default["default"].gray(`Starting Promptbook Agents Server on port ${port}.`));
+            console.info(colors__default["default"].gray(createAgentsServerRuntimeStartupMessage(port, definition.nextRuntimeMode)));
             await startAgentsServer({
                 port,
                 agentName: runnerOptions.agentName,
@@ -37751,25 +37860,35 @@
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 allowCredits: runnerOptions.allowCredits,
-                isBuildForced: options.forceBuild,
+                nextRuntimeMode: definition.nextRuntimeMode,
+                isBuildForced: definition.isForceBuildSupported && options.forceBuild === true,
             });
         }, {
             isExitingOnSuccess: false,
         }));
     }
     /**
-     * Initializes `agents-server build` command for Promptbook CLI utilities.
-     *
-     * @private internal function of `promptbookCli`
+     * Creates the shared help description for Agents Server runtime commands.
      */
-    function $initializeAgentsServerBuildCommand(program) {
-        const command = program.command('build');
-        command.description('Build the Agents Server Next app for later local startup');
-        command.action(handleActionErrors(async () => {
-            console.info(colors__default["default"].gray('Building Promptbook Agents Server.'));
-            loadAgentsServerProjectEnvironment(process.cwd());
-            await ensureAgentsServerBuild({ isBuildForced: true });
-        }));
+    function createAgentsServerRuntimeCommandDescription(summary) {
+        return _spaceTrim.spaceTrim(`
+        ${summary}
+
+        ${PROMPT_RUNNER_DESCRIPTION}
+
+        The current working directory stores:
+        - Agent runner folders in \`.promptbook/agents-server/agents\`
+        - Foreground service logs in \`.logs\`
+    `);
+    }
+    /**
+     * Creates the startup log line for one Agents Server runtime mode.
+     */
+    function createAgentsServerRuntimeStartupMessage(port, nextRuntimeMode) {
+        if (nextRuntimeMode === 'dev') {
+            return `Starting Promptbook Agents Server on port ${port} in development mode.`;
+        }
+        return `Starting Promptbook Agents Server on port ${port}.`;
     }
     /**
      * Parses and validates the user-configured Agents Server port.
@@ -37800,10 +37919,12 @@
 
             Subcommands:
             - build: Build the web server for later local startup
+            - dev: Start the web server in development mode with hot reloading
             - init: Initialize local web server configuration
             - start: Start the web server and local coding-agent message runners
         `));
         $initializeAgentsServerBuildCommand(agentsServerCommand);
+        $initializeAgentsServerDevCommand(agentsServerCommand);
         $initializeAgentsServerInitCommand(agentsServerCommand);
         $initializeAgentsServerStartCommand(agentsServerCommand);
         agentsServerCommand.action(() => {