@promptbook/cli 0.113.0-7 → 0.113.0-9

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;
+    }
+}

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

@@ -0,0 +1,33 @@
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { isAgentsServerAppPath } from './isAgentsServerAppPath';
+
+/**
+ * Finds the Agents Server app in a source checkout or generated CLI package.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function resolveAgentsServerAppPath(): Promise<string> {
+    const candidates = [
+        join(process.cwd(), 'apps', 'agents-server'),
+        join(__dirname, '..', '..', '..', '..', '..', 'apps', 'agents-server'),
+        join(__dirname, '..', '..', '..', 'apps', 'agents-server'),
+        join(__dirname, '..', '..', 'apps', 'agents-server'),
+    ];
+
+    for (const candidate of candidates) {
+        if (await isAgentsServerAppPath(candidate)) {
+            return candidate;
+        }
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Cannot find the bundled Agents Server app.
+
+            Checked:
+            ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
+        `),
+    );
+}

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

@@ -0,0 +1,30 @@
+import { join, resolve } from 'path';
+import { resolvePromptbookTemporaryPath } from '../../../../utils/filesystem/promptbookTemporaryPath';
+import { isPathInsideNodeModules } from './isPathInsideNodeModules';
+import { synchronizeMaterializedAgentsServerRuntime } from './synchronizeMaterializedAgentsServerRuntime';
+
+/**
+ * Uses the source checkout app directly, but copies npm-packaged app sources out of `node_modules`.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function resolveAgentsServerBuildAppPath(options: {
+    readonly nodeModulesPath: string;
+    readonly sourceAppPath: string;
+}): Promise<string> {
+    if (!isPathInsideNodeModules(options.sourceAppPath)) {
+        return options.sourceAppPath;
+    }
+
+    const sourceRuntimeRootPath = resolve(options.sourceAppPath, '..', '..');
+    const materializedRuntimeRootPath = resolvePromptbookTemporaryPath(process.cwd(), 'agents-server', 'runtime');
+
+    await synchronizeMaterializedAgentsServerRuntime({
+        materializedRuntimeRootPath,
+        nodeModulesPath: options.nodeModulesPath,
+        sourceAppPath: options.sourceAppPath,
+        sourceRuntimeRootPath,
+    });
+
+    return join(materializedRuntimeRootPath, 'apps', 'agents-server');
+}

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

@@ -0,0 +1,19 @@
+import { resolve } from 'path';
+import type { AgentsServerBuildCacheOptions } from './AgentsServerBuildCacheOptions';
+
+/**
+ * Next output directory used by the local Agents Server runtime unless Next overrides it.
+ */
+const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
+
+/**
+ * Resolves the Next output directory used by a particular build environment.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function resolveAgentsServerBuildOutputPath(options: AgentsServerBuildCacheOptions): string {
+    return resolve(
+        options.appPath,
+        options.environment?.NEXT_DIST_DIR || DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME,
+    );
+}

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

@@ -0,0 +1,21 @@
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+
+/**
+ * Resolves the Next CLI module installed alongside the Promptbook CLI.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function resolveNextCliPath(): string {
+    try {
+        return require.resolve('next/dist/bin/next');
+    } catch {
+        throw new NotAllowed(
+            spaceTrim(`
+                Cannot start Agents Server because the \`next\` package is unavailable.
+
+                Reinstall \`ptbk\` so the CLI package contains the Agents Server runtime dependencies.
+            `),
+        );
+    }
+}

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

@@ -0,0 +1,19 @@
+import { resolve } from 'path';
+import { NODE_MODULES_DIRECTORY_NAME } from './NODE_MODULES_DIRECTORY_NAME';
+
+/**
+ * Resolves the dependency root that contains the installed Next CLI.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export function resolveNodeModulesPath(nextCliPath: string): string {
+    const normalizedNextCliPath = nextCliPath.replace(/\\/gu, '/');
+    const marker = `/${NODE_MODULES_DIRECTORY_NAME}/next/`;
+    const markerIndex = normalizedNextCliPath.lastIndexOf(marker);
+
+    if (markerIndex === -1) {
+        return resolve(nextCliPath, '..', '..', '..');
+    }
+
+    return normalizedNextCliPath.slice(0, markerIndex + marker.length - '/next/'.length);
+}

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

@@ -0,0 +1,184 @@
+import { spawn } from 'child_process';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+
+/**
+ * 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.
+ */
+const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
+
+/**
+ * Maximum attempts for a Next.js build that was killed by the operating system.
+ */
+const AGENTS_SERVER_BUILD_MAX_ATTEMPTS = 2;
+
+/**
+ * Signals that indicate the Next.js build may have been terminated by resource pressure.
+ */
+const RETRYABLE_NEXT_BUILD_SIGNALS = new Set<NodeJS.Signals | null>(['SIGKILL', null]);
+
+/**
+ * Exit status reported by one spawned Next.js build child process.
+ */
+type NextBuildExitStatus = {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+};
+
+/**
+ * Runs the finite Next production build used by local Agents Server commands.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function runNextBuild(options: {
+    readonly appPath: string;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly nextCliPath: string;
+    readonly onBuildOutput?: (chunk: string) => void;
+}): Promise<void> {
+    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: createNextBuildProcessEnvironment(options.environment),
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        buildProcess.stdout?.on('data', (chunk) => {
+            forwardBuildOutput(chunk.toString(), options.onBuildOutput);
+        });
+        buildProcess.stderr?.on('data', (chunk) => {
+            forwardBuildOutput(chunk.toString(), options.onBuildOutput);
+        });
+
+        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.
+ */
+function forwardBuildOutput(chunk: string, onBuildOutput: ((chunk: string) => void) | undefined): void {
+    if (onBuildOutput) {
+        onBuildOutput(chunk);
+        return;
+    }
+
+    process.stdout.write(chunk);
+}

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

