@promptbook/cli 0.112.0-103 → 0.112.0-105

package/src/book-components/BookEditor/BookEditor.tsx

@@ -17,6 +17,8 @@ import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContex
 import { classNames } from '../_common/react-utils/classNames';
 import styles from './BookEditor.module.css';
 import { BookEditorMonaco } from './BookEditorMonaco';
+import type { BookEditorTheme } from './BookEditorTheme';
+import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
 
 /**
  * Monaco diagnostic shown inside `BookEditor`.
@@ -123,14 +125,14 @@ export type BookEditorProps = {
     readonly style?: CSSProperties;
 
     /**
-     * Resolved visual theme used for the editor wrapper and Monaco instance.
+     * Resolved host application theme.
      *
-     * Host applications should pass the final light/dark theme instead of relying on
-     * browser media-query inference inside `<BookEditor/>`.
+     * `<BookEditor/>` accepts this for integration compatibility, but the notebook
+     * editor itself is intentionally rendered as light paper in every app theme.
      *
      * @default 'LIGHT'
      */
-    readonly theme?: 'LIGHT' | 'DARK';
+    readonly theme?: BookEditorTheme;
 
     /**
      * Height of the `BookEditor` component
@@ -288,7 +290,7 @@ export function BookEditor(props: BookEditorProps) {
         agentSource,
         className,
         style,
-        theme = 'LIGHT',
+        theme: hostTheme = BOOK_EDITOR_RENDER_THEME,
         zoom = 1,
         value,
         onChange,
@@ -309,6 +311,7 @@ export function BookEditor(props: BookEditorProps) {
     } = props;
 
     const [isFullscreen, setIsFullscreen] = useState(false);
+    const renderedTheme = resolveBookEditorRenderTheme(hostTheme);
 
     /**
      * Toggles fullscreen mode for the editor.
@@ -320,7 +323,7 @@ export function BookEditor(props: BookEditorProps) {
     const editorContent = (
         <div
             data-book-component="BookEditor"
-            data-book-editor-theme={theme.toLowerCase()}
+            data-book-editor-theme={renderedTheme.toLowerCase()}
             className={classNames(
                 styles.BookEditor,
                 isVerbose && styles.isVerbose,
@@ -365,7 +368,7 @@ export function BookEditor(props: BookEditorProps) {
                 zoom={zoom}
                 monacoModelPath={monacoModelPath}
                 hoistedMenuItems={hoistedMenuItems}
-                theme={theme}
+                theme={renderedTheme}
             />
         </div>
     );

package/src/book-components/BookEditor/BookEditorMonaco.tsx

@@ -12,6 +12,7 @@ import type { BookEditorProps } from './BookEditor';
 import styles from './BookEditor.module.css';
 import { BookEditorActionbar } from './BookEditorActionbar';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
+import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
 import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics';
 import { useBookEditorMonacoDecorations } from './useBookEditorMonacoDecorations';
 import { useBookEditorMonacoDiagnostics } from './useBookEditorMonacoDiagnostics';
@@ -204,7 +205,7 @@ export function BookEditorMonaco(props: BookEditorProps) {
         onChange,
         diagnostics,
         isReadonly,
-        theme = 'LIGHT',
+        theme: hostTheme = BOOK_EDITOR_RENDER_THEME,
         translations,
         onFileUpload,
         isUploadButtonShown,
@@ -219,6 +220,7 @@ export function BookEditorMonaco(props: BookEditorProps) {
         hoistedMenuItems,
     } = props;
 
+    const theme = resolveBookEditorRenderTheme(hostTheme);
     const zoomLevel = zoom;
     const { scaledLineHeight, scaledContentPaddingLeft, scaledVerticalLineLeft, scaledFontSize, scaledScrollbarSize } =
         createBookEditorMonacoScale(zoomLevel);

package/src/book-components/BookEditor/BookEditorTheme.ts

@@ -0,0 +1,32 @@
+/**
+ * Visual theme accepted by `<BookEditor/>` integrations.
+ *
+ * @private internal type of `BookEditor`
+ */
+export type BookEditorTheme = 'LIGHT' | 'DARK';
+
+/**
+ * Theme used for the actual notebook editor surface.
+ *
+ * The host application can still pass its resolved app theme, but book sources
+ * are intentionally rendered as light paper in both light and dark app modes.
+ *
+ * @private internal constant of `BookEditor`
+ */
+export const BOOK_EDITOR_RENDER_THEME = 'LIGHT' satisfies BookEditorTheme;
+
+/**
+ * Resolves an app-level theme into the visual theme used by `<BookEditor/>`.
+ *
+ * @param hostTheme - Resolved theme from the embedding application.
+ * @returns Light theme used by the Book editor surface.
+ *
+ * @private internal utility of `BookEditor`
+ */
+export function resolveBookEditorRenderTheme(hostTheme: BookEditorTheme = BOOK_EDITOR_RENDER_THEME): BookEditorTheme {
+    if (hostTheme === 'DARK') {
+        return BOOK_EDITOR_RENDER_THEME;
+    }
+
+    return hostTheme;
+}

