@promptbook/cli 0.113.0-0 → 0.113.0-10

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

@@ -1,16 +1,11 @@
 import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { AGENT_BOOK_FILE_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_KNOWLEDGE_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-} from './agentProjectPaths';
+import { AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH, AGENT_KNOWLEDGE_DIRECTORY_PATH } from './agentProjectPaths';
 import { initializeAgentProjectConfiguration } from './initializeAgentProjectConfiguration';
 import { printAgentInitializationSummary } from './printAgentInitializationSummary';
 

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

@@ -1,17 +1,8 @@
+import { AGENT_BOOK_FILE_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 import type { InitializationStatus } from '../coder/boilerplateTemplates';
 import { ensureCoderMarkdownFile } from '../coder/ensureCoderMarkdownFile';
 import { ensureDirectory } from '../coder/ensureDirectory';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH,
-    AGENT_DOCS_DIRECTORY_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_KNOWLEDGE_DIRECTORY_PATH,
-    AGENT_MESSAGES_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-    getDefaultAgentBookContent,
-    getDefaultBookLanguageManualContent,
-} from './agentProjectPaths';
+import { AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH, AGENT_DOCS_DIRECTORY_PATH, AGENT_KNOWLEDGE_DIRECTORY_PATH, getDefaultAgentBookContent, getDefaultBookLanguageManualContent } from './agentProjectPaths';
 
 /**
  * Result summary returned after local agent configuration initialization.

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

@@ -1,14 +1,7 @@
 import colors from 'colors';
+import { AGENT_BOOK_FILE_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
 import type { InitializationStatus } from '../coder/boilerplateTemplates';
-import {
-    AGENT_BOOK_FILE_PATH,
-    AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH,
-    AGENT_DOCS_DIRECTORY_PATH,
-    AGENT_FINISHED_MESSAGES_DIRECTORY_PATH,
-    AGENT_KNOWLEDGE_DIRECTORY_PATH,
-    AGENT_MESSAGES_DIRECTORY_PATH,
-    AGENT_QUEUED_MESSAGES_DIRECTORY_PATH,
-} from './agentProjectPaths';
+import { AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH, AGENT_DOCS_DIRECTORY_PATH, AGENT_KNOWLEDGE_DIRECTORY_PATH } from './agentProjectPaths';
 import type { AgentInitializationSummary } from './initializeAgentProjectConfiguration';
 
 /**

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

@@ -0,0 +1,6 @@
+/**
+ * Metadata file stored beside the production Next build output.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const AGENTS_SERVER_BUILD_CACHE_FILENAME = '.ptbk-agents-server-build-cache.json';

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

@@ -0,0 +1,6 @@
+/**
+ * Version of the CLI-owned Agents Server build cache metadata.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const AGENTS_SERVER_BUILD_CACHE_VERSION = 1;

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

@@ -0,0 +1,6 @@
+/**
+ * Next production build marker required before a cached build is reused.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const AGENTS_SERVER_NEXT_BUILD_ID_FILENAME = 'BUILD_ID';

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

@@ -0,0 +1,11 @@
+import { AGENTS_SERVER_BUILD_CACHE_VERSION } from './AGENTS_SERVER_BUILD_CACHE_VERSION';
+
+/**
+ * Metadata persisted after one successful Agents Server production build.
+ *
+ * @private internal type of `buildAgentsServer`
+ */
+export type AgentsServerBuildCache = {
+    readonly version: typeof AGENTS_SERVER_BUILD_CACHE_VERSION;
+    readonly sourceFingerprint: string;
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Input paths required to validate or update the cached Agents Server build.
+ *
+ * @private internal type of `buildAgentsServer`
+ */
+export type AgentsServerBuildCacheOptions = {
+    readonly appPath: string;
+    readonly environment?: NodeJS.ProcessEnv;
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Directory segment used for Node package installs.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const NODE_MODULES_DIRECTORY_NAME = 'node_modules';

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

@@ -0,0 +1,19 @@
+/**
+ * Paths needed after the Agents Server production build is ready.
+ *
+ * @private internal type of `buildAgentsServer`
+ */
+export type AgentsServerBuildArtifacts = {
+    readonly appPath: string;
+    readonly nodeModulesPath: string;
+    readonly nextCliPath: string;
+};
+
+/**
+ * Runtime paths resolved for Agents Server commands before choosing build or dev execution.
+ *
+ * @private internal type of `buildAgentsServer`
+ */
+export type PreparedAgentsServerRuntime = AgentsServerBuildArtifacts & {
+    readonly isAppPathMaterialized: boolean;
+};

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

@@ -0,0 +1,71 @@
+import { createHash, type Hash } from 'crypto';
+import { readFile, readdir, stat } from 'fs/promises';
+import { join, resolve } from 'path';
+import { getAgentsServerBuildInputRelativePaths } from './getAgentsServerBuildInputRelativePaths';
+import { isExcludedAgentsServerBuildInputPath } from './isExcludedAgentsServerBuildInputPath';
+import { normalizeAgentsServerBuildInputPath } from './normalizeAgentsServerBuildInputPath';
+
+/**
+ * Fingerprints all runtime source paths that can affect the local Agents Server build.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function createAgentsServerBuildSourceFingerprint(appPath: string): Promise<string> {
+    const runtimeRootPath = resolve(appPath, '..', '..');
+    const fingerprint = createHash('sha256');
+
+    for (const relativeInputPath of getAgentsServerBuildInputRelativePaths()) {
+        await addAgentsServerBuildInputToFingerprint(fingerprint, {
+            inputPath: join(runtimeRootPath, relativeInputPath),
+            runtimeRootPath,
+        });
+    }
+
+    return fingerprint.digest('hex');
+}
+
+/**
+ * Adds one runtime source file or directory subtree to the production build fingerprint.
+ */
+async function addAgentsServerBuildInputToFingerprint(
+    fingerprint: Hash,
+    options: {
+        readonly inputPath: string;
+        readonly runtimeRootPath: string;
+    },
+): Promise<void> {
+    if (isExcludedAgentsServerBuildInputPath(options.inputPath, options.runtimeRootPath)) {
+        return;
+    }
+
+    let inputStats;
+
+    try {
+        inputStats = await stat(options.inputPath);
+    } catch {
+        fingerprint.update(`missing:${normalizeAgentsServerBuildInputPath(options.runtimeRootPath, options.inputPath)}\n`);
+        return;
+    }
+
+    if (inputStats.isFile()) {
+        fingerprint.update(`file:${normalizeAgentsServerBuildInputPath(options.runtimeRootPath, options.inputPath)}\n`);
+        fingerprint.update(await readFile(options.inputPath));
+        fingerprint.update('\n');
+        return;
+    }
+
+    if (!inputStats.isDirectory()) {
+        return;
+    }
+
+    fingerprint.update(`directory:${normalizeAgentsServerBuildInputPath(options.runtimeRootPath, options.inputPath)}\n`);
+    const inputDirents = await readdir(options.inputPath, { withFileTypes: true });
+    const sortedInputDirents = [...inputDirents].sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const inputDirent of sortedInputDirents) {
+        await addAgentsServerBuildInputToFingerprint(fingerprint, {
+            inputPath: join(options.inputPath, inputDirent.name),
+            runtimeRootPath: options.runtimeRootPath,
+        });
+    }
+}

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

@@ -0,0 +1,69 @@
+import { delimiter } from 'path';
+
+/**
+ * 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.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+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 `buildAgentsServer`
+ */
+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.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = 'PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION';
+
+/**
+ * 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.
+ */
+const AGENTS_SERVER_BUILD_WORKER_COUNT = 1;
+
+/**
+ * Adds dependency-resolution environment required by the materialized Agents Server runtime.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function createAgentsServerRuntimeEnvironment(
+    environment: NodeJS.ProcessEnv,
+    nodeModulesPath: string,
+    options: {
+        readonly isNextValidationIgnored?: boolean;
+    } = {},
+): NodeJS.ProcessEnv {
+    return {
+        ...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',
+              }
+            : {}),
+    };
+}
+
+/**
+ * Prepends one dependency root to `NODE_PATH` while preserving any existing value.
+ */
+function mergeNodePath(nodeModulesPath: string, nodePath: string | undefined): string {
+    if (!nodePath) {
+        return nodeModulesPath;
+    }
+
+    return `${nodeModulesPath}${delimiter}${nodePath}`;
+}

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

@@ -0,0 +1,59 @@
+import { createAgentsServerRuntimeEnvironment } from './createAgentsServerRuntimeEnvironment';
+import { isAgentsServerBuildCacheCurrent } from './isAgentsServerBuildCacheCurrent';
+import { prepareAgentsServerRuntime } from './prepareAgentsServerRuntime';
+import type { PreparedAgentsServerRuntime } from './PreparedAgentsServerRuntime';
+import { runNextBuild } from './runNextBuild';
+import { writeAgentsServerBuildCache } from './writeAgentsServerBuildCache';
+
+/**
+ * Inputs controlling one cached Agents Server production build.
+ */
+type EnsureAgentsServerBuildOptions = {
+    readonly appPath?: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly isBuildForced?: boolean;
+    readonly onBuildEvent?: (event: string) => void;
+    readonly onBuildOutput?: (chunk: string) => void;
+};
+
+/**
+ * Ensures that the local Agents Server production build exists and matches its source fingerprint.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function ensureAgentsServerBuild(
+    options: EnsureAgentsServerBuildOptions = {},
+): Promise<PreparedAgentsServerRuntime> {
+    const environment = options.environment ?? process.env;
+    const preparedRuntime = await prepareAgentsServerRuntime({
+        appPath: options.appPath,
+    });
+    const buildEnvironment = createAgentsServerRuntimeEnvironment(environment, preparedRuntime.nodeModulesPath, {
+        isNextValidationIgnored: preparedRuntime.isAppPathMaterialized,
+    });
+
+    if (
+        !options.isBuildForced &&
+        (await isAgentsServerBuildCacheCurrent({
+            appPath: preparedRuntime.appPath,
+            environment: buildEnvironment,
+        }))
+    ) {
+        options.onBuildEvent?.('Using the cached Agents Server Next app build.');
+        return preparedRuntime;
+    }
+
+    options.onBuildEvent?.('Building the Agents Server Next app.');
+    await runNextBuild({
+        appPath: preparedRuntime.appPath,
+        environment: buildEnvironment,
+        nextCliPath: preparedRuntime.nextCliPath,
+        onBuildOutput: options.onBuildOutput,
+    });
+    await writeAgentsServerBuildCache({
+        appPath: preparedRuntime.appPath,
+        environment: buildEnvironment,
+    });
+
+    return preparedRuntime;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Runtime paths copied into the CLI package and used by the Agents Server production build.
+ */
+const AGENTS_SERVER_BUILD_INPUT_RELATIVE_PATHS = [
+    'apps/agents-server',
+    'apps/_common',
+    'src',
+    'books',
+    'package.json',
+    'package-lock.json',
+    'security.config.ts',
+    'servers.ts',
+    'tsconfig.json',
+] as const;
+
+/**
+ * Returns runtime input paths that can affect the materialized runtime and build fingerprint.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function getAgentsServerBuildInputRelativePaths(): typeof AGENTS_SERVER_BUILD_INPUT_RELATIVE_PATHS {
+    return AGENTS_SERVER_BUILD_INPUT_RELATIVE_PATHS;
+}

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

@@ -0,0 +1,20 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+
+/**
+ * Returns true when one folder contains the Next Agents Server app marker files.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function isAgentsServerAppPath(candidate: string): Promise<boolean> {
+    try {
+        const [packageStats, nextConfigStats] = await Promise.all([
+            stat(join(candidate, 'package.json')),
+            stat(join(candidate, 'next.config.ts')),
+        ]);
+
+        return packageStats.isFile() && nextConfigStats.isFile();
+    } catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,17 @@
+import { resolvePromptbookTemporaryPath } from '../../../../utils/filesystem/promptbookTemporaryPath';
+
+/**
+ * Returns true when the app path points at the project-local materialized runtime.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function isAgentsServerAppPathMaterialized(appPath: string): boolean {
+    const normalizedAppPath = appPath.replace(/\\/gu, '/');
+    const normalizedMaterializedRuntimePath = resolvePromptbookTemporaryPath(
+        process.cwd(),
+        'agents-server',
+        'runtime',
+    ).replace(/\\/gu, '/');
+
+    return normalizedAppPath.includes(normalizedMaterializedRuntimePath);
+}

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

@@ -0,0 +1,27 @@
+import { join } from 'path';
+import { AGENTS_SERVER_NEXT_BUILD_ID_FILENAME } from './AGENTS_SERVER_NEXT_BUILD_ID_FILENAME';
+import type { AgentsServerBuildCacheOptions } from './AgentsServerBuildCacheOptions';
+import { createAgentsServerBuildSourceFingerprint } from './createAgentsServerBuildSourceFingerprint';
+import { isFile } from './isFile';
+import { readAgentsServerBuildCache } from './readAgentsServerBuildCache';
+import { resolveAgentsServerBuildOutputPath } from './resolveAgentsServerBuildOutputPath';
+
+/**
+ * Returns true when the production build marker and source fingerprint still match.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function isAgentsServerBuildCacheCurrent(options: AgentsServerBuildCacheOptions): Promise<boolean> {
+    const buildCache = await readAgentsServerBuildCache(options);
+
+    if (!buildCache) {
+        return false;
+    }
+
+    const buildOutputPath = resolveAgentsServerBuildOutputPath(options);
+    if (!(await isFile(join(buildOutputPath, AGENTS_SERVER_NEXT_BUILD_ID_FILENAME)))) {
+        return false;
+    }
+
+    return buildCache.sourceFingerprint === (await createAgentsServerBuildSourceFingerprint(options.appPath));
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Test files copied out of packaged runtime input paths because Next does not build them.
+ */
+const AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN = /\.(?:spec|test)(?:\.|$)/iu;
+
+/**
+ * Type-only compile check files copied out of packaged runtime input paths.
+ */
+const AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN = /\.test-type\.[jt]sx?$/iu;
+
+/**
+ * Returns true for test files that should not affect packaged Agents Server builds.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function isAgentsServerBuildInputTestFile(inputBasename: string): boolean {
+    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/buildAgentsServer/isExcludedAgentsServerBuildInputDirectoryName.ts

@@ -0,0 +1,22 @@
+/**
+ * Directory names excluded while copying or fingerprinting production build inputs.
+ */
+const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES = new Set([
+    '.git',
+    '.next',
+    '.next-e2e',
+    '.promptbook',
+    'coverage',
+    'node_modules',
+    'playwright-report',
+    'test-results',
+]);
+
+/**
+ * Returns true when a directory segment should not affect Agents Server production builds.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function isExcludedAgentsServerBuildInputDirectoryName(directoryName: string): boolean {
+    return AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES.has(directoryName);
+}

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

@@ -0,0 +1,30 @@
+import { basename } from 'path';
+import { isAgentsServerBuildInputTestFile } from './isAgentsServerBuildInputTestFile';
+import { isExcludedAgentsServerBuildInputDirectoryName } from './isExcludedAgentsServerBuildInputDirectoryName';
+import { isExcludedAgentsServerRuntimeSourcePath } from './isExcludedAgentsServerRuntimeSourcePath';
+import { normalizeAgentsServerBuildInputPath } from './normalizeAgentsServerBuildInputPath';
+
+/**
+ * Returns true for non-build files and folders inside shared runtime source paths.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function isExcludedAgentsServerBuildInputPath(inputPath: string, runtimeRootPath: string): boolean {
+    const inputRelativePath = normalizeAgentsServerBuildInputPath(runtimeRootPath, inputPath);
+    const inputPathSegments = inputRelativePath.split('/').filter(Boolean);
+    const inputBasename = basename(inputPath);
+
+    if (inputPathSegments.some(isExcludedAgentsServerBuildInputDirectoryName)) {
+        return true;
+    }
+
+    if (inputPathSegments.includes('playground')) {
+        return true;
+    }
+
+    if (isExcludedAgentsServerRuntimeSourcePath(inputRelativePath)) {
+        return true;
+    }
+
+    return isAgentsServerBuildInputTestFile(inputBasename);
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Runtime source files excluded from the packaged Agents Server copy.
+ */
+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.
+ */
+const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATH_PREFIXES = [
+    'src/dialogs/simple-prompt',
+    'src/storage/local-storage',
+] as const;
+
+/**
+ * Returns true for runtime source files and folders that are not needed by the Agents Server build.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export 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),
+        )
+    );
+}
+
+/**
+ * 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}/`)
+    );
+}

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

@@ -0,0 +1,14 @@
+import { stat } from 'fs/promises';
+
+/**
+ * Returns true when one path exists as a regular file.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function isFile(path: string): Promise<boolean> {
+    try {
+        return (await stat(path)).isFile();
+    } catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,10 @@
+import { NODE_MODULES_DIRECTORY_NAME } from './NODE_MODULES_DIRECTORY_NAME';
+
+/**
+ * Returns true when one path is nested below a `node_modules` segment.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function isPathInsideNodeModules(path: string): boolean {
+    return path.split(/[\\/]+/u).includes(NODE_MODULES_DIRECTORY_NAME);
+}

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

@@ -0,0 +1,10 @@
+import { relative } from 'path';
+
+/**
+ * Normalizes one absolute runtime path so cache fingerprints are stable across platforms.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function normalizeAgentsServerBuildInputPath(runtimeRootPath: string, inputPath: string): string {
+    return relative(runtimeRootPath, inputPath).replace(/\\/gu, '/');
+}

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

@@ -0,0 +1,31 @@
+import { isAgentsServerAppPathMaterialized } from './isAgentsServerAppPathMaterialized';
+import type { PreparedAgentsServerRuntime } from './PreparedAgentsServerRuntime';
+import { resolveAgentsServerAppPath } from './resolveAgentsServerAppPath';
+import { resolveAgentsServerBuildAppPath } from './resolveAgentsServerBuildAppPath';
+import { resolveNextCliPath } from './resolveNextCliPath';
+import { resolveNodeModulesPath } from './resolveNodeModulesPath';
+
+/**
+ * Resolves the runtime app and dependency paths shared by Agents Server start and dev commands.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+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),
+    };
+}

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

@@ -0,0 +1,35 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { AGENTS_SERVER_BUILD_CACHE_FILENAME } from './AGENTS_SERVER_BUILD_CACHE_FILENAME';
+import { AGENTS_SERVER_BUILD_CACHE_VERSION } from './AGENTS_SERVER_BUILD_CACHE_VERSION';
+import type { AgentsServerBuildCache } from './AgentsServerBuildCache';
+import type { AgentsServerBuildCacheOptions } from './AgentsServerBuildCacheOptions';
+import { resolveAgentsServerBuildOutputPath } from './resolveAgentsServerBuildOutputPath';
+
+/**
+ * Reads and validates cached build metadata.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function readAgentsServerBuildCache(
+    options: AgentsServerBuildCacheOptions,
+): Promise<AgentsServerBuildCache | undefined> {
+    try {
+        const serializedBuildCache = await readFile(
+            join(resolveAgentsServerBuildOutputPath(options), AGENTS_SERVER_BUILD_CACHE_FILENAME),
+            'utf-8',
+        );
+        const buildCache = JSON.parse(serializedBuildCache) as Partial<AgentsServerBuildCache>;
+
+        if (
+            buildCache.version !== AGENTS_SERVER_BUILD_CACHE_VERSION ||
+            typeof buildCache.sourceFingerprint !== 'string'
+        ) {
+            return undefined;
+        }
+
+        return buildCache as AgentsServerBuildCache;
+    } catch {
+        return undefined;
+    }
+}