@promptbook/cli 0.112.0-99 → 0.112.0

package/src/cli/cli-commands/agent-folder/agentProjectPaths.ts

@@ -1,12 +1,20 @@
 import { join } from 'path';
 import { spaceTrim } from 'spacetrim';
-
-/**
- * Relative path to the local agent source initialized by `ptbk agent-folder init`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export const AGENT_BOOK_FILE_PATH = 'agent.book';
+import {
+    AGENT_BOOK_FILE_PATH,
+    AGENT_FAILED_MESSAGES_DIRECTORY_PATH,
+    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
+    AGENT_MESSAGES_DIRECTORY_PATH,
+    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
+} from '../../../book-3.0/agentFolderPaths';
+
+export {
+    AGENT_BOOK_FILE_PATH,
+    AGENT_FAILED_MESSAGES_DIRECTORY_PATH,
+    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
+    AGENT_MESSAGES_DIRECTORY_PATH,
+    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
+};
 
 /**
  * Relative path to local knowledge files initialized by `ptbk agent-folder init`.
@@ -15,27 +23,6 @@ export const AGENT_BOOK_FILE_PATH = 'agent.book';
  */
 export const AGENT_KNOWLEDGE_DIRECTORY_PATH = 'knowledge';
 
-/**
- * Relative path to the message queue root initialized by `ptbk agent-folder init`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export const AGENT_MESSAGES_DIRECTORY_PATH = 'messages';
-
-/**
- * Relative path to queued user messages consumed by `ptbk agent-folder run-once`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'queued');
-
-/**
- * Relative path to answered messages written by `ptbk agent-folder run-once`.
- *
- * @private internal utility of `ptbk agent-folder`
- */
-export const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'finished');
-
 /**
  * Relative path to generated local agent documentation initialized by `ptbk agent-folder init`.
  *

package/src/cli/cli-commands/agent.ts

@@ -0,0 +1,44 @@
+import colors from 'colors';
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $initializeAgentChatCommand } from './agent/chat';
+import { $initializeAgentExecCommand } from './agent/exec';
+
+/**
+ * Initializes `agent` command with subcommands for Promptbook CLI utilities.
+ *
+ * The agent command runs one `.book` source directly through a selected CLI harness:
+ * - chat: Run an interactive terminal chat session
+ * - exec: Send one message and print the response
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeAgentCommand(program: Program): $side_effect {
+    const agentCommand = program.command('agent');
+    agentCommand.description(
+        spaceTrim(`
+            Run a Promptbook agent book directly in the terminal
+
+            Subcommands:
+            - chat: Run an interactive terminal chat session
+            - exec: Send one message and print the response
+        `),
+    );
+
+    $initializeAgentChatCommand(agentCommand);
+    $initializeAgentExecCommand(agentCommand);
+
+    agentCommand.action(() => {
+        console.info(colors.yellow('Please specify a subcommand.'));
+        console.info('');
+        agentCommand.help();
+    });
+}
+
+// Note: [🟡] Code for CLI command [agent](src/cli/cli-commands/agent.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -34,6 +34,17 @@ const AGENTS_SERVER_NEXT_BUILD_ID_FILENAME = 'BUILD_ID';
  */
 const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
 
+/**
+ * Node.js heap size limit (in MiB) injected into `NODE_OPTIONS` for the Next.js production build.
+ *
+ * Next.js webpack peaks at ~1.9 GiB on a fresh install; the Node.js default cap is ~1.7 GiB,
+ * which causes an OOM crash on first-run VPS installations where swap is the primary resource.
+ * Raising the limit lets the build complete on the first attempt.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
+
 /**
  * Environment variable passed to the bundled Next app so webpack can resolve dependencies
  * installed beside `ptbk` even when the app sources are materialized into a project cache.
@@ -96,12 +107,41 @@ const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES = new Set([
     'test-results',
 ]);
 
+/**
+ * Runtime source files excluded from the packaged Agents Server copy.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATHS = new Set([
+    'src/_packages/browser.index.ts',
+    'src/_packages/browser.readme.md',
+    'src/llm-providers/_common/register/$provideLlmToolsForTestingAndScriptsAndPlayground.ts',
+    'src/llm-providers/_common/utils/assertUniqueModels.ts',
+]);
+
+/**
+ * Runtime source folders excluded from the packaged Agents Server copy.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATH_PREFIXES = [
+    'src/dialogs/simple-prompt',
+    'src/storage/local-storage',
+] as const;
+
 /**
  * Test files copied out of packaged runtime input paths because Next does not build them.
  *
  * @private internal constant of `ptbk agents-server`
  */