package/src/book-components/BookEditor/useBookEditorMonacoLanguage.ts

@@ -8,19 +8,14 @@ import {
 import { PROMPTBOOK_SYNTAX_COLORS } from '../../config';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
 import { BookEditorMonacoTokenization } from './BookEditorMonacoTokenization';
+import type { BookEditorTheme } from './BookEditorTheme';
+import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
 
 /**
  * Type describing monaco editor.
  */
 type MonacoEditor = typeof import('monaco-editor');
 
-/**
- * Resolved visual theme supported by the Book editor.
- *
- * @private function of BookEditorMonaco
- */
-type BookEditorTheme = 'LIGHT' | 'DARK';
-
 /**
  * Props for use book editor monaco language.
  */
@@ -286,12 +281,13 @@ function createNoteLikeBodyRules(
  *
  * @private function of BookEditorMonaco
  */
-export function ensureBookEditorMonacoLanguage(monaco: MonacoEditor, theme: BookEditorTheme = 'LIGHT'): void {
+export function ensureBookEditorMonacoLanguage(monaco: MonacoEditor, theme: BookEditorTheme = BOOK_EDITOR_RENDER_THEME): void {
+    const renderedTheme = resolveBookEditorRenderTheme(theme);
     const monacoWithLanguageState = monaco as MonacoEditorWithBookEditorLanguageState;
     if (monacoWithLanguageState[BOOK_EDITOR_LANGUAGE_INITIALIZED_FLAG]) {
-        if (monacoWithLanguageState[BOOK_EDITOR_THEME_MODE_FLAG] !== theme) {
-            applyBookEditorMonacoTheme(monaco, theme);
-            monacoWithLanguageState[BOOK_EDITOR_THEME_MODE_FLAG] = theme;
+        if (monacoWithLanguageState[BOOK_EDITOR_THEME_MODE_FLAG] !== renderedTheme) {
+            applyBookEditorMonacoTheme(monaco, renderedTheme);
+            monacoWithLanguageState[BOOK_EDITOR_THEME_MODE_FLAG] = renderedTheme;
             return;
         }
 
@@ -300,7 +296,7 @@ export function ensureBookEditorMonacoLanguage(monaco: MonacoEditor, theme: Book
     }
 
     monacoWithLanguageState[BOOK_EDITOR_LANGUAGE_INITIALIZED_FLAG] = true;
-    monacoWithLanguageState[BOOK_EDITOR_THEME_MODE_FLAG] = theme;
+    monacoWithLanguageState[BOOK_EDITOR_THEME_MODE_FLAG] = renderedTheme;
 
     monaco.languages.register({ id: BookEditorMonacoConstants.BOOK_LANGUAGE_ID });
 
@@ -437,7 +433,7 @@ export function ensureBookEditorMonacoLanguage(monaco: MonacoEditor, theme: Book
         },
     });
 
-    applyBookEditorMonacoTheme(monaco, theme);
+    applyBookEditorMonacoTheme(monaco, renderedTheme);
 }
 
 /**
@@ -462,8 +458,9 @@ type EnsureBookEditorMonacoLanguageForEditorProps = {
  * @private function of BookEditorMonaco
  */
 export function ensureBookEditorMonacoLanguageForEditor(props: EnsureBookEditorMonacoLanguageForEditorProps): void {
-    const { monaco, monacoEditor, theme = 'LIGHT' } = props;
-    ensureBookEditorMonacoLanguage(monaco, theme);
+    const { monaco, monacoEditor, theme = BOOK_EDITOR_RENDER_THEME } = props;
+    const renderedTheme = resolveBookEditorRenderTheme(theme);
+    ensureBookEditorMonacoLanguage(monaco, renderedTheme);
 
     const model = monacoEditor.getModel();
     if (!model) {

package/src/book-components/BookEditor/useBookEditorMonacoLifecycle.ts

@@ -1,5 +1,6 @@
 import type { editor } from 'monaco-editor';
 import { useCallback, useEffect, useState } from 'react';
+import type { BookEditorTheme } from './BookEditorTheme';
 import { ensureBookEditorMonacoLanguage, ensureBookEditorMonacoLanguageForEditor } from './useBookEditorMonacoLanguage';
 
 /**
@@ -7,11 +8,6 @@ import { ensureBookEditorMonacoLanguage, ensureBookEditorMonacoLanguageForEditor
  */
 type MonacoEditor = typeof import('monaco-editor');
 
-/**
- * Resolved visual theme supported by the Book editor.
- */
-type BookEditorTheme = 'LIGHT' | 'DARK';
-
 /**
  * Props for use book editor monaco lifecycle.
  */

package/src/book-components/BookEditor/useBookEditorMonacoStyles.ts

@@ -1,5 +1,6 @@
 import { useEffect } from 'react';
 import { PROMPTBOOK_SYNTAX_COLORS } from '../../config';
+import type { BookEditorTheme } from './BookEditorTheme';
 
 /**
  * Relative Y offset multiplier for aligning line background with Monaco rendering.
@@ -17,7 +18,7 @@ type UseBookEditorMonacoStylesProps = {
     readonly scaledContentPaddingLeft: number;
     readonly scaledVerticalLineLeft: number;
     readonly zoomLevel: number;
-    readonly theme: 'LIGHT' | 'DARK';
+    readonly theme: BookEditorTheme;
 };
 
 /**

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

@@ -36,6 +36,13 @@ export const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTOR
  */
 export const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'finished');
 
+/**
+ * Relative path to messages that the agent runner stopped retrying.
+ *
+ * @private internal utility of `ptbk agent-folder`
+ */
+export const AGENT_FAILED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'failed');
+
 /**
  * Relative path to generated local agent documentation initialized by `ptbk agent-folder init`.
  *

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

@@ -96,12 +96,41 @@ const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES = new Set([
     'test-results',
 ]);
 
+/**
+ * Runtime source files excluded from the packaged Agents Server copy.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATHS = new Set([
+    'src/_packages/browser.index.ts',
+    'src/_packages/browser.readme.md',
+    'src/llm-providers/_common/register/$provideLlmToolsForTestingAndScriptsAndPlayground.ts',
+    'src/llm-providers/_common/utils/assertUniqueModels.ts',
+]);
+
+/**
+ * Runtime source folders excluded from the packaged Agents Server copy.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATH_PREFIXES = [
+    'src/dialogs/simple-prompt',
+    'src/storage/local-storage',
+] as const;
+
 /**
  * Test files copied out of packaged runtime input paths because Next does not build them.
  *
  * @private internal constant of `ptbk agents-server`
  */
-const AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN = /\.(?:spec|test)\.[jt]sx?$/iu;
+const AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN = /\.(?:spec|test)(?:\.|$)/iu;
+
+/**
+ * Type-only compile check files copied out of packaged runtime input paths.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN = /\.test-type\.[jt]sx?$/iu;
 
 /**
  * Metadata persisted after one successful Agents Server production build.
@@ -410,6 +439,7 @@ async function copyAgentsServerRuntimePath(options: {
  */
 function shouldCopyAgentsServerRuntimePath(sourcePath: string, sourceRootPath: string): boolean {
     const sourceRelativePath = relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+    const sourceRuntimeRelativePath = normalizeRuntimeSourceRelativePath(sourcePath, sourceRootPath);
     const sourcePathSegments = sourceRelativePath.split('/').filter(Boolean);
     const sourceBasename = basename(sourcePath);
 
@@ -421,11 +451,58 @@ function shouldCopyAgentsServerRuntimePath(sourcePath: string, sourceRootPath: s
         return false;
     }
 
+    if (sourcePathSegments.includes('playground')) {
+        return false;
+    }
+
+    if (isExcludedAgentsServerRuntimeSourcePath(sourceRuntimeRelativePath)) {
+        return false;
+    }
+
     if (sourceBasename.startsWith('.env')) {
         return false;
     }
 
-    return !AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(sourceBasename);
+    return (
+        !AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(sourceBasename) &&
+        !AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN.test(sourceBasename)
+    );
+}
+
+/**
+ * Normalizes a copied runtime path to the shape used inside the packaged runtime root.
+ */
+function normalizeRuntimeSourceRelativePath(sourcePath: string, sourceRootPath: string): string {
+    const sourceRelativePath = relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+    const sourceRootBasename = basename(sourceRootPath);
+
+    if (!sourceRelativePath) {
+        return sourceRootBasename;
+    }
+
+    return `${sourceRootBasename}/${sourceRelativePath}`;
+}
+
+/**
+ * Checks whether one normalized runtime path is equal to or nested below another path.
+ */
+function isRuntimePathWithin(sourceRuntimeRelativePath: string, excludedSourcePathPrefix: string): boolean {
+    return (
+        sourceRuntimeRelativePath === excludedSourcePathPrefix ||
+        sourceRuntimeRelativePath.startsWith(`${excludedSourcePathPrefix}/`)
+    );
+}
+
+/**
+ * Returns true for runtime source files and folders that are not needed by the Agents Server build.
+ */
+function isExcludedAgentsServerRuntimeSourcePath(sourceRuntimeRelativePath: string): boolean {
+    return (
+        AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATHS.has(sourceRuntimeRelativePath) ||
+        AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATH_PREFIXES.some((excludedSourcePathPrefix) =>
+            isRuntimePathWithin(sourceRuntimeRelativePath, excludedSourcePathPrefix),
+        )
+    );
 }
 
 /**
@@ -595,6 +672,10 @@ async function addAgentsServerBuildInputToFingerprint(
         readonly runtimeRootPath: string;
     },
 ): Promise<void> {
+    if (isExcludedAgentsServerBuildInputPath(options.inputPath, options.runtimeRootPath)) {
+        return;
+    }
+
     let inputStats;
 
     try {
@@ -605,10 +686,6 @@ async function addAgentsServerBuildInputToFingerprint(
     }
 
     if (inputStats.isFile()) {
-        if (isExcludedAgentsServerBuildInputFile(options.inputPath)) {
-            return;
-        }
-
         fingerprint.update(`file:${normalizeBuildInputPath(options.runtimeRootPath, options.inputPath)}\n`);
         fingerprint.update(await readFile(options.inputPath));
         fingerprint.update('\n');
@@ -636,10 +713,33 @@ async function addAgentsServerBuildInputToFingerprint(
 }
 
 /**
- * Returns true for non-build test files inside shared runtime source paths.
+ * Returns true for non-build files and folders inside shared runtime source paths.
  */
-function isExcludedAgentsServerBuildInputFile(inputPath: string): boolean {
-    return AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(basename(inputPath));
+function isExcludedAgentsServerBuildInputPath(inputPath: string, runtimeRootPath: string): boolean {
+    const inputRelativePath = normalizeBuildInputPath(runtimeRootPath, inputPath);
+    const inputPathSegments = inputRelativePath.split('/').filter(Boolean);
+    const inputBasename = basename(inputPath);
+
+    if (
+        inputPathSegments.some((inputPathSegment) =>
+            AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES.has(inputPathSegment),
+        )
+    ) {
+        return true;
+    }
+
+    if (inputPathSegments.includes('playground')) {
+        return true;
+    }
+
+    if (isExcludedAgentsServerRuntimeSourcePath(inputRelativePath)) {
+        return true;
+    }
+
+    return (
+        AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(inputBasename) ||
+        AGENTS_SERVER_BUILD_INPUT_TEST_TYPE_FILE_PATTERN.test(inputBasename)
+    );
 }
 
 /**

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

@@ -19,6 +19,7 @@ import {
     ensureAgentsServerBuild,
     resolveAgentsServerAppPath,
 } from './buildAgentsServer';
+import { DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS } from '../../../../apps/agents-server/src/constants/serverLimits';
 
 /**
  * Local worker-pump delay while the Agents Server foreground process stays active.
@@ -41,6 +42,20 @@ const USER_CHAT_JOB_WORKER_REPEATED_ERROR_LOG_INTERVAL = 10;
  */
 const USER_CHAT_JOB_WORKER_ERROR_BODY_MAX_LENGTH = 2_000;
 
+/**
+ * Delay between foreground CLI attempts to load internal Agents Server limits during startup.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const INTERNAL_SERVER_LIMITS_RETRY_DELAY_MS = 1_000;
+
+/**
+ * Maximum time spent waiting for the internal limits route before startup fails.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const INTERNAL_SERVER_LIMITS_STARTUP_TIMEOUT_MS = 60_000;
+
 /**
  * HTTP status used by an idle internal worker tick with no job to process.
  *
@@ -163,6 +178,15 @@ type AgentsServerSupervisorState = {
     };
 };
 
+/**
+ * Local runner limits loaded from the running Agents Server app.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+};
+
 /**
  * Starts the Agents Server web app and local coding-agent queue workers in the foreground.
  *
@@ -229,6 +253,12 @@ export async function startAgentsServer(options: StartAgentsServerOptions): Prom
             logStreams,
             state,
         });
+        const localAgentRunnerLimits = await waitForLocalAgentRunnerLimits({
+            port: options.port,
+            environment: runtimeChildEnvironment,
+            logStreams,
+            state,
+        });
         stopUserChatJobWorkerPump = startUserChatJobWorkerPump({
             port: options.port,
             environment: runtimeChildEnvironment,
@@ -237,7 +267,7 @@ export async function startAgentsServer(options: StartAgentsServerOptions): Prom
         });
 
         await withCurrentWorkingDirectory(runtimePaths.agentRootPath, async () => {
-            await runMultipleAgentMessages(createLocalAgentRunOptions(options), {
+            await runMultipleAgentMessages(createLocalAgentRunOptions(options, localAgentRunnerLimits), {
                 shouldContinue: () => state.isContinuing,
                 watchErrorLogDirectoryPath: runtimePaths.logDirectoryPath,
                 onUiInitialized: (uiHandle) => {
@@ -409,7 +439,10 @@ function createAgentsServerChildEnvironment(port: number_port, agentRootPath: st
 /**
  * Creates local no-git agent runner options for folders managed by the Agents Server database.
  */
-function createLocalAgentRunOptions(options: StartAgentsServerOptions): AgentRunOptions {
+function createLocalAgentRunOptions(
+    options: StartAgentsServerOptions,
+    localAgentRunnerLimits: LocalAgentRunnerLimits,
+): AgentRunOptions {
     return {
         agentName: options.agentName,
         model: options.model,
@@ -422,9 +455,90 @@ function createLocalAgentRunOptions(options: StartAgentsServerOptions): AgentRun
         autoPush: false,
         autoPull: false,
         autoClone: false,
+        maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
+    };
+}
+
+/**
+ * Waits until the internal Next route can return current local runner limits.
+ */
+async function waitForLocalAgentRunnerLimits(options: {
+    readonly port: number_port;
+    readonly environment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly state: AgentsServerSupervisorState;
+}): Promise<LocalAgentRunnerLimits> {
+    const startedAt = Date.now();
+    let lastError: unknown;
+
+    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}.`,
+            );
+            return limits;
+        } catch (error) {
+            lastError = error;
+            await wait(INTERNAL_SERVER_LIMITS_RETRY_DELAY_MS);
+        }
+    }
+
+    if (!options.state.isContinuing) {
+        return {
+            maxFailedAttempts: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+        };
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Failed to load local agent runner limits from the Agents Server.
+
+            ${lastError instanceof Error ? lastError.message : String(lastError)}
+        `),
+    );
+}
+
+/**
+ * Loads local runner limits through the token-protected internal Agents Server route.
+ */
+async function fetchLocalAgentRunnerLimits(options: {
+    readonly port: number_port;
+    readonly environment: AgentsServerChildEnvironment;
+}): Promise<LocalAgentRunnerLimits> {
+    const response = await fetch(`http://localhost:${options.port}/api/internal/agent-runner-limits`, {
+        method: 'GET',
+        cache: 'no-store',
+        headers: {
+            'x-user-chat-worker-token': options.environment.PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN,
+        },
+    });
+
+    if (!response.ok) {
+        const details = await readUserChatJobWorkerErrorDetails(response);
+        throw new Error(createInternalRouteErrorMessage('agent runner limits', response, details));
+    }
+
+    const payload = (await response.json()) as Partial<LocalAgentRunnerLimits>;
+    return {
+        maxFailedAttempts: normalizeLocalAgentRunnerMaxFailedAttempts(payload.maxFailedAttempts),
     };
 }
 
+/**
+ * Normalizes the local runner retry cap returned by the internal server route.
+ */
+function normalizeLocalAgentRunnerMaxFailedAttempts(rawValue: unknown): number {
+    const parsedValue = Number(rawValue);
+
+    if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+        return DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS;
+    }
+
+    return Math.floor(parsedValue);
+}
+
 /**
  * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
  */
@@ -563,14 +677,21 @@ function parseUserChatJobWorkerErrorMessage(body: string): string | null {
  * Builds the foreground worker failure message from HTTP status and route details.
  */
 function createUserChatJobWorkerErrorMessage(response: Response, details: string | null): string {
+    return createInternalRouteErrorMessage('user chat worker', response, details);
+}
+
+/**
+ * Builds a foreground failure message for one internal Agents Server route.
+ */
+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 user chat worker returned ${statusMessage}.`;
+        return `Internal ${routeLabel} route returned ${statusMessage}.`;
     }
 
-    return `Internal user chat worker returned ${statusMessage}: ${details}`;
+    return `Internal ${routeLabel} route returned ${statusMessage}: ${details}`;
 }
 
 /**
@@ -652,4 +773,11 @@ function stopChildProcess(commandProcess: ChildProcess | undefined): void {
     commandProcess.kill();
 }
 
+/**
+ * Waits for the given delay.
+ */
+async function wait(delayMs: number): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
 // Note: [🟡] Code for CLI runtime [startAgentsServer](src/cli/cli-commands/agents-server/startAgentsServer.ts) should never be published outside of `@promptbook/cli`