@@ -0,0 +1,48 @@
+import { basename, relative } from 'path';
+import { isAgentsServerBuildInputTestFile } from './isAgentsServerBuildInputTestFile';
+import { isExcludedAgentsServerBuildInputDirectoryName } from './isExcludedAgentsServerBuildInputDirectoryName';
+import { isExcludedAgentsServerRuntimeSourcePath } from './isExcludedAgentsServerRuntimeSourcePath';
+
+/**
+ * Excludes build artifacts, dependency folders, private env files, and test sources.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export 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);
+
+    if (sourcePathSegments.some(isExcludedAgentsServerBuildInputDirectoryName)) {
+        return false;
+    }
+
+    if (sourcePathSegments.includes('playground')) {
+        return false;
+    }
+
+    if (isExcludedAgentsServerRuntimeSourcePath(sourceRuntimeRelativePath)) {
+        return false;
+    }
+
+    if (sourceBasename.startsWith('.env')) {
+        return false;
+    }
+
+    return !isAgentsServerBuildInputTestFile(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}`;
+}

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

@@ -0,0 +1,179 @@
+import { cp, lstat, mkdir, readFile, rm, stat, symlink, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { AGENTS_SERVER_BUILD_CACHE_VERSION } from './AGENTS_SERVER_BUILD_CACHE_VERSION';
+import { createAgentsServerBuildSourceFingerprint } from './createAgentsServerBuildSourceFingerprint';
+import { getAgentsServerBuildInputRelativePaths } from './getAgentsServerBuildInputRelativePaths';
+import { isAgentsServerAppPath } from './isAgentsServerAppPath';
+import { NODE_MODULES_DIRECTORY_NAME } from './NODE_MODULES_DIRECTORY_NAME';
+import { shouldCopyAgentsServerRuntimePath } from './shouldCopyAgentsServerRuntimePath';
+
+/**
+ * Runtime copy metadata filename stored in the project-local materialized app root.
+ */
+const AGENTS_SERVER_MATERIALIZED_RUNTIME_CACHE_FILENAME = '.ptbk-agents-server-runtime-cache.json';
+
+/**
+ * Metadata persisted after copying the npm-packaged Agents Server runtime into the launch project.
+ */
+type AgentsServerMaterializedRuntimeCache = {
+    readonly version: typeof AGENTS_SERVER_BUILD_CACHE_VERSION;
+    readonly sourceFingerprint: string;
+};
+
+/**
+ * Copies the bundled runtime into the launch project when the original app lives under `node_modules`.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function synchronizeMaterializedAgentsServerRuntime(options: {
+    readonly materializedRuntimeRootPath: string;
+    readonly nodeModulesPath: string;
+    readonly sourceAppPath: string;
+    readonly sourceRuntimeRootPath: string;
+}): Promise<void> {
+    const sourceFingerprint = await createAgentsServerBuildSourceFingerprint(options.sourceAppPath);
+    const runtimeCache = await readAgentsServerMaterializedRuntimeCache(options.materializedRuntimeRootPath);
+    const isRuntimeCurrent =
+        runtimeCache?.version === AGENTS_SERVER_BUILD_CACHE_VERSION &&
+        runtimeCache.sourceFingerprint === sourceFingerprint &&
+        (await isAgentsServerAppPath(join(options.materializedRuntimeRootPath, 'apps', 'agents-server')));
+
+    if (!isRuntimeCurrent) {
+        await rm(options.materializedRuntimeRootPath, { recursive: true, force: true });
+        await mkdir(options.materializedRuntimeRootPath, { recursive: true });
+
+        for (const relativeInputPath of getAgentsServerBuildInputRelativePaths()) {
+            await copyAgentsServerRuntimePath({
+                destinationPath: join(options.materializedRuntimeRootPath, relativeInputPath),
+                sourcePath: join(options.sourceRuntimeRootPath, relativeInputPath),
+            });
+        }
+
+        await assertMaterializedAgentsServerAppExists(options.materializedRuntimeRootPath);
+        await writeAgentsServerMaterializedRuntimeCache(options.materializedRuntimeRootPath, sourceFingerprint);
+    }
+
+    await ensureMaterializedRuntimeNodeModulesLink({
+        materializedRuntimeRootPath: options.materializedRuntimeRootPath,
+        nodeModulesPath: options.nodeModulesPath,
+    });
+}
+
+/**
+ * Verifies that the materialized runtime contains a usable Next app before caching it.
+ */
+async function assertMaterializedAgentsServerAppExists(materializedRuntimeRootPath: string): Promise<void> {
+    const materializedAppPath = join(materializedRuntimeRootPath, 'apps', 'agents-server');
+
+    if (await isAgentsServerAppPath(materializedAppPath)) {
+        return;
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Cannot prepare the bundled Agents Server runtime.
+
+            The materialized app path is missing required files:
+            \`${materializedAppPath}\`
+        `),
+    );
+}
+
+/**
+ * Copies one source path into the materialized runtime, skipping generated or private files.
+ */
+async function copyAgentsServerRuntimePath(options: {
+    readonly destinationPath: string;
+    readonly sourcePath: string;
+}): Promise<void> {
+    let sourceStats;
+
+    try {
+        sourceStats = await stat(options.sourcePath);
+    } catch {
+        return;
+    }
+
+    await mkdir(dirname(options.destinationPath), { recursive: true });
+
+    if (sourceStats.isDirectory()) {
+        await cp(options.sourcePath, options.destinationPath, {
+            recursive: true,
+            filter: (sourcePath) => shouldCopyAgentsServerRuntimePath(sourcePath, options.sourcePath),
+        });
+        return;
+    }
+
+    if (sourceStats.isFile() && shouldCopyAgentsServerRuntimePath(options.sourcePath, dirname(options.sourcePath))) {
+        await cp(options.sourcePath, options.destinationPath);
+    }
+}
+
+/**
+ * Links the materialized runtime back to the package dependency tree used by the installed CLI.
+ */
+async function ensureMaterializedRuntimeNodeModulesLink(options: {
+    readonly materializedRuntimeRootPath: string;
+    readonly nodeModulesPath: string;
+}): Promise<void> {
+    const nodeModulesLinkPath = join(options.materializedRuntimeRootPath, NODE_MODULES_DIRECTORY_NAME);
+
+    try {
+        const existingLinkStats = await lstat(nodeModulesLinkPath);
+        await rm(nodeModulesLinkPath, {
+            force: true,
+            recursive: existingLinkStats.isDirectory() && !existingLinkStats.isSymbolicLink(),
+        });
+    } catch {
+        // The link does not exist yet.
+    }
+
+    await symlink(options.nodeModulesPath, nodeModulesLinkPath, process.platform === 'win32' ? 'junction' : 'dir');
+}
+
+/**
+ * Reads and validates materialized runtime metadata.
+ */
+async function readAgentsServerMaterializedRuntimeCache(
+    materializedRuntimeRootPath: string,
+): Promise<AgentsServerMaterializedRuntimeCache | undefined> {
+    try {
+        const serializedRuntimeCache = await readFile(
+            join(materializedRuntimeRootPath, AGENTS_SERVER_MATERIALIZED_RUNTIME_CACHE_FILENAME),
+            'utf-8',
+        );
+        const runtimeCache = JSON.parse(serializedRuntimeCache) as Partial<AgentsServerMaterializedRuntimeCache>;
+
+        if (
+            runtimeCache.version !== AGENTS_SERVER_BUILD_CACHE_VERSION ||
+            typeof runtimeCache.sourceFingerprint !== 'string'
+        ) {
+            return undefined;
+        }
+
+        return runtimeCache as AgentsServerMaterializedRuntimeCache;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Persists the source fingerprint used for the materialized runtime copy.
+ */
+async function writeAgentsServerMaterializedRuntimeCache(
+    materializedRuntimeRootPath: string,
+    sourceFingerprint: string,
+): Promise<void> {
+    const runtimeCache: AgentsServerMaterializedRuntimeCache = {
+        version: AGENTS_SERVER_BUILD_CACHE_VERSION,
+        sourceFingerprint,
+    };
+
+    await writeFile(
+        join(materializedRuntimeRootPath, AGENTS_SERVER_MATERIALIZED_RUNTIME_CACHE_FILENAME),
+        `${JSON.stringify(runtimeCache, null, 4)}\n`,
+        'utf-8',
+    );
+}

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

@@ -0,0 +1,28 @@
+import { mkdir, writeFile } 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 { createAgentsServerBuildSourceFingerprint } from './createAgentsServerBuildSourceFingerprint';
+import { resolveAgentsServerBuildOutputPath } from './resolveAgentsServerBuildOutputPath';
+
+/**
+ * Persists the source fingerprint for the just-created production build.
+ *
+ * @private internal utility of `buildAgentsServer`
+ */
+export async function writeAgentsServerBuildCache(options: AgentsServerBuildCacheOptions): Promise<void> {
+    const buildOutputPath = resolveAgentsServerBuildOutputPath(options);
+    const buildCache: AgentsServerBuildCache = {
+        version: AGENTS_SERVER_BUILD_CACHE_VERSION,
+        sourceFingerprint: await createAgentsServerBuildSourceFingerprint(options.appPath),
+    };
+
+    await mkdir(buildOutputPath, { recursive: true });
+    await writeFile(
+        join(buildOutputPath, AGENTS_SERVER_BUILD_CACHE_FILENAME),
+        `${JSON.stringify(buildCache, null, 4)}\n`,
+        'utf-8',
+    );
+}