@promptbook/cli 0.112.0 → 0.113.0-1

package/umd/index.umd.js

@@ -63,7 +63,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-1';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3303,6 +3303,28 @@
      * @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(['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.
@@ -3310,6 +3332,12 @@
      * @private internal constant of `ptbk agents-server`
      */
     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`
+     */
+    const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = 'PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT';
     /**
      * Environment variable used only by the CLI-owned production build.
      *
@@ -3510,6 +3538,7 @@
             ...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',
@@ -3696,14 +3725,27 @@
      * Runs the finite Next production build used by local Agents Server commands.
      */
     async function runNextBuild(options) {
-        await new Promise((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) {
+        return await new Promise((resolveBuild, rejectBuild) => {
             var _a, _b;
             const buildProcess = child_process.spawn(process.execPath, [options.nextCliPath, 'build'], {
                 cwd: options.appPath,
-                env: {
-                    ...options.environment,
-                    NODE_OPTIONS: mergeNodeOptionsWithHeapSize(options.environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
-                },
+                env: createNextBuildProcessEnvironment(options.environment),
                 stdio: ['ignore', 'pipe', 'pipe'],
             });
             (_a = buildProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
@@ -3712,16 +3754,70 @@
             (_b = buildProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => {
                 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) {
+        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) {
+        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, nextAttempt) {
+        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, attemptCount) {
+        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.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) {
+        return new NotAllowed(_spaceTrim.spaceTrim(`
+            Cannot start the Agents Server Next production build.
+
+            ${error.message}
+        `));
+    }
+    /**
+     * Formats one Next.js build exit status for foreground logs.
+     */
+    function describeNextBuildExitStatus(exitStatus) {
+        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.
      */
@@ -16452,6 +16548,70 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * META VISIBILITY commitment definition.
+     *
+     * The `META VISIBILITY` commitment stores whether an agent is public, private, or unlisted.
+     * Agents Server mirrors this value into the database for efficient filtering, but the book
+     * commitment remains the editable source of truth.
+     *
+     * @private Metadata-only commitment used by Agents Server.
+     */
+    class MetaVisibilityCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('META VISIBILITY');
+        }
+        /**
+         * Short one-line description of META VISIBILITY.
+         */
+        get description() {
+            return 'Set whether the agent is private, unlisted, or public.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '👁️';
+        }
+        /**
+         * Markdown documentation for META VISIBILITY commitment.
+         */
+        get documentation() {
+            return _spaceTrim.spaceTrim(`
+            # META VISIBILITY
+
+            Sets the agent visibility used by Agents Server.
+
+            ## Allowed values
+
+            - \`PRIVATE\` - accessible only to signed-in users with access.
+            - \`UNLISTED\` - accessible by direct link but hidden from public listings.
+            - \`PUBLIC\` - visible in public listings and accessible by anyone.
+
+            ## Key aspects
+
+            - Does not modify the agent's behavior, system message, or tools.
+            - Whitespace and letter case are normalized when persisted.
+            - If multiple \`META VISIBILITY\` commitments are present, persistence keeps one normalized value.
+            - Agents Server mirrors the value into the database for filtering, but the book is the source of truth.
+
+            ## Example
+
+            \`\`\`book
+            Helpful Assistant
+
+            GOAL Be helpful and friendly.
+            META VISIBILITY PUBLIC
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // META VISIBILITY is metadata only and does not alter model requirements.
+            return requirements;
+        }
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * META VOICE commitment definition
      *
@@ -22947,31 +23107,65 @@
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
-     * This error type indicates that some limit was reached
+     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
      *
      * @public exported from `@promptbook/core`
      */
-    class LimitReachedError extends Error {
+    class ParseError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'LimitReachedError';
-            Object.setPrototypeOf(this, LimitReachedError.prototype);
+            this.name = 'ParseError';
+            Object.setPrototypeOf(this, ParseError.prototype);
         }
     }
+    // TODO: Maybe split `ParseError` and `ApplyError`
 
     /**
-     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+     * Supported visibility states for persisted agents.
      *
      * @public exported from `@promptbook/core`
      */
-    class ParseError extends Error {
+    const AGENT_VISIBILITY_VALUES = ['PRIVATE', 'UNLISTED', 'PUBLIC'];
+    /**
+     * Returns `true` when the value is one of supported visibility states.
+     *
+     * @param value - Raw value to validate.
+     * @returns Whether the value is a valid `AgentVisibility`.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function isAgentVisibility(value) {
+        return typeof value === 'string' && AGENT_VISIBILITY_VALUES.includes(value);
+    }
+    /**
+     * Normalizes raw visibility text into a supported value.
+     *
+     * @param value - Raw visibility value.
+     * @returns Normalized visibility, or `null` when invalid.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function normalizeAgentVisibility(value) {
+        if (typeof value !== 'string') {
+            return null;
+        }
+        const normalized = value.trim().toUpperCase();
+        return isAgentVisibility(normalized) ? normalized : null;
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
+    /**
+     * This error type indicates that some limit was reached
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class LimitReachedError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'ParseError';
-            Object.setPrototypeOf(this, ParseError.prototype);
+            this.name = 'LimitReachedError';
+            Object.setPrototypeOf(this, LimitReachedError.prototype);
         }
     }
-    // TODO: Maybe split `ParseError` and `ApplyError`
 
     /**
      * Maximum allowed source length for create-agent payloads.
@@ -25306,6 +25500,7 @@
         new MetaDomainCommitmentDefinition(),
         new MetaDisclaimerCommitmentDefinition(),
         new MetaInputPlaceholderCommitmentDefinition(),
+        new MetaVisibilityCommitmentDefinition(),
         new MetaCommitmentDefinition(),
         new MetaVoiceCommitmentDefinition(),
         new NoteCommitmentDefinition('NOTE'),
@@ -25757,6 +25952,7 @@
         'META COLOR': applyMetaColorContent,
         'META FONT': applyMetaFontContent,
         'META VOICE': applyMetaVoiceContent,
+        'META VISIBILITY': applyMetaVisibilityContent,
     };
     /**
      * Applies META-style commitments that mutate parsed profile metadata.
@@ -25786,6 +25982,10 @@
             applyMetaAvatarContent(state, metaValue);
             return;
         }
+        if (metaTypeRaw.toUpperCase() === 'VISIBILITY') {
+            applyMetaVisibilityContent(state, metaValue);
+            return;
+        }
         const metaType = normalizeTo_camelCase(metaTypeRaw);
         state.meta[metaType] = metaValue;
     }
@@ -25862,6 +26062,15 @@
     function applyMetaVoiceContent(state, content) {
         state.meta.voice = _spaceTrim.spaceTrim(content);
     }
+    /**
+     * Applies META VISIBILITY content into the normalized `meta.visibility` field.
+     */
+    function applyMetaVisibilityContent(state, content) {
+        const visibility = normalizeAgentVisibility(content);
+        if (visibility) {
+            state.meta.visibility = visibility;
+        }
+    }
     /**
      * Normalizes the separator in the content
      *
@@ -37434,7 +37643,7 @@
         validateAgentRunOptions(options);
         const projectPath = tickOptions.projectPath || process.cwd();
         let queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
-        let queuedMessage = queueSnapshot.queuedMessages[0];
+        let queuedMessage = resolveSelectedQueuedMessage(queueSnapshot, tickOptions.queuedMessage);
         if (!queuedMessage) {
             announceNoQueuedMessages(tickOptions);
             return { isMessageProcessed: false };
@@ -37449,7 +37658,7 @@
         });
         if (autoPullTimestamp !== undefined) {
             queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
-            queuedMessage = queueSnapshot.queuedMessages[0];
+            queuedMessage = resolveSelectedQueuedMessage(queueSnapshot, tickOptions.queuedMessage);
             if (!queuedMessage) {
                 if (tickOptions.uiHandle && !((_b = tickOptions.uiPresentation) === null || _b === void 0 ? void 0 : _b.isSharedDashboard)) {
                     updateAgentRunUiForWatching(tickOptions.uiHandle, queueSnapshot);
@@ -37475,7 +37684,7 @@
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.updateProgress(((_e = tickOptions.uiPresentation) === null || _e === void 0 ? void 0 : _e.completedProgressStats) ||
                     createAgentQueueProgressSnapshot({
                         finishedMessageCount: queueSnapshot.finishedMessageCount + 1,
-                        queuedMessages: queueSnapshot.queuedMessages.slice(1),
+                        queuedMessages: removeQueuedMessageFromSnapshot(queueSnapshot, queuedMessage),
                     }));
                 if ((_f = tickOptions.uiPresentation) === null || _f === void 0 ? void 0 : _f.completedAgentStatusLines) {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAgentStatusLines([...tickOptions.uiPresentation.completedAgentStatusLines]);
@@ -37487,7 +37696,9 @@
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewLines([...tickOptions.uiPresentation.completedMessagePreviewLines]);
                 }
                 if ((_j = tickOptions.uiPresentation) === null || _j === void 0 ? void 0 : _j.completedMessagePreviewSections) {
-                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewSections([...tickOptions.uiPresentation.completedMessagePreviewSections]);
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewSections([
+                        ...tickOptions.uiPresentation.completedMessagePreviewSections,
+                    ]);
                 }
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Message answered');
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('done');
@@ -37515,6 +37726,21 @@
             printAgentGitIdentityTipAtProcessExitIfNeeded();
         }
     }
+    /**
+     * Resolves either the explicitly selected queued message or the first available queue item.
+     */
+    function resolveSelectedQueuedMessage(queueSnapshot, selectedQueuedMessage) {
+        if (!selectedQueuedMessage) {
+            return queueSnapshot.queuedMessages[0];
+        }
+        return queueSnapshot.queuedMessages.find((queuedMessage) => queuedMessage.relativePath === selectedQueuedMessage.relativePath);
+    }
+    /**
+     * Creates a progress queue list with the processed message removed from its original snapshot.
+     */
+    function removeQueuedMessageFromSnapshot(queueSnapshot, processedQueuedMessage) {
+        return queueSnapshot.queuedMessages.filter((queuedMessage) => queuedMessage.relativePath !== processedQueuedMessage.relativePath);
+    }
     /**
      * Runs the selected coding runner for one message and finalizes the answered file.
      */
@@ -37635,7 +37861,9 @@
             return;
         }
         uiHandle.state.setCurrentPrompt(queuedMessage.relativePath);
-        uiHandle.state.setMessagePreviewLines([...((uiPresentation === null || uiPresentation === void 0 ? void 0 : uiPresentation.messagePreviewLines) || agentUiMetadata.latestUserMessageLines)]);
+        uiHandle.state.setMessagePreviewLines([
+            ...((uiPresentation === null || uiPresentation === void 0 ? void 0 : uiPresentation.messagePreviewLines) || agentUiMetadata.latestUserMessageLines),
+        ]);
         uiHandle.state.setPhase('loading');
         uiHandle.state.setStatusMessage('Preparing message');
     }
@@ -37914,12 +38142,16 @@
      * Watches all direct child agent repositories from the current directory in one shared session.
      */
     async function runMultipleAgentMessages(options, controls = {}) {
-        var _a;
+        var _a, _b;
         validateAgentRunOptions(options);
         validateAgentWatchOptions('ptbk agent-folder run-multiple', options);
         const rootPath = process.cwd();
         const shouldContinue = controls.shouldContinue || (() => just(true));
+        const queuePollIntervalMs = (_a = controls.queuePollIntervalMs) !== null && _a !== void 0 ? _a : MULTI_AGENT_QUEUE_POLL_INTERVAL_MS;
         const ignoreMatcher = createAgentIgnoreMatcher(options.ignorePatterns);
+        const isParallelMessageLimitConfigured = options.maxParallelMessages !== undefined;
+        const maxParallelMessageCount = normalizeMaxParallelMessageCount(options.maxParallelMessages);
+        const activeMessageTasksByKey = new Map();
         let githubSynchronizationTimestamp;
         let githubIgnoredRepositoryCount = 0;
         const autoPullTimestampsByProjectPath = new Map();
@@ -37934,7 +38166,7 @@
                 if (!isWatchSessionInitialized) {
                     uiHandle = await initializeMultipleAgentRunUi(options);
                     isWatchSessionInitialized = true;
-                    (_a = controls.onUiInitialized) === null || _a === void 0 ? void 0 : _a.call(controls, uiHandle);
+                    (_b = controls.onUiInitialized) === null || _b === void 0 ? void 0 : _b.call(controls, uiHandle);
                     if (!uiHandle) {
                         console.info(colors__default["default"].green('Watching direct child agent repositories for queued messages.'));
                     }
@@ -37957,14 +38189,19 @@
                 let projectSummaries = projectSummariesResult.projectSummaries;
                 lastObservedProjectCount = projectSummaries.length;
                 let ignoredAgentCount = projectSummariesResult.ignoredProjectCount + githubIgnoredRepositoryCount;
-                const autoPullResult = await pullLatestChangesForLocalAgentRunnerProjectsIfNeeded({
-                    rootPath,
-                    runOptions: options,
-                    uiHandle,
-                    projectSummaries,
-                    ignoredAgentCount,
-                    autoPullTimestampsByProjectPath,
-                });
+                const autoPullResult = activeMessageTasksByKey.size === 0
+                    ? await pullLatestChangesForLocalAgentRunnerProjectsIfNeeded({
+                        rootPath,
+                        runOptions: options,
+                        uiHandle,
+                        projectSummaries,
+                        ignoredAgentCount,
+                        autoPullTimestampsByProjectPath,
+                    })
+                    : {
+                        isAnyRepositoryPulled: false,
+                        pulledProjectPaths: new Set(),
+                    };
                 if (autoPullResult.isAnyRepositoryPulled) {
                     projectSummariesResult = await loadLocalAgentRunnerProjectSummaries(rootPath, {
                         includeMessagePreviews: Boolean(uiHandle),
@@ -37974,61 +38211,49 @@
                     lastObservedProjectCount = projectSummaries.length;
                     ignoredAgentCount = projectSummariesResult.ignoredProjectCount + githubIgnoredRepositoryCount;
                 }
-                const queuedProjects = projectSummaries.filter((projectSummary) => projectSummary.queuedMessageCount > 0);
-                if (queuedProjects.length === 0) {
+                const availableParallelMessageSlots = Math.max(0, maxParallelMessageCount - activeMessageTasksByKey.size);
+                const queuedWorkItems = availableParallelMessageSlots > 0
+                    ? selectQueuedWorkItems({
+                        projectSummaries,
+                        activeMessageTasksByKey,
+                        availableParallelMessageSlots,
+                        isParallelMessageLimitConfigured,
+                    })
+                    : [];
+                const answeringProjectPaths = createAnsweringProjectPaths(activeMessageTasksByKey, queuedWorkItems);
+                if (queuedWorkItems.length === 0 && activeMessageTasksByKey.size === 0) {
                     updateMultipleAgentRunUiForWatching(uiHandle, options, rootPath, projectSummaries, ignoredAgentCount);
-                    await wait$3(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
+                    await wait$3(queuePollIntervalMs);
+                    continue;
+                }
+                if (queuedWorkItems.length === 0) {
+                    updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount, activeMessageTasksByKey.size);
+                    await waitForNextSchedulerTurn(activeMessageTasksByKey, queuePollIntervalMs);
                     continue;
                 }
                 if (!uiHandle) {
-                    for (const queuedProject of queuedProjects) {
-                        console.info(colors__default["default"].blue(`Processing ${formatProjectPath(rootPath, queuedProject.project.projectPath)} with ${queuedProject.localAgentName}.`));
+                    for (const queuedWorkItem of queuedWorkItems) {
+                        console.info(colors__default["default"].blue(`Processing ${formatProjectPath(rootPath, queuedWorkItem.projectSummary.project.projectPath)}/${queuedWorkItem.queuedMessage.relativePath} with ${queuedWorkItem.projectSummary.localAgentName}.`));
                     }
                 }
-                const answeringProjectPaths = new Set(queuedProjects.map((queuedProject) => queuedProject.project.projectPath));
-                if (uiHandle) {
-                    updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount);
-                }
-                const tickResults = await Promise.allSettled(queuedProjects.map(async (queuedProject) => {
-                    const tickRunOptions = createAgentRunOptionsForQueuedProjectTick({
-                        runOptions: options,
-                        isProjectPulledInCurrentIteration: autoPullResult.pulledProjectPaths.has(queuedProject.project.projectPath),
-                    });
-                    const tickResult = await tickAgentMessages(tickRunOptions, {
-                        isQuietWhenIdle: true,
-                        projectPath: queuedProject.project.projectPath,
+                updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount, activeMessageTasksByKey.size + queuedWorkItems.length);
+                for (const queuedWorkItem of queuedWorkItems) {
+                    startActiveAgentMessageTask({
+                        rootPath,
+                        options,
+                        queuedWorkItem,
+                        projectSummaries,
+                        answeringProjectPaths,
+                        ignoredAgentCount,
+                        autoPullResult,
+                        autoPullTimestampsByProjectPath,
+                        activeMessageTasksByKey,
+                        messageFailureTracker,
                         uiHandle,
-                        uiPresentation: uiHandle
-                            ? buildMultiAgentTickUiPresentation({
-                                rootPath,
-                                projectSummaries,
-                                answeringProjectPaths,
-                                ignoredAgentCount,
-                            })
-                            : undefined,
-                    });
-                    return {
-                        projectPath: queuedProject.project.projectPath,
-                        tickResult,
-                    };
-                }));
-                for (const tickResult of tickResults) {
-                    if (tickResult.status === 'fulfilled') {
-                        if (tickResult.value.tickResult.autoPullTimestamp !== undefined) {
-                            autoPullTimestampsByProjectPath.set(tickResult.value.projectPath, tickResult.value.tickResult.autoPullTimestamp);
-                        }
-                        if (tickResult.value.tickResult.isMessageProcessed) {
-                            messageFailureTracker.clearMessageFailure(tickResult.value.projectPath, tickResult.value.tickResult.queuedMessage);
-                        }
-                        continue;
-                    }
-                    await handleAgentWatchError({
-                        commandDisplayName: 'ptbk agent-folder run-multiple',
-                        logDirectoryPath: controls.watchErrorLogDirectoryPath || rootPath,
-                        error: tickResult.reason,
+                        watchErrorLogDirectoryPath: controls.watchErrorLogDirectoryPath || rootPath,
                     });
-                    await messageFailureTracker.recordFailure(tickResult.reason);
                 }
+                await waitForNextSchedulerTurn(activeMessageTasksByKey, queuePollIntervalMs);
             }
             catch (error) {
                 await handleAgentWatchError({
@@ -38037,9 +38262,167 @@
                     error,
                 });
                 await messageFailureTracker.recordFailure(error);
-                await wait$3(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
+                await wait$3(queuePollIntervalMs);
+            }
+        }
+        await waitForActiveMessageTasksToSettle(activeMessageTasksByKey);
+    }
+    /**
+     * Starts one selected queued-message harness task and records it until it settles.
+     */
+    function startActiveAgentMessageTask(options) {
+        const { queuedWorkItem } = options;
+        const projectPath = queuedWorkItem.projectSummary.project.projectPath;
+        const messageKey = createAgentMessageTaskKey(projectPath, queuedWorkItem.queuedMessage);
+        const promise = runActiveAgentMessageTask({
+            rootPath: options.rootPath,
+            options: options.options,
+            queuedWorkItem,
+            projectSummaries: options.projectSummaries,
+            answeringProjectPaths: options.answeringProjectPaths,
+            ignoredAgentCount: options.ignoredAgentCount,
+            autoPullResult: options.autoPullResult,
+            autoPullTimestampsByProjectPath: options.autoPullTimestampsByProjectPath,
+            messageFailureTracker: options.messageFailureTracker,
+            uiHandle: options.uiHandle,
+            watchErrorLogDirectoryPath: options.watchErrorLogDirectoryPath,
+        }).finally(() => {
+            options.activeMessageTasksByKey.delete(messageKey);
+        });
+        options.activeMessageTasksByKey.set(messageKey, {
+            projectPath,
+            queuedMessage: queuedWorkItem.queuedMessage,
+            promise,
+        });
+    }
+    /**
+     * Runs one queued-message tick and folds its result back into shared watcher state.
+     */
+    async function runActiveAgentMessageTask(options) {
+        const projectPath = options.queuedWorkItem.projectSummary.project.projectPath;
+        try {
+            const tickRunOptions = createAgentRunOptionsForQueuedProjectTick({
+                runOptions: options.options,
+                isProjectPulledInCurrentIteration: options.autoPullResult.pulledProjectPaths.has(projectPath),
+            });
+            const tickResult = await tickAgentMessages(tickRunOptions, {
+                isQuietWhenIdle: true,
+                projectPath,
+                queuedMessage: options.queuedWorkItem.queuedMessage,
+                uiHandle: options.uiHandle,
+                uiPresentation: options.uiHandle
+                    ? buildMultiAgentTickUiPresentation({
+                        rootPath: options.rootPath,
+                        projectSummaries: options.projectSummaries,
+                        answeringProjectPaths: options.answeringProjectPaths,
+                        ignoredAgentCount: options.ignoredAgentCount,
+                    })
+                    : undefined,
+            });
+            if (tickResult.autoPullTimestamp !== undefined) {
+                options.autoPullTimestampsByProjectPath.set(projectPath, tickResult.autoPullTimestamp);
+            }
+            if (tickResult.isMessageProcessed) {
+                options.messageFailureTracker.clearMessageFailure(projectPath, tickResult.queuedMessage);
+            }
+        }
+        catch (error) {
+            await handleAgentWatchError({
+                commandDisplayName: 'ptbk agent-folder run-multiple',
+                logDirectoryPath: options.watchErrorLogDirectoryPath,
+                error,
+            });
+            await options.messageFailureTracker.recordFailure(error);
+        }
+    }
+    /**
+     * Selects the next queued messages that can be started without exceeding active harness capacity.
+     */
+    function selectQueuedWorkItems(options) {
+        const activeProjectPaths = new Set(Array.from(options.activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.projectPath));
+        const queuedProjectSummaries = options.projectSummaries.filter((projectSummary) => {
+            if (projectSummary.queuedMessageCount === 0) {
+                return false;
+            }
+            return options.isParallelMessageLimitConfigured || !activeProjectPaths.has(projectSummary.project.projectPath);
+        });
+        if (!options.isParallelMessageLimitConfigured) {
+            return queuedProjectSummaries
+                .map((projectSummary) => selectFirstInactiveQueuedWorkItem(projectSummary, options.activeMessageTasksByKey))
+                .filter((workItem) => workItem !== null);
+        }
+        const workItems = [];
+        for (let messageIndex = 0; workItems.length < options.availableParallelMessageSlots; messageIndex++) {
+            let isAnyMessageAtIndex = false;
+            for (const projectSummary of queuedProjectSummaries) {
+                const queuedMessage = projectSummary.queuedMessages[messageIndex];
+                if (!queuedMessage) {
+                    continue;
+                }
+                isAnyMessageAtIndex = true;
+                if (options.activeMessageTasksByKey.has(createAgentMessageTaskKey(projectSummary.project.projectPath, queuedMessage))) {
+                    continue;
+                }
+                workItems.push({ projectSummary, queuedMessage });
+                if (workItems.length >= options.availableParallelMessageSlots) {
+                    return workItems;
+                }
+            }
+            if (!isAnyMessageAtIndex) {
+                return workItems;
             }
         }
+        return workItems;
+    }
+    /**
+     * Selects the first inactive queued message from a project while preserving legacy one-message-per-project behavior.
+     */
+    function selectFirstInactiveQueuedWorkItem(projectSummary, activeMessageTasksByKey) {
+        const queuedMessage = projectSummary.queuedMessages.find((message) => !activeMessageTasksByKey.has(createAgentMessageTaskKey(projectSummary.project.projectPath, message)));
+        return queuedMessage ? { projectSummary, queuedMessage } : null;
+    }
+    /**
+     * Builds the set of project paths currently represented by active or newly scheduled harness tasks.
+     */
+    function createAnsweringProjectPaths(activeMessageTasksByKey, queuedWorkItems) {
+        return new Set([
+            ...Array.from(activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.projectPath),
+            ...queuedWorkItems.map((queuedWorkItem) => queuedWorkItem.projectSummary.project.projectPath),
+        ]);
+    }
+    /**
+     * Creates a stable scheduler key for one queued message file.
+     */
+    function createAgentMessageTaskKey(projectPath, queuedMessage) {
+        return `${projectPath}\0${queuedMessage.relativePath}`;
+    }
+    /**
+     * Normalizes the maximum number of parallel queued-message tasks.
+     */
+    function normalizeMaxParallelMessageCount(rawValue) {
+        const parsedValue = Number(rawValue);
+        if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+            return Number.POSITIVE_INFINITY;
+        }
+        return Math.floor(parsedValue);
+    }
+    /**
+     * Waits for either one active task to finish or the next queue polling interval.
+     */
+    async function waitForNextSchedulerTurn(activeMessageTasksByKey, queuePollIntervalMs) {
+        if (activeMessageTasksByKey.size === 0) {
+            return;
+        }
+        await Promise.race([
+            ...Array.from(activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.promise),
+            wait$3(queuePollIntervalMs),
+        ]);
+    }
+    /**
+     * Preserves previous shutdown behavior by letting active harness tasks finish before returning.
+     */
+    async function waitForActiveMessageTasksToSettle(activeMessageTasksByKey) {
+        await Promise.allSettled(Array.from(activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.promise));
     }
     /**
      * Creates the shared multi-agent rich UI when the terminal supports it.
@@ -38185,6 +38568,7 @@
                 project,
                 localAgentName: localAgentIdentity.localAgentName,
                 localAgentUrl: localAgentIdentity.localAgentUrl || formatProjectPath(rootPath, project.projectPath),
+                queuedMessages: queueSnapshot.queuedMessages,
                 queuedMessageCount: queueSnapshot.queuedMessages.length,
                 finishedMessageCount: queueSnapshot.finishedMessageCount,
                 ...(queuedMessagePreview ? { queuedMessagePreview } : {}),
@@ -38216,14 +38600,16 @@
     /**
      * Updates the shared UI while one or more child repositories are answering queued messages.
      */
-    function updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount) {
-        const activeProjectCount = projectSummaries.filter((projectSummary) => answeringProjectPaths.has(projectSummary.project.projectPath)).length;
+    function updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount, activeMessageCount) {
+        if (!uiHandle) {
+            return;
+        }
         setMultipleAgentRunUiConfig(uiHandle, options, projectSummaries.length, ignoredAgentCount);
         uiHandle.state.updateProgress(createMultiAgentQueueProgressSnapshot(projectSummaries));
         uiHandle.state.setCurrentPrompt('');
         uiHandle.state.setCurrentScriptPaths(buildMultiAgentScriptPaths(projectSummaries, answeringProjectPaths));
         uiHandle.state.setPhase('running');
-        uiHandle.state.setStatusMessage(`Answering ${activeProjectCount} queued message${activeProjectCount === 1 ? '' : 's'}`);
+        uiHandle.state.setStatusMessage(`Answering ${activeMessageCount} queued message${activeMessageCount === 1 ? '' : 's'}`);
         uiHandle.state.setDetailLines(buildMultiAgentAnsweringDetailLines(rootPath, projectSummaries, answeringProjectPaths));
         uiHandle.state.setAgentStatusLines(buildMultiAgentStatusLines(rootPath, projectSummaries, answeringProjectPaths));
         uiHandle.state.setAgentStatusTableRows(buildMultiAgentStatusTableRows(projectSummaries, answeringProjectPaths));
@@ -38525,6 +38911,12 @@
      * @private shared Agents Server constant
      */
     const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
+    /**
+     * Default maximum number of local runner harness instances allowed to answer queued messages at once.
+     *
+     * @private shared Agents Server constant
+     */
+    const DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES = 3;
     /**
      * Stable keys used by the dedicated server-limits table.
      *
@@ -38539,6 +38931,7 @@
         SPAWN_AGENT_RATE_LIMIT_MAX: 'SPAWN_AGENT_RATE_LIMIT_MAX',
         SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: 'SPAWN_AGENT_RATE_LIMIT_WINDOW_MS',
         LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS: 'LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS',
+        LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES: 'LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES',
     };
     /**
      * Shared metadata for all server limits exposed in the admin UI and runtime loaders.
@@ -38634,6 +39027,17 @@
             step: 1,
             legacyMetadataKeys: [],
         },
+        {
+            key: SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+            category: 'Local agent runner',
+            title: 'Max parallel harness instances',
+            description: 'Caps how many queued chat messages the local coding-agent harness may answer at the same time.',
+            unit: 'count',
+            defaultValue: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [],
+        },
     ];
     /**
      * Fast lookup map used by server-limit validators and UI helpers.
@@ -38995,6 +39399,7 @@
             autoPull: false,
             autoClone: false,
             maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
+            maxParallelMessages: localAgentRunnerLimits.maxParallelMessages,
         };
     }
     /**
@@ -39006,7 +39411,7 @@
         while (options.state.isContinuing && Date.now() - startedAt < INTERNAL_SERVER_LIMITS_STARTUP_TIMEOUT_MS) {
             try {
                 const limits = await fetchLocalAgentRunnerLimits(options);
-                logRunnerEvent(options.logStreams.runner, `Local agent runner max failed attempts: ${limits.maxFailedAttempts}.`);
+                logRunnerEvent(options.logStreams.runner, `Local agent runner limits: ${limits.maxFailedAttempts} failed attempt(s), ${limits.maxParallelMessages} parallel message(s).`);
                 return limits;
             }
             catch (error) {
@@ -39017,6 +39422,7 @@
         if (!options.state.isContinuing) {
             return {
                 maxFailedAttempts: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+                maxParallelMessages: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
             };
         }
         throw new NotAllowed(_spaceTrim.spaceTrim(`
@@ -39043,6 +39449,7 @@
         const payload = (await response.json());
         return {
             maxFailedAttempts: normalizeLocalAgentRunnerMaxFailedAttempts(payload.maxFailedAttempts),
+            maxParallelMessages: normalizeLocalAgentRunnerMaxParallelMessages(payload.maxParallelMessages),
         };
     }
     /**
@@ -39055,6 +39462,16 @@
         }
         return Math.floor(parsedValue);
     }
+    /**
+     * Normalizes the local runner parallel message cap returned by the internal server route.
+     */
+    function normalizeLocalAgentRunnerMaxParallelMessages(rawValue) {
+        const parsedValue = Number(rawValue);
+        if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+            return DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES;
+        }
+        return Math.floor(parsedValue);
+    }
     /**
      * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
      */