-const AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN = /\.(?:spec|test)\.[jt]sx?$/iu;
+const AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN = /\.(?:spec|test)(?:\.|$)/iu;
+
+/**
+ * Type-only compile check files copied out of packaged runtime input paths.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN = /\.test-type\.[jt]sx?$/iu;
 
 /**
  * Metadata persisted after one successful Agents Server production build.
@@ -147,6 +187,15 @@ export type AgentsServerBuildArtifacts = {
     readonly nextCliPath: string;
 };
 
+/**
+ * Runtime paths resolved for Agents Server commands before choosing build or dev execution.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+export type PreparedAgentsServerRuntime = AgentsServerBuildArtifacts & {
+    readonly isAppPathMaterialized: boolean;
+};
+
 /**
  * Input paths required to validate or update the cached Agents Server build.
  *
@@ -164,39 +213,64 @@ type AgentsServerBuildCacheOptions = {
  */
 export async function ensureAgentsServerBuild(
     options: EnsureAgentsServerBuildOptions = {},
-): Promise<AgentsServerBuildArtifacts> {
+): Promise<PreparedAgentsServerRuntime> {
     const environment = options.environment ?? process.env;
-    const nextCliPath = resolveNextCliPath();
-    const nodeModulesPath = resolveNodeModulesPath(nextCliPath);
-    const appPath = await resolveAgentsServerBuildAppPath({
-        sourceAppPath: options.appPath ?? (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,
         }))
     ) {
         options.onBuildEvent?.('Using the cached Agents Server Next app build.');
-        return { appPath, nextCliPath, nodeModulesPath };
+        return preparedRuntime;
     }
 
     options.onBuildEvent?.('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 });
+    await writeAgentsServerBuildCache({
+        appPath: preparedRuntime.appPath,
+        environment: buildEnvironment,
+    });
 
-    return { appPath, nextCliPath, nodeModulesPath };
+    return preparedRuntime;
+}
+
+/**
+ * Resolves the runtime app and dependency paths shared by Agents Server start and dev commands.
+ *
+ * @private internal utility of `ptbk agents-server`
+ */
+export async function prepareAgentsServerRuntime(
+    options: {
+        readonly appPath?: string;
+    } = {},
+): Promise<PreparedAgentsServerRuntime> {
+    const nextCliPath = resolveNextCliPath();
+    const nodeModulesPath = resolveNodeModulesPath(nextCliPath);
+    const appPath = await resolveAgentsServerBuildAppPath({
+        sourceAppPath: options.appPath ?? (await resolveAgentsServerAppPath()),
+        nodeModulesPath,
+    });
+
+    return {
+        appPath,
+        nextCliPath,
+        nodeModulesPath,
+        isAppPathMaterialized: isAgentsServerAppPathMaterialized(appPath),
+    };
 }
 
 /**
@@ -410,6 +484,7 @@ async function copyAgentsServerRuntimePath(options: {
  */
 function shouldCopyAgentsServerRuntimePath(sourcePath: string, sourceRootPath: string): boolean {
     const sourceRelativePath = relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+    const sourceRuntimeRelativePath = normalizeRuntimeSourceRelativePath(sourcePath, sourceRootPath);
     const sourcePathSegments = sourceRelativePath.split('/').filter(Boolean);
     const sourceBasename = basename(sourcePath);
 
@@ -421,11 +496,58 @@ function shouldCopyAgentsServerRuntimePath(sourcePath: string, sourceRootPath: s
         return false;
     }
 
+    if (sourcePathSegments.includes('playground')) {
+        return false;
+    }
+
+    if (isExcludedAgentsServerRuntimeSourcePath(sourceRuntimeRelativePath)) {
+        return false;
+    }
+
     if (sourceBasename.startsWith('.env')) {
         return false;
     }
 
-    return !AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(sourceBasename);
+    return (
+        !AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(sourceBasename) &&
+        !AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN.test(sourceBasename)
+    );
+}
+
+/**
+ * Normalizes a copied runtime path to the shape used inside the packaged runtime root.
+ */
+function normalizeRuntimeSourceRelativePath(sourcePath: string, sourceRootPath: string): string {
+    const sourceRelativePath = relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+    const sourceRootBasename = basename(sourceRootPath);
+
+    if (!sourceRelativePath) {
+        return sourceRootBasename;
+    }
+
+    return `${sourceRootBasename}/${sourceRelativePath}`;
+}
+
+/**
+ * Checks whether one normalized runtime path is equal to or nested below another path.
+ */
+function isRuntimePathWithin(sourceRuntimeRelativePath: string, excludedSourcePathPrefix: string): boolean {
+    return (
+        sourceRuntimeRelativePath === excludedSourcePathPrefix ||
+        sourceRuntimeRelativePath.startsWith(`${excludedSourcePathPrefix}/`)
+    );
+}
+
+/**
+ * Returns true for runtime source files and folders that are not needed by the Agents Server build.
+ */
+function isExcludedAgentsServerRuntimeSourcePath(sourceRuntimeRelativePath: string): boolean {
+    return (
+        AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATHS.has(sourceRuntimeRelativePath) ||
+        AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATH_PREFIXES.some((excludedSourcePathPrefix) =>
+            isRuntimePathWithin(sourceRuntimeRelativePath, excludedSourcePathPrefix),
+        )
+    );
 }
 
 /**
@@ -507,7 +629,13 @@ async function runNextBuild(options: {
     await new Promise<void>((resolveBuild, rejectBuild) => {
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: options.environment,
+            env: {
+                ...options.environment,
+                NODE_OPTIONS: mergeNodeOptionsWithHeapSize(
+                    options.environment.NODE_OPTIONS,
+                    AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB,
+                ),
+            },
             stdio: ['ignore', 'pipe', 'pipe'],
         });
 
@@ -530,6 +658,19 @@ async function runNextBuild(options: {
     });
 }
 
+/**
+ * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
+ */
+function mergeNodeOptionsWithHeapSize(existingNodeOptions: string | undefined, maxOldSpaceMib: number): string {
+    if (existingNodeOptions !== undefined && /--max-old-space-size[= ]/u.test(existingNodeOptions)) {
+        return existingNodeOptions;
+    }
+
+    const heapFlag = `--max-old-space-size=${maxOldSpaceMib}`;
+
+    return existingNodeOptions ? `${heapFlag} ${existingNodeOptions}` : heapFlag;
+}
+
 /**
  * Sends one Next build output chunk through the caller handler or to the foreground terminal.
  */
