@promptbook/cli 0.112.0-99 → 0.113.0-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,42 @@ 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;
+
+/**
+ * Conservative Next.js build worker count used by CLI-owned Agents Server production builds.
+ *
+ * Standalone VPS self-updates build the replacement server while the current pm2 process is
+ * still serving traffic. Keeping Next's static workers serial avoids CPU-count-based memory
+ * spikes that can make the OS kill the build child with no normal exit code.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_WORKER_COUNT = 1;
+
+/**
+ * Maximum attempts for a Next.js build that was killed by the operating system.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_ATTEMPTS = 2;
+
+/**
+ * Signals that indicate the Next.js build may have been terminated by resource pressure.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const RETRYABLE_NEXT_BUILD_SIGNALS = new Set<NodeJS.Signals | null>(['SIGKILL', null]);
+
 /**
  * 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.
@@ -42,6 +78,13 @@ const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
  */
 export const PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV = 'PTBK_AGENTS_SERVER_NODE_MODULES_PATH';
 
+/**
+ * Environment variable consumed by `apps/agents-server/next.config.ts` to throttle build workers.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+export const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = 'PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT';
+
 /**
  * Environment variable used only by the CLI-owned production build.
  *
@@ -96,12 +139,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 +219,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.
  *
@@ -157,6 +238,16 @@ type AgentsServerBuildCacheOptions = {
     readonly environment?: NodeJS.ProcessEnv;
 };
 
+/**
+ * Exit status reported by one spawned Next.js build child process.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type NextBuildExitStatus = {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+};
+
 /**
  * Ensures that the local Agents Server production build exists and matches its source fingerprint.
  *
@@ -164,39 +255,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 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 };
+    return {
+        appPath,
+        nextCliPath,
+        nodeModulesPath,
+        isAppPathMaterialized: isAgentsServerAppPathMaterialized(appPath),
+    };
 }
 
 /**
@@ -284,6 +400,8 @@ export function createAgentsServerRuntimeEnvironment(
         ...environment,
         NODE_PATH: mergeNodePath(nodeModulesPath, environment.NODE_PATH),
         [PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV]: nodeModulesPath,
+        [PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV]:
+            environment[PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV] || String(AGENTS_SERVER_BUILD_WORKER_COUNT),
         ...(options.isNextValidationIgnored
             ? {
                   [PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV]: 'true',
@@ -410,6 +528,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 +540,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),
+        )
+    );
 }
 
 /**
@@ -504,10 +670,35 @@ async function runNextBuild(options: {
     readonly nextCliPath: string;
     readonly onBuildOutput?: (chunk: string) => void;
 }): Promise<void> {
-    await new Promise<void>((resolveBuild, rejectBuild) => {
+    for (let attempt = 1; attempt <= AGENTS_SERVER_BUILD_MAX_ATTEMPTS; attempt++) {
+        const exitStatus = await runNextBuildAttempt(options);
+
+        if (exitStatus.code === 0) {
+            return;
+        }
+
+        if (attempt < AGENTS_SERVER_BUILD_MAX_ATTEMPTS && isNextBuildTerminationRetryable(exitStatus)) {
+            forwardBuildOutput(createNextBuildRetryMessage(exitStatus, attempt + 1), options.onBuildOutput);
+            continue;
+        }
+
+        throw createNextBuildExitError(exitStatus, attempt);
+    }
+}
+
+/**
+ * Runs one Next.js production build attempt and returns its exit status.
+ */
+async function runNextBuildAttempt(options: {
+    readonly appPath: string;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly nextCliPath: string;
+    readonly onBuildOutput?: (chunk: string) => void;
+}): Promise<NextBuildExitStatus> {
+    return await new Promise<NextBuildExitStatus>((resolveBuild, rejectBuild) => {
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: options.environment,
+            env: createNextBuildProcessEnvironment(options.environment),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
 
@@ -518,18 +709,96 @@ async function runNextBuild(options: {
             forwardBuildOutput(chunk.toString(), options.onBuildOutput);
         });
 
-        buildProcess.once('error', rejectBuild);
-        buildProcess.once('exit', (code) => {
-            if (code === 0) {
-                resolveBuild();
-                return;
-            }
-
-            rejectBuild(new Error(`next-build exited with code ${String(code)}.`));
+        buildProcess.once('error', (error) => {
+            rejectBuild(createNextBuildSpawnError(error));
+        });
+        buildProcess.once('close', (code, signal) => {
+            resolveBuild({ code, signal });
         });
     });
 }
 
+/**
+ * Creates the environment passed to the spawned Next.js build process.
+ */
+function createNextBuildProcessEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+    return {
+        ...environment,
+        NODE_OPTIONS: mergeNodeOptionsWithHeapSize(environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+    };
+}
+
+/**
+ * Returns true when one failed build attempt is worth retrying.
+ */
+function isNextBuildTerminationRetryable(exitStatus: NextBuildExitStatus): boolean {
+    return exitStatus.code === null && RETRYABLE_NEXT_BUILD_SIGNALS.has(exitStatus.signal);
+}
+
+/**
+ * Creates one visible retry message for a killed Next.js build attempt.
+ */
+function createNextBuildRetryMessage(exitStatus: NextBuildExitStatus, nextAttempt: number): string {
+    return `\nAgents Server Next build was terminated by ${describeNextBuildExitStatus(exitStatus)}. Retrying attempt ${nextAttempt}/${AGENTS_SERVER_BUILD_MAX_ATTEMPTS}.\n`;
+}
+
+/**
+ * Creates a branded error for a failed Next.js build child process.
+ */
+function createNextBuildExitError(exitStatus: NextBuildExitStatus, attemptCount: number): NotAllowed {
+    const lowMemoryHint = isNextBuildTerminationRetryable(exitStatus)
+        ? '\n\nThe build process was terminated by the operating system. On standalone VPS self-updates this usually means the host ran out of memory while Next.js was compiling or prerendering the app.'
+        : '';
+
+    return new NotAllowed(
+        spaceTrim(`
+            Agents Server Next production build failed.
+
+            - Exit code: \`${String(exitStatus.code)}\`
+            - Signal: \`${String(exitStatus.signal)}\`
+            - Attempts: \`${String(attemptCount)}\`
+            ${lowMemoryHint}
+        `),
+    );
+}
+
+/**
+ * Creates a branded error for failures to start the Next.js build child process.
+ */
+function createNextBuildSpawnError(error: Error): NotAllowed {
+    return new NotAllowed(
+        spaceTrim(`
+            Cannot start the Agents Server Next production build.
+
+            ${error.message}
+        `),
+    );
+}
+
+/**
+ * Formats one Next.js build exit status for foreground logs.
+ */
+function describeNextBuildExitStatus(exitStatus: NextBuildExitStatus): string {
+    if (exitStatus.signal) {
+        return `signal \`${exitStatus.signal}\``;
+    }
+
+    return `exit code \`${String(exitStatus.code)}\``;
+}
+
+/**
+ * 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 +864,10 @@ async function addAgentsServerBuildInputToFingerprint(
         readonly runtimeRootPath: string;
     },
 ): Promise<void> {
+    if (isExcludedAgentsServerBuildInputPath(options.inputPath, options.runtimeRootPath)) {
+        return;
+    }
+
     let inputStats;
 
     try {
@@ -605,10 +878,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 +905,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`