@@ -40309,7 +40726,7 @@
      */
     const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
         'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
-        'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+        'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
         // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
         'coder:verify': 'ptbk coder verify',
     };
@@ -40789,6 +41206,7 @@
         command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
         addPromptRunnerExecutionOptions(command);
         command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption$1, 0);
+        command.option('--limit <run-count>', 'Stop after processing this many prompt runs', parsePositiveIntegerOption);
         command.option('--wait-after-prompt <duration>', _spaceTrim.spaceTrim(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
             Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
@@ -40807,7 +41225,7 @@
         command.option('--auto-migrate', 'Run testing-server database migrations automatically after each successfully processed prompt');
         command.option('--allow-destructive-auto-migrate', 'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations');
         command.action(handleActionErrors(async (cliOptions) => {
-            const { dryRun, agent, context, test, preserveLogs, priority, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+            const { dryRun, agent, context, test, preserveLogs, priority, limit, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
             const testCommand = normalizeCommandOptionValue$1(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
@@ -40840,6 +41258,7 @@
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 priority,
+                limit,
                 normalizeLineEndings: runnerOptions.normalizeLineEndings,
                 allowCredits: runnerOptions.allowCredits,
                 autoMigrate,
@@ -40874,6 +41293,22 @@
         }
         return parsed;
     }
+    /**
+     * Parses a positive integer option value.
+     *
+     * @private internal utility of `coder run` command
+     */
+    function parsePositiveIntegerOption(value) {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            throw new NotAllowed(_spaceTrim.spaceTrim(`
+                Invalid value for \`--limit\`: \`${value}\`.
+
+                Use a positive integer.
+            `));
+        }
+        return parsed;
+    }
     /**
      * Joins one Commander option that may be parsed either as a single string or a variadic token array.
      *
@@ -70289,7 +70724,7 @@
     /**
      * CLI usage text for this script.
      */
-    const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--preserve-logs] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+    const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--preserve-logs] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
     /**
      * Top-level flags supported by this command.
      */
@@ -70303,6 +70738,7 @@
         '--no-ui',
         '--thinking-level',
         '--priority',
+        '--limit',
         '--allow-credits',
         '--auto-migrate',
         '--allow-destructive-auto-migrate',
@@ -70339,6 +70775,8 @@
         const thinkingLevelValue = readOptionValue(args, '--thinking-level');
         const hasPriorityFlag = args.includes('--priority');
         const priority = parsePriority(readOptionValue(args, '--priority'), hasPriorityFlag);
+        const hasLimitFlag = args.includes('--limit');
+        const limit = parseLimit(readOptionValue(args, '--limit'), hasLimitFlag);
         const noCommit = args.includes('--no-commit');
         const ignoreGitChanges = args.includes('--ignore-git-changes');
         const normalizeLineEndings = !args.includes('--no-normalize-line-endings');
@@ -70393,6 +70831,7 @@
             testCommand,
             thinkingLevel,
             priority,
+            limit,
         };
     }
     /**
@@ -70456,6 +70895,22 @@
         }
         return priority;
     }
+    /**
+     * Parses and validates the optional successful prompt-run limit.
+     */
+    function parseLimit(limitValue, hasLimitFlag) {
+        if (limitValue === undefined) {
+            if (hasLimitFlag) {
+                exitWithUsageError('Missing value for --limit. Use a positive integer.');
+            }
+            return undefined;
+        }
+        const limit = Number(limitValue);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            exitWithUsageError(`Invalid value for --limit: "${limitValue}". Use a positive integer.`);
+        }
+        return limit;
+    }
     /**
      * Prints an argument error with usage and exits the process.
      */