@@ -595,6 +736,10 @@ async function addAgentsServerBuildInputToFingerprint(
         readonly runtimeRootPath: string;
     },
 ): Promise<void> {
+    if (isExcludedAgentsServerBuildInputPath(options.inputPath, options.runtimeRootPath)) {
+        return;
+    }
+
     let inputStats;
 
     try {
@@ -605,10 +750,6 @@ async function addAgentsServerBuildInputToFingerprint(
     }
 
     if (inputStats.isFile()) {
-        if (isExcludedAgentsServerBuildInputFile(options.inputPath)) {
-            return;
-        }
-
         fingerprint.update(`file:${normalizeBuildInputPath(options.runtimeRootPath, options.inputPath)}\n`);
         fingerprint.update(await readFile(options.inputPath));
         fingerprint.update('\n');
@@ -636,10 +777,33 @@ async function addAgentsServerBuildInputToFingerprint(
 }
 
 /**
- * Returns true for non-build test files inside shared runtime source paths.
+ * Returns true for non-build files and folders inside shared runtime source paths.
  */
-function isExcludedAgentsServerBuildInputFile(inputPath: string): boolean {
-    return AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(basename(inputPath));
+function isExcludedAgentsServerBuildInputPath(inputPath: string, runtimeRootPath: string): boolean {
+    const inputRelativePath = normalizeBuildInputPath(runtimeRootPath, inputPath);
+    const inputPathSegments = inputRelativePath.split('/').filter(Boolean);
+    const inputBasename = basename(inputPath);
+
+    if (
+        inputPathSegments.some((inputPathSegment) =>
+            AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES.has(inputPathSegment),
+        )
+    ) {
+        return true;
+    }
+
+    if (inputPathSegments.includes('playground')) {
+        return true;
+    }
+
+    if (isExcludedAgentsServerRuntimeSourcePath(inputRelativePath)) {
+        return true;
+    }
+
+    return (
+        AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(inputBasename) ||
+        AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN.test(inputBasename)
+    );
 }
 
 /**

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

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { ensureProjectEnvFile, type EnsureProjectEnvFileResult } from '../common/projectInitialization';
 
 /**
@@ -38,6 +39,8 @@ const REQUIRED_AGENTS_SERVER_ENV_VARIABLES: ReadonlyArray<RequiredAgentsServerEn
     createAgentsServerEnvVariable('SUPABASE_SERVICE_ROLE_KEY', ''),
     createAgentsServerEnvVariable('SUPABASE_AUTO_MIGRATE', 'true'),
     createAgentsServerEnvVariable('ADMIN_PASSWORD', ''),
+    createAgentsServerEnvVariable('PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN', ''),
+    createAgentsServerEnvVariable('PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN', ''),
 ];
 
 /**
@@ -70,10 +73,20 @@ function createAgentsServerEnvVariable(name: string, value: string): RequiredAge
  */
 function buildMissingEnvVariablesBlock(variables: ReadonlyArray<RequiredAgentsServerEnvVariable>): string {
     const variableBlocks = variables.map(({ documentationUrl, name, value }) =>
-        [AGENTS_SERVER_ENV_CREATED_COMMENT, `# Documentation: ${documentationUrl}`, `${name}=${value}`].join('\n'),
+        spaceTrim(`
+            ${AGENTS_SERVER_ENV_CREATED_COMMENT}
+            # Documentation: ${documentationUrl}
+            ${name}=${value}
+        `),
     );
 
-    return ['# Promptbook Agents Server', ...variableBlocks].join('\n\n');
+    return spaceTrim(
+        (block) => `
+            # Promptbook Agents Server
+
+            ${block(variableBlocks.join('\n\n'))}
+        `,
+    );
 }
 
 // Note: [🟡] Code for Agents Server environment bootstrapping [ensureAgentsServerEnvFile](src/cli/cli-commands/agents-server/ensureAgentsServerEnvFile.ts) should never be published outside of `@promptbook/cli`

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}.`;
 }
 
 /**