@promptbook/cli 0.112.0-99 → 0.113.0-0

package/src/cli/cli-commands/agents-server/run.ts

@@ -17,23 +17,39 @@ import {
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
 import { ensureAgentsServerBuild } from './buildAgentsServer';
-import { loadAgentsServerProjectEnvironment, startAgentsServer } from './startAgentsServer';
+import {
+    loadAgentsServerProjectEnvironment,
+    startAgentsServer,
+    type AgentsServerNextRuntimeMode,
+} from './startAgentsServer';
 
 /**
- * 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`
  */
 const DEFAULT_AGENTS_SERVER_PORT = '4440';
 
 /**
- * CLI options accepted by `ptbk agents-server start`.
+ * CLI options accepted by `ptbk agents-server start` and `ptbk agents-server dev`.
  *
  * @private internal type of `ptbk agents-server`
  */
-type AgentsServerStartCliOptions = PromptRunnerSelectionCliOptions & {
+type AgentsServerRuntimeCliOptions = PromptRunnerSelectionCliOptions & {
     readonly port: string;
-    readonly forceBuild: boolean;
+    readonly forceBuild?: boolean;
+};
+
+/**
+ * Shared command definition for one Agents Server runtime subcommand.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type AgentsServerRuntimeCommandDefinition = {
+    readonly commandName: 'start' | 'dev';
+    readonly description: string;
+    readonly nextRuntimeMode: AgentsServerNextRuntimeMode;
+    readonly isForceBuildSupported: boolean;
 };
 
 /**
@@ -42,19 +58,59 @@ type AgentsServerStartCliOptions = PromptRunnerSelectionCliOptions & {
  * @private internal function of `promptbookCli`
  */
 export function $initializeAgentsServerStartCommand(program: Program): $side_effect {
-    const command = program.command('start');
-    command.description(
-        spaceTrim(`
-            Start the Agents Server web app and the local coding-agent message runners
+    initializeAgentsServerRuntimeCommand(program, {
+        commandName: 'start',
+        description: createAgentsServerRuntimeCommandDescription(
+            'Start the Agents Server web app and the local coding-agent message runners',
+        ),
+        nextRuntimeMode: 'start',
+        isForceBuildSupported: true,
+    });
+}
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+/**
+ * Initializes `agents-server dev` command for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeAgentsServerDevCommand(program: Program): $side_effect {
+    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,
+    });
+}
 
-            The current working directory stores:
-            - Agent runner folders in \`.promptbook/agents-server/agents\`
-            - Foreground service logs in \`.logs\`
-        `),
+/**
+ * Initializes `agents-server build` command for Promptbook CLI utilities.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeAgentsServerBuildCommand(program: Program): $side_effect {
+    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: Program,
+    definition: AgentsServerRuntimeCommandDefinition,
+): $side_effect {
+    const command = program.command(definition.commandName);
+
+    command.description(definition.description);
     addPromptRunnerSelectionOptions(command);
     addPromptRunnerRuntimeOptions(command);
     command.addOption(
@@ -62,18 +118,21 @@ export function $initializeAgentsServerStartCommand(program: Program): $side_eff
             .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 as AgentsServerStartCliOptions;
+                const options = cliOptions as AgentsServerRuntimeCliOptions;
                 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!,
@@ -81,7 +140,8 @@ export function $initializeAgentsServerStartCommand(program: Program): $side_eff
                     noUi: runnerOptions.noUi,
                     thinkingLevel: runnerOptions.thinkingLevel,
                     allowCredits: runnerOptions.allowCredits,
-                    isBuildForced: options.forceBuild,
+                    nextRuntimeMode: definition.nextRuntimeMode,
+                    isBuildForced: definition.isForceBuildSupported && options.forceBuild === true,
                 });
             },
             {
@@ -92,20 +152,32 @@ export function $initializeAgentsServerStartCommand(program: Program): $side_eff
 }
 
 /**
- * Initializes `agents-server build` command for Promptbook CLI utilities.
- *
- * @private internal function of `promptbookCli`
+ * Creates the shared help description for Agents Server runtime commands.
  */
-export function $initializeAgentsServerBuildCommand(program: Program): $side_effect {
-    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: string): string {
+    return 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: number_port,
+    nextRuntimeMode: AgentsServerNextRuntimeMode,
+): string {
+    if (nextRuntimeMode === 'dev') {
+        return `Starting Promptbook Agents Server on port ${port} in development mode.`;
+    }
+
+    return `Starting Promptbook Agents Server on port ${port}.`;
 }
 
 /**

package/src/cli/cli-commands/agents-server/startAgentsServer.ts

@@ -6,7 +6,7 @@ import { join } from 'path';
 import * as dotenv from 'dotenv';
 import { spaceTrim } from 'spacetrim';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import type { PromptRunnerAgentName } from '../common/promptRunnerCliOptions';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import { NotAllowed } from '../../../errors/NotAllowed';
 import type { number_port } from '../../../types/number_positive';
 import { resolvePromptbookTemporaryPath } from '../../../utils/filesystem/promptbookTemporaryPath';
@@ -17,15 +17,21 @@ import type { CoderRunUiHandle } from '../../../../scripts/run-codex-prompts/ui/
 import {
     createAgentsServerRuntimeEnvironment,
     ensureAgentsServerBuild,
+    prepareAgentsServerRuntime,
+    type PreparedAgentsServerRuntime,
     resolveAgentsServerAppPath,
 } from './buildAgentsServer';
+import {
+    DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+    DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+} from '../../../../apps/agents-server/src/constants/serverLimits';
 
 /**
  * Local worker-pump delay while the Agents Server foreground process stays active.
  *
  * @private internal constant of `ptbk agents-server`
  */
-const USER_CHAT_JOB_WORKER_POLL_INTERVAL_MS = 2_000;
+const USER_CHAT_JOB_WORKER_POLL_INTERVAL_MS = 10_000;
 
 /**
  * Number of identical worker failures suppressed before logging a repeated summary.
@@ -41,6 +47,20 @@ const USER_CHAT_JOB_WORKER_REPEATED_ERROR_LOG_INTERVAL = 10;
  */
 const USER_CHAT_JOB_WORKER_ERROR_BODY_MAX_LENGTH = 2_000;
 
+/**
+ * Delay between foreground CLI attempts to load internal Agents Server limits during startup.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const INTERNAL_SERVER_LIMITS_RETRY_DELAY_MS = 1_000;
+
+/**
+ * Maximum time spent waiting for the internal limits route before startup fails.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const INTERNAL_SERVER_LIMITS_STARTUP_TIMEOUT_MS = 60_000;
+
 /**
  * HTTP status used by an idle internal worker tick with no job to process.
  *
@@ -97,6 +117,13 @@ const PTBK_HOSTNAME_ENV = 'PTBK_HOSTNAME';
  */
 const LOCAL_USER_CHAT_WORKER_TOKEN_BYTE_LENGTH = 32;
 
+/**
+ * Next runtime mode supported by the local Agents Server foreground launcher.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+export type AgentsServerNextRuntimeMode = 'start' | 'dev';
+
 /**
  * Options required to start the foreground Agents Server service group.
  *
@@ -104,11 +131,12 @@ const LOCAL_USER_CHAT_WORKER_TOKEN_BYTE_LENGTH = 32;
  */
 export type StartAgentsServerOptions = {
     readonly port: number_port;
-    readonly agentName: PromptRunnerAgentName;
+    readonly agentName: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly allowCredits: boolean;
+    readonly nextRuntimeMode: AgentsServerNextRuntimeMode;
     readonly isBuildForced: boolean;
 };
 
@@ -163,6 +191,27 @@ type AgentsServerSupervisorState = {
     };
 };
 
+/**
+ * Prepared Next runtime and child environment used by one foreground launch.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type PreparedAgentsServerLaunch = {
+    readonly runtimeArtifacts: PreparedAgentsServerRuntime;
+    readonly runtimeChildEnvironment: AgentsServerChildEnvironment;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+};
+
+/**
+ * Local runner limits loaded from the running Agents Server app.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+    readonly maxParallelMessages: number;
+};
+
 /**
  * Starts the Agents Server web app and local coding-agent queue workers in the foreground.
  *
@@ -192,52 +241,37 @@ export async function startAgentsServer(options: StartAgentsServerOptions): Prom
     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 runtimeChildEnvironment = createAgentsServerRuntimeEnvironment(
+        const preparedLaunch = await prepareAgentsServerLaunch({
             childEnvironment,
-            buildArtifacts.nodeModulesPath,
-        ) as AgentsServerChildEnvironment;
-        const builtRuntimePaths: AgentsServerRuntimePaths = {
-            ...runtimePaths,
-            appPath: buildArtifacts.appPath,
-        };
+            logStreams,
+            options,
+            runtimePaths,
+            state,
+        });
 
         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: preparedLaunch.runtimeChildEnvironment,
             logStreams,
             state,
         });
         stopUserChatJobWorkerPump = startUserChatJobWorkerPump({
             port: options.port,
-            environment: runtimeChildEnvironment,
+            environment: preparedLaunch.runtimeChildEnvironment,
             logStreams,
             state,
         });
 
         await withCurrentWorkingDirectory(runtimePaths.agentRootPath, async () => {
-            await runMultipleAgentMessages(createLocalAgentRunOptions(options), {
+            await runMultipleAgentMessages(createLocalAgentRunOptions(options, localAgentRunnerLimits), {
                 shouldContinue: () => state.isContinuing,
                 watchErrorLogDirectoryPath: runtimePaths.logDirectoryPath,
                 onUiInitialized: (uiHandle) => {
@@ -260,6 +294,70 @@ export async function startAgentsServer(options: StartAgentsServerOptions): Prom
     }
 }
 
+/**
+ * Prepares the shared Next runtime for either production start or hot-reloading development mode.
+ */
+async function prepareAgentsServerLaunch(options: {
+    readonly childEnvironment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly options: StartAgentsServerOptions;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+    readonly state: AgentsServerSupervisorState;
+}): Promise<PreparedAgentsServerLaunch> {
+    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,
+            },
+        ) as AgentsServerChildEnvironment,
+        runtimePaths: {
+            ...options.runtimePaths,
+            appPath: runtimeArtifacts.appPath,
+        },
+    };
+}
+
+/**
+ * Resolves the hot-reloading Next runtime without running the production build step.
+ */
+async function prepareAgentsServerDevelopmentRuntime(
+    appPath: string,
+    runnerLogStream: WriteStream,
+): Promise<PreparedAgentsServerRuntime> {
+    logRunnerEvent(runnerLogStream, 'Preparing the Agents Server Next development runtime.');
+
+    return prepareAgentsServerRuntime({
+        appPath,
+    });
+}
+
 /**
  * Loads launch-directory `.env` values without overriding explicit process environment.
  *
@@ -288,7 +386,7 @@ async function resolveAgentsServerRuntimePaths(): Promise<AgentsServerRuntimePat
 }
 
 /**
- * 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: {
     readonly nextCliPath: string;
@@ -298,8 +396,18 @@ function startNextServer(options: {
     readonly logStreams: AgentsServerLogStreams;
     readonly state: AgentsServerSupervisorState;
 }): ChildProcess {
-    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 = options.childEnvironment[PTBK_HOSTNAME_ENV]?.trim();
 
     if (hostname) {
@@ -337,6 +445,13 @@ function startNextServer(options: {
     return commandProcess;
 }
 
+/**
+ * Converts one Next runtime mode into a readable label for logs.
+ */
+function describeAgentsServerNextRuntimeMode(nextRuntimeMode: AgentsServerNextRuntimeMode): string {
+    return nextRuntimeMode === 'dev' ? 'development' : 'production';
+}
+
 /**
  * Connects child stdout/stderr to the persisted Next log and visible terminal output.
  */