@@ -72565,11 +73020,12 @@
         // Prepend agent system message before the task so the harness sees agent instructions first
         const promptWithAgent = resolvedAgentSystemMessage
             ? _spaceTrim.spaceTrim((block) => `
-                  ${block(resolvedAgentSystemMessage.trim())}
-
+                  
                   ## Your Task
 
                   ${block(taskPrompt)}
+
+                  ${block(resolvedAgentSystemMessage.trim())}
               `)
             : taskPrompt;
         const codexPrompt = appendCoderContext(promptWithAgent, resolvedCoderContext);
@@ -72892,6 +73348,7 @@
             let hasWaitedForStart = false;
             let previousRoundStartTime;
             let previousRoundEndTime;
+            let completedRunCount = 0;
             while (just(true)) {
                 if (options.autoPull && !options.dryRun) {
                     await waitForRequestedPause({
@@ -72977,6 +73434,15 @@
                 });
                 previousRoundStartTime = currentRoundStartTime;
                 previousRoundEndTime = Date.now();
+                completedRunCount += 1;
+                if (isRunLimitReached({ completedRunCount, limit: options.limit })) {
+                    finishWhenRunLimitIsReached({
+                        completedRunCount,
+                        isRichUiEnabled,
+                        uiHandle,
+                    });
+                    return;
+                }
             }
         }
         finally {
@@ -73006,6 +73472,13 @@
                 Auto-pull keeps the repository up to date between prompt rounds, which requires each successful round to end with a clean committed working tree.
             `));
         }
+        if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+            throw new NotAllowed(_spaceTrim.spaceTrim(`
+                Flag \`--limit\` expects a positive integer.
+
+                Received: \`${options.limit}\`
+            `));
+        }
     }
     /**
      * Pulls the latest repository state before loading prompts when the feature is enabled.
@@ -73152,6 +73625,21 @@
         }
         return true;
     }
+    /**
+     * Checks whether the configured successful prompt-run limit has been reached.
+     */
+    function isRunLimitReached(options) {
+        const { completedRunCount, limit } = options;
+        return limit !== undefined && completedRunCount >= limit;
+    }
+    /**
+     * Updates UI and console output when a user-configured run limit stops the loop.
+     */
+    function finishWhenRunLimitIsReached(options) {
+        const { completedRunCount, isRichUiEnabled, uiHandle } = options;
+        const runCountLabel = completedRunCount === 1 ? '1 prompt run' : `${completedRunCount} prompt runs`;
+        announceRunCompletion(`Run limit reached after ${runCountLabel}.`, colors__default["default"].green, isRichUiEnabled, uiHandle);
+    }
     /**
      * Updates the UI status message while waiting for new prompts in keepAlive server mode.
      */