@promptbook/cli 0.112.0-109 → 0.112.0-110

package/esm/index.es.js

@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -3202,34 +3202,54 @@ const AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN = /\.test-type\.[jt]sx?$/
  * @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.
@@ -34169,12 +34189,16 @@ async function $runGoScriptUntilMarkerIdle(options) {
  * 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=()'
@@ -34185,36 +34209,54 @@ function buildCodexScript(options) {
               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);
 }
 
 /**
@@ -37261,48 +37303,30 @@ async function startAgentsServer(options) {
     };
     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,
         });
@@ -37326,6 +37350,52 @@ async function startAgentsServer(options) {
         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.
  *
@@ -37351,12 +37421,13 @@ async function resolveAgentsServerRuntimePaths() {
     };
 }
 /**
- * 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);
@@ -37384,6 +37455,12 @@ function startNextServer(options) {
     });
     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.
  */
@@ -37708,7 +37785,7 @@ async function wait$2(delayMs) {
 // 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`
  */
@@ -37719,29 +37796,61 @@ const DEFAULT_AGENTS_SERVER_PORT = '4440';
  * @private internal function of `promptbookCli`
  */
 function $initializeAgentsServerStartCommand(program) {
-    const command = program.command('start');
-    command.description(spaceTrim$1(`
-            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.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 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.gray(`Starting Promptbook Agents Server on port ${port}.`));
+        console.info(colors.gray(createAgentsServerRuntimeStartupMessage(port, definition.nextRuntimeMode)));
         await startAgentsServer({
             port,
             agentName: runnerOptions.agentName,
@@ -37749,25 +37858,35 @@ function $initializeAgentsServerStartCommand(program) {
             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.gray('Building Promptbook Agents Server.'));
-        loadAgentsServerProjectEnvironment(process.cwd());
-        await ensureAgentsServerBuild({ isBuildForced: true });
-    }));
+function createAgentsServerRuntimeCommandDescription(summary) {
+    return spaceTrim$1(`
+        ${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.
@@ -37798,10 +37917,12 @@ function $initializeAgentsServerCommand(program) {
 
             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(() => {