@@ -409,7 +524,10 @@ function createAgentsServerChildEnvironment(port: number_port, agentRootPath: st
 /**
  * Creates local no-git agent runner options for folders managed by the Agents Server database.
  */
-function createLocalAgentRunOptions(options: StartAgentsServerOptions): AgentRunOptions {
+function createLocalAgentRunOptions(
+    options: StartAgentsServerOptions,
+    localAgentRunnerLimits: LocalAgentRunnerLimits,
+): AgentRunOptions {
     return {
         agentName: options.agentName,
         model: options.model,
@@ -422,9 +540,106 @@ function createLocalAgentRunOptions(options: StartAgentsServerOptions): AgentRun
         autoPush: false,
         autoPull: false,
         autoClone: false,
+        maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
+        maxParallelMessages: localAgentRunnerLimits.maxParallelMessages,
     };
 }
 
+/**
+ * Waits until the internal Next route can return current local runner limits.
+ */
+async function waitForLocalAgentRunnerLimits(options: {
+    readonly port: number_port;
+    readonly environment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly state: AgentsServerSupervisorState;
+}): Promise<LocalAgentRunnerLimits> {
+    const startedAt = Date.now();
+    let lastError: unknown;
+
+    while (options.state.isContinuing && Date.now() - startedAt < INTERNAL_SERVER_LIMITS_STARTUP_TIMEOUT_MS) {
+        try {
+            const limits = await fetchLocalAgentRunnerLimits(options);
+            logRunnerEvent(
+                options.logStreams.runner,
+                `Local agent runner limits: ${limits.maxFailedAttempts} failed attempt(s), ${limits.maxParallelMessages} parallel message(s).`,
+            );
+            return limits;
+        } catch (error) {
+            lastError = error;
+            await wait(INTERNAL_SERVER_LIMITS_RETRY_DELAY_MS);
+        }
+    }
+
+    if (!options.state.isContinuing) {
+        return {
+            maxFailedAttempts: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+            maxParallelMessages: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+        };
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Failed to load local agent runner limits from the Agents Server.
+
+            ${lastError instanceof Error ? lastError.message : String(lastError)}
+        `),
+    );
+}
+
+/**
+ * Loads local runner limits through the token-protected internal Agents Server route.
+ */
+async function fetchLocalAgentRunnerLimits(options: {
+    readonly port: number_port;
+    readonly environment: AgentsServerChildEnvironment;
+}): Promise<LocalAgentRunnerLimits> {
+    const response = await fetch(`http://localhost:${options.port}/api/internal/agent-runner-limits`, {
+        method: 'GET',
+        cache: 'no-store',
+        headers: {
+            'x-user-chat-worker-token': options.environment.PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN,
+        },
+    });
+
+    if (!response.ok) {
+        const details = await readUserChatJobWorkerErrorDetails(response);
+        throw new Error(createInternalRouteErrorMessage('agent runner limits', response, details));
+    }
+
+    const payload = (await response.json()) as Partial<LocalAgentRunnerLimits>;
+    return {
+        maxFailedAttempts: normalizeLocalAgentRunnerMaxFailedAttempts(payload.maxFailedAttempts),
+        maxParallelMessages: normalizeLocalAgentRunnerMaxParallelMessages(payload.maxParallelMessages),
+    };
+}
+
+/**
+ * Normalizes the local runner retry cap returned by the internal server route.
+ */
+function normalizeLocalAgentRunnerMaxFailedAttempts(rawValue: unknown): number {
+    const parsedValue = Number(rawValue);
+
+    if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+        return DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS;
+    }
+
+    return Math.floor(parsedValue);
+}
+
+/**
+ * Normalizes the local runner parallel message cap returned by the internal server route.
+ */
+function normalizeLocalAgentRunnerMaxParallelMessages(rawValue: unknown): number {
+    const parsedValue = Number(rawValue);
+
+    if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+        return DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES;
+    }
+
+    return Math.floor(parsedValue);
+}
+
 /**
  * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
  */
