@promptbook/cli 0.113.0-0 → 0.113.0-10

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

@@ -1,5 +1,6 @@
 import { spaceTrim } from 'spacetrim';
-import { ensureProjectEnvFile, type EnsureProjectEnvFileResult } from '../common/projectInitialization';
+import type { EnsureProjectEnvFileResult } from '../common/projectInitialization';
+import { ensureProjectEnvFile } from '../common/projectInitialization';
 
 /**
  * Agents Server environment variable initialized for local startup.

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

@@ -1,5 +1,6 @@
 import { PROMPTBOOK_TEMPORARY_DIRECTORY } from '../../../utils/filesystem/promptbookTemporaryPath';
-import { ensureProjectGitignoreFile, type ProjectInitializationStatus } from '../common/projectInitialization';
+import type { ProjectInitializationStatus } from '../common/projectInitialization';
+import { ensureProjectGitignoreFile } from '../common/projectInitialization';
 
 /**
  * Gitignore header for rules initialized by the Agents Server command.

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

@@ -17,11 +17,8 @@ import {
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
 import { ensureAgentsServerBuild } from './buildAgentsServer';
-import {
-    loadAgentsServerProjectEnvironment,
-    startAgentsServer,
-    type AgentsServerNextRuntimeMode,
-} from './startAgentsServer';
+import type { AgentsServerNextRuntimeMode } from './startAgentsServer';
+import { loadAgentsServerProjectEnvironment, startAgentsServer } from './startAgentsServer';
 
 /**
  * Default port used by `ptbk agents-server start` and `ptbk agents-server dev`.

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

@@ -0,0 +1,67 @@
+import { randomBytes } from 'crypto';
+import { join } from 'path';
+import type { number_port } from '../../../../types/number_positive';
+
+/**
+ * Public local agent-root environment name consumed by the Agents Server app.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const PTBK_AGENTS_SERVER_AGENT_ROOT_ENV = 'PTBK_AGENTS_SERVER_AGENT_ROOT';
+
+/**
+ * Public database mode environment name consumed by the Agents Server app.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const PTBK_AGENTS_SERVER_DATABASE_ENV = 'PTBK_AGENTS_SERVER_DATABASE';
+
+/**
+ * Local SQLite file environment name consumed by the Agents Server app.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const PTBK_AGENTS_SERVER_SQLITE_PATH_ENV = 'PTBK_AGENTS_SERVER_SQLITE_PATH';
+
+/**
+ * Entropy size for the local-only token shared by the CLI pump and the Next app.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const LOCAL_USER_CHAT_WORKER_TOKEN_BYTE_LENGTH = 32;
+
+/**
+ * Subprocess environment carrying the explicit local worker credential.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerChildEnvironment = NodeJS.ProcessEnv & {
+    readonly PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN: string;
+};
+
+/**
+ * Creates the subprocess environment for Next and its internal local runner bridge.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function createAgentsServerChildEnvironment(
+    port: number_port,
+    agentRootPath: string,
+): AgentsServerChildEnvironment {
+    const launchWorkingDirectory = process.cwd();
+
+    return {
+        ...process.env,
+        PORT: String(port),
+        NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL || `http://localhost:${port}`,
+        [PTBK_AGENTS_SERVER_AGENT_ROOT_ENV]: agentRootPath,
+        [PTBK_AGENTS_SERVER_SQLITE_PATH_ENV]:
+            process.env[PTBK_AGENTS_SERVER_SQLITE_PATH_ENV] ||
+            join(launchWorkingDirectory, '.promptbook', 'agents-server.sqlite'),
+        [PTBK_AGENTS_SERVER_DATABASE_ENV]: process.env[PTBK_AGENTS_SERVER_DATABASE_ENV] || 'supabase',
+        // Next loads app-local `.env` values after the CLI has prepared this bridge environment.
+        PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN:
+            process.env.PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN ||
+            randomBytes(LOCAL_USER_CHAT_WORKER_TOKEN_BYTE_LENGTH).toString('hex'),
+    };
+}

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

@@ -0,0 +1,43 @@
+import { createWriteStream, type WriteStream } from 'fs';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+
+/**
+ * Logger handles kept open for the foreground Agents Server lifetime.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerLogStreams = {
+    readonly next: WriteStream;
+    readonly runner: WriteStream;
+};
+
+/**
+ * Creates file streams for service output persisted below `./logs`.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function createAgentsServerLogStreams(runtimePaths: AgentsServerRuntimePaths): AgentsServerLogStreams {
+    return {
+        next: createWriteStream(runtimePaths.nextLogPath, { flags: 'a' }),
+        runner: createWriteStream(runtimePaths.runnerLogPath, { flags: 'a' }),
+    };
+}
+
+/**
+ * Closes all foreground service log streams.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function closeAgentsServerLogStreams(logStreams: AgentsServerLogStreams): void {
+    logStreams.next.end();
+    logStreams.runner.end();
+}
+
+/**
+ * Appends one timestamped runner lifecycle event into its persistent log file.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function logRunnerEvent(logStream: WriteStream, event: string): void {
+    logStream.write(`[${new Date().toISOString()}] ${event}\n`);
+}

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

@@ -0,0 +1,44 @@
+import { join } from 'path';
+import { resolvePromptbookTemporaryPath } from '../../../../utils/filesystem/promptbookTemporaryPath';
+import { resolveAgentsServerAppPath } from '../buildAgentsServer';
+
+/**
+ * Name of the local Agents Server log folder relative to the launch working directory.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const AGENTS_SERVER_LOG_DIRECTORY_NAME = '.logs';
+
+/**
+ * Captures foreground file locations for one Agents Server launch.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerRuntimePaths = {
+    readonly launchWorkingDirectory: string;
+    readonly appPath: string;
+    readonly agentRootPath: string;
+    readonly logDirectoryPath: string;
+    readonly nextLogPath: string;
+    readonly runnerLogPath: string;
+};
+
+/**
+ * Resolves local app, agent-root, and log paths for one foreground launch.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export async function resolveAgentsServerRuntimePaths(): Promise<AgentsServerRuntimePaths> {
+    const launchWorkingDirectory = process.cwd();
+    const appPath = await resolveAgentsServerAppPath();
+    const logDirectoryPath = join(launchWorkingDirectory, AGENTS_SERVER_LOG_DIRECTORY_NAME);
+
+    return {
+        launchWorkingDirectory,
+        appPath,
+        agentRootPath: resolvePromptbookTemporaryPath(launchWorkingDirectory, 'agents-server', 'agents'),
+        logDirectoryPath,
+        nextLogPath: join(logDirectoryPath, 'agents-server-next.log'),
+        runnerLogPath: join(logDirectoryPath, 'agents-server-runner.log'),
+    };
+}

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

@@ -0,0 +1,59 @@
+import { spaceTrim } from 'spacetrim';
+import type { CoderRunUiHandle } from '../../../../../scripts/run-codex-prompts/ui/renderCoderRunUi';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+
+/**
+ * Mutable supervisor state shared with child-process and watcher callbacks.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerSupervisorState = {
+    isContinuing: boolean;
+    uiHandle?: CoderRunUiHandle;
+    lastUserChatJobWorkerError?: {
+        message: string;
+        repeatCount: number;
+    };
+    nextExit?: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    };
+};
+
+/**
+ * Adds one Next or worker output line to the rich terminal UI when it is active.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function addUiOutput(state: AgentsServerSupervisorState, output: string): void {
+    state.uiHandle?.state.addAgentOutput(output);
+}
+
+/**
+ * Adds one service error line to the rich terminal UI when it is active.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function addUiError(state: AgentsServerSupervisorState, error: string): void {
+    state.uiHandle?.state.addError(error);
+}
+
+/**
+ * Throws when the server child stopped while the watcher was still expected to be foreground work.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function assertNextServerStillRunning(state: AgentsServerSupervisorState): void {
+    if (!state.nextExit) {
+        return;
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Agents Server Next process stopped.
+
+            - Exit code: \`${String(state.nextExit.code)}\`
+            - Signal: \`${String(state.nextExit.signal)}\`
+        `),
+    );
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Local runner limits loaded from the running Agents Server app.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+    readonly maxParallelMessages: number;
+};

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

@@ -0,0 +1,14 @@
+import type { PreparedAgentsServerRuntime } from '../buildAgentsServer';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+
+/**
+ * Prepared Next runtime and child environment used by one foreground launch.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type PreparedAgentsServerLaunch = {
+    readonly runtimeArtifacts: PreparedAgentsServerRuntime;
+    readonly runtimeChildEnvironment: AgentsServerChildEnvironment;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+};

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

@@ -0,0 +1,26 @@
+import type { number_port } from '../../../../types/number_positive';
+import type { ThinkingLevel } from '../../coder/ThinkingLevel';
+import type { PromptRunnerHarnessName } from '../../common/promptRunnerCliOptions';
+
+/**
+ * Next runtime mode supported by the local Agents Server foreground launcher.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerNextRuntimeMode = 'start' | 'dev';
+
+/**
+ * Options required to start the foreground Agents Server service group.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type StartAgentsServerOptions = {
+    readonly port: number_port;
+    readonly agentName: PromptRunnerHarnessName;
+    readonly model?: string;
+    readonly noUi: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly allowCredits: boolean;
+    readonly nextRuntimeMode: AgentsServerNextRuntimeMode;
+    readonly isBuildForced: boolean;
+};

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

@@ -0,0 +1,15 @@
+/**
+ * Builds a foreground failure message for one internal Agents Server route.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function createInternalRouteErrorMessage(routeLabel: string, response: Response, details: string | null): string {
+    const statusText = response.statusText ? ` ${response.statusText}` : '';
+    const statusMessage = `${response.status}${statusText}`;
+
+    if (!details) {
+        return `Internal ${routeLabel} route returned ${statusMessage}.`;
+    }
+
+    return `Internal ${routeLabel} route returned ${statusMessage}: ${details}`;
+}

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

@@ -0,0 +1,29 @@
+import type { AgentRunOptions } from '../../../../../scripts/run-agent-messages/AgentRunOptions';
+import type { LocalAgentRunnerLimits } from './LocalAgentRunnerLimits';
+import type { StartAgentsServerOptions } from './StartAgentsServerOptions';
+
+/**
+ * Creates local no-git agent runner options for folders managed by the Agents Server database.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function createLocalAgentRunOptions(
+    options: StartAgentsServerOptions,
+    localAgentRunnerLimits: LocalAgentRunnerLimits,
+): AgentRunOptions {
+    return {
+        agentName: options.agentName,
+        model: options.model,
+        noUi: options.noUi,
+        thinkingLevel: options.thinkingLevel,
+        noCommit: true,
+        ignoreGitChanges: true,
+        normalizeLineEndings: false,
+        allowCredits: options.allowCredits,
+        autoPush: false,
+        autoPull: false,
+        autoClone: false,
+        maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
+        maxParallelMessages: localAgentRunnerLimits.maxParallelMessages,
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { WriteStream } from 'fs';
+import { addUiOutput, type AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+
+/**
+ * Persists one child output chunk and forwards readable lines into UI or plain output.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function forwardChildOutput(
+    chunk: string,
+    options: {
+        readonly label: string;
+        readonly logStream: WriteStream;
+        readonly state: AgentsServerSupervisorState;
+    },
+): void {
+    options.logStream.write(chunk);
+
+    const visibleLines = chunk
+        .split(/\r?\n/gu)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0);
+
+    for (const line of visibleLines) {
+        const labeledLine = `[${options.label}] ${line}`;
+        if (options.state.uiHandle) {
+            addUiOutput(options.state, labeledLine);
+        } else {
+            process.stdout.write(`${labeledLine}\n`);
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+import * as dotenv from 'dotenv';
+import { join } from 'path';
+
+/**
+ * Project environment file read from the Agents Server launch directory.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const AGENTS_SERVER_PROJECT_ENV_FILE_NAME = '.env';
+
+/**
+ * Loads launch-directory `.env` values without overriding explicit process environment.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function loadAgentsServerProjectEnvironment(launchWorkingDirectory: string): void {
+    dotenv.config({ path: join(launchWorkingDirectory, AGENTS_SERVER_PROJECT_ENV_FILE_NAME) });
+}

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

@@ -0,0 +1,81 @@
+import type { WriteStream } from 'fs';
+import {
+    createAgentsServerRuntimeEnvironment,
+    ensureAgentsServerBuild,
+    prepareAgentsServerRuntime,
+    type PreparedAgentsServerRuntime,
+} from '../buildAgentsServer';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerLogStreams } from './AgentsServerLogStreams';
+import { logRunnerEvent } from './AgentsServerLogStreams';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+import { forwardChildOutput } from './forwardChildOutput';
+import type { PreparedAgentsServerLaunch } from './PreparedAgentsServerLaunch';
+import type { StartAgentsServerOptions } from './StartAgentsServerOptions';
+
+/**
+ * Prepares the shared Next runtime for either production start or hot-reloading development mode.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export async function prepareAgentsServerLaunch(options: {
+    readonly childEnvironment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly startOptions: StartAgentsServerOptions;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+    readonly state: AgentsServerSupervisorState;
+}): Promise<PreparedAgentsServerLaunch> {
+    const runtimeArtifacts =
+        options.startOptions.nextRuntimeMode === 'start'
+            ? await ensureAgentsServerBuild({
+                  appPath: options.runtimePaths.appPath,
+                  environment: options.childEnvironment,
+                  isBuildForced: options.startOptions.isBuildForced,
+                  onBuildEvent: (event) => {
+                      logRunnerEvent(options.logStreams.runner, event);
+                      forwardChildOutput(`${event}\n`, {
+                          label: 'next-build',
+                          logStream: options.logStreams.next,
+                          state: options.state,
+                      });
+                  },
+                  onBuildOutput: (chunk) => {
+                      forwardChildOutput(chunk, {
+                          label: 'next-build',
+                          logStream: options.logStreams.next,
+                          state: options.state,
+                      });
+                  },
+              })
+            : await prepareAgentsServerDevelopmentRuntime(options.runtimePaths.appPath, options.logStreams.runner);
+
+    return {
+        runtimeArtifacts,
+        runtimeChildEnvironment: createAgentsServerRuntimeEnvironment(
+            options.childEnvironment,
+            runtimeArtifacts.nodeModulesPath,
+            {
+                isNextValidationIgnored: runtimeArtifacts.isAppPathMaterialized,
+            },
+        ) as AgentsServerChildEnvironment,
+        runtimePaths: {
+            ...options.runtimePaths,
+            appPath: runtimeArtifacts.appPath,
+        },
+    };
+}
+
+/**
+ * Resolves the hot-reloading Next runtime without running the production build step.
+ */
+async function prepareAgentsServerDevelopmentRuntime(
+    appPath: string,
+    runnerLogStream: WriteStream,
+): Promise<PreparedAgentsServerRuntime> {
+    logRunnerEvent(runnerLogStream, 'Preparing the Agents Server Next development runtime.');
+
+    return prepareAgentsServerRuntime({
+        appPath,
+    });
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Maximum internal route response body length shown in foreground diagnostics.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const INTERNAL_ROUTE_ERROR_BODY_MAX_LENGTH = 2_000;
+
+/**
+ * Reads an internal route error payload so foreground logs show the route-level reason.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export async function readInternalRouteErrorDetails(response: Response): Promise<string | null> {
+    const body = await response.text().catch(() => '');
+    const trimmedBody = body.trim();
+
+    if (!trimmedBody) {
+        return null;
+    }
+
+    const parsedMessage = parseInternalRouteErrorMessage(trimmedBody);
+    return truncateInternalRouteErrorDetails(parsedMessage || trimmedBody);
+}
+
+/**
+ * Extracts a readable error message from an internal route JSON response.
+ */
+function parseInternalRouteErrorMessage(body: string): string | null {
+    try {
+        const parsedBody = JSON.parse(body) as {
+            error?: unknown;
+            message?: unknown;
+        };
+        const errorMessage = typeof parsedBody.error === 'string' ? parsedBody.error : undefined;
+        const fallbackMessage = typeof parsedBody.message === 'string' ? parsedBody.message : undefined;
+
+        return errorMessage || fallbackMessage || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Keeps foreground internal-route diagnostics bounded when a route returns a large payload.
+ */
+function truncateInternalRouteErrorDetails(details: string): string {
+    if (details.length <= INTERNAL_ROUTE_ERROR_BODY_MAX_LENGTH) {
+        return details;
+    }
+
+    return `${details.slice(0, INTERNAL_ROUTE_ERROR_BODY_MAX_LENGTH)}...`;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Optional hostname used by the internal Next server.
+ *
+ * @private internal constant of `startAgentsServer`
+ */
+const PTBK_HOSTNAME_ENV = 'PTBK_HOSTNAME';
+
+/**
+ * Resolves the optional Next hostname from the prepared child environment.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function resolveAgentsServerChildHostname(environment: NodeJS.ProcessEnv): string | null {
+    const hostname = environment[PTBK_HOSTNAME_ENV]?.trim();
+
+    return hostname || null;
+}

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

@@ -0,0 +1,97 @@
+import { spawn, type ChildProcess } from 'child_process';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerLogStreams } from './AgentsServerLogStreams';
+import { logRunnerEvent } from './AgentsServerLogStreams';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+import { addUiError, type AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+import { forwardChildOutput } from './forwardChildOutput';
+import { resolveAgentsServerChildHostname } from './resolveAgentsServerChildHostname';
+import type { AgentsServerNextRuntimeMode, StartAgentsServerOptions } from './StartAgentsServerOptions';
+
+/**
+ * Starts the configured Next server mode and wires its logs into the foreground dashboard.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export function startNextServer(options: {
+    readonly nextCliPath: string;
+    readonly startOptions: StartAgentsServerOptions;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+    readonly childEnvironment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly state: AgentsServerSupervisorState;
+}): ChildProcess {
+    const nextRuntimeModeLabel = describeAgentsServerNextRuntimeMode(options.startOptions.nextRuntimeMode);
+
+    logRunnerEvent(
+        options.logStreams.runner,
+        `Starting the Agents Server Next process in ${nextRuntimeModeLabel} mode.`,
+    );
+    const nextArguments = [
+        options.nextCliPath,
+        options.startOptions.nextRuntimeMode,
+        '--port',
+        String(options.startOptions.port),
+    ];
+    const hostname = resolveAgentsServerChildHostname(options.childEnvironment);
+
+    if (hostname) {
+        nextArguments.push('--hostname', hostname);
+        logRunnerEvent(options.logStreams.runner, `Binding Agents Server Next process to ${hostname}.`);
+    }
+
+    const commandProcess = spawn(process.execPath, nextArguments, {
+        cwd: options.runtimePaths.appPath,
+        env: options.childEnvironment,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    bindChildOutput(commandProcess, {
+        label: 'next',
+        logStream: options.logStreams.next,
+        state: options.state,
+    });
+
+    commandProcess.once('exit', (code, signal) => {
+        options.state.nextExit = { code, signal };
+        options.state.isContinuing = false;
+        logRunnerEvent(
+            options.logStreams.runner,
+            `Agents Server Next process exited with code ${String(code)} and signal ${String(signal)}.`,
+        );
+    });
+
+    commandProcess.once('error', (error) => {
+        options.state.isContinuing = false;
+        logRunnerEvent(options.logStreams.runner, `Agents Server Next process failed: ${error.message}`);
+        addUiError(options.state, error.message);
+    });
+
+    return commandProcess;
+}
+
+/**
+ * Converts one Next runtime mode into a readable label for logs.
+ */
+function describeAgentsServerNextRuntimeMode(nextRuntimeMode: AgentsServerNextRuntimeMode): string {
+    return nextRuntimeMode === 'dev' ? 'development' : 'production';
+}
+
+/**
+ * Connects child stdout/stderr to the persisted Next log and visible terminal output.
+ */
+function bindChildOutput(
+    commandProcess: ChildProcess,
+    options: {
+        readonly label: string;
+        readonly logStream: AgentsServerLogStreams['next'];
+        readonly state: AgentsServerSupervisorState;
+    },
+): void {
+    commandProcess.stdout?.on('data', (chunk) => {
+        forwardChildOutput(chunk.toString(), options);
+    });
+    commandProcess.stderr?.on('data', (chunk) => {
+        forwardChildOutput(chunk.toString(), options);
+    });
+}