@@ -563,14 +778,21 @@ function parseUserChatJobWorkerErrorMessage(body: string): string | null {
  * Builds the foreground worker failure message from HTTP status and route details.
  */
 function createUserChatJobWorkerErrorMessage(response: Response, details: string | null): string {
+    return createInternalRouteErrorMessage('user chat worker', response, details);
+}
+
+/**
+ * Builds a foreground failure message for one internal Agents Server route.
+ */
+function createInternalRouteErrorMessage(routeLabel: string, response: Response, details: string | null): string {
     const statusText = response.statusText ? ` ${response.statusText}` : '';
     const statusMessage = `${response.status}${statusText}`;
 
     if (!details) {
-        return `Internal user chat worker returned ${statusMessage}.`;
+        return `Internal ${routeLabel} route returned ${statusMessage}.`;
     }
 
-    return `Internal user chat worker returned ${statusMessage}: ${details}`;
+    return `Internal ${routeLabel} route returned ${statusMessage}: ${details}`;
 }
 
 /**
@@ -652,4 +874,11 @@ function stopChildProcess(commandProcess: ChildProcess | undefined): void {
     commandProcess.kill();
 }
 
+/**
+ * Waits for the given delay.
+ */
+async function wait(delayMs: number): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
 // Note: [🟡] Code for CLI runtime [startAgentsServer](src/cli/cli-commands/agents-server/startAgentsServer.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/agents-server.ts

@@ -5,7 +5,11 @@ import type {
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { $initializeAgentsServerInitCommand } from './agents-server/init';
-import { $initializeAgentsServerBuildCommand, $initializeAgentsServerStartCommand } from './agents-server/run';
+import {
+    $initializeAgentsServerBuildCommand,
+    $initializeAgentsServerDevCommand,
+    $initializeAgentsServerStartCommand,
+} from './agents-server/run';
 
 /**
  * Initializes `agents-server` command with subcommands for Promptbook CLI utilities.
@@ -20,12 +24,14 @@ export function $initializeAgentsServerCommand(program: Program): $side_effect {
 
             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);
 

package/src/cli/cli-commands/coder/ThinkingLevel.ts

@@ -1,9 +1,11 @@
+import { CLI_AGENT_THINKING_LEVEL_VALUES } from '../../../book-3.0/cliAgentEnv';
+
 /**
  * Supported thinking-level CLI values for coding-agent runners with configurable reasoning effort.
  *
  * @private internal shared utility of `ptbk coder run`
  */
-export const THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'] as const;
+export const THINKING_LEVEL_VALUES = CLI_AGENT_THINKING_LEVEL_VALUES;
 
 /**
  * Supported reasoning effort values for coding-agent runners with configurable thinking levels.

package/src/cli/cli-commands/coder/agentCodingFile.ts

@@ -45,7 +45,7 @@ export function getDefaultCoderAgentCodingFileContent({
             6. Use \`npm run coder:verify\` to archive finished prompts into \`${formatDisplayPath(
                 PROMPTS_DONE_DIRECTORY_PATH,
             )}/\` and append repair follow-up prompts when more work is needed.
-            7. Use \`npm run coder:find-refactor-candidates\` when you want Promptbook to suggest refactor prompts automatically.
+            7. Use \`ptbk coder find-refactor-candidates\` when you want Promptbook to suggest refactor prompts automatically.
 
             ## Templates
             -   Project-owned templates created by \`ptbk coder init\`: ${formatInlineCodeList(