@promptbook/cli 0.112.0-104 → 0.112.0-105

package/umd/index.umd.js

@@ -60,7 +60,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-104';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-105';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1750,6 +1750,12 @@
      * @private internal utility of `ptbk agent-folder`
      */
     const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH = path.join(AGENT_MESSAGES_DIRECTORY_PATH, 'finished');
+    /**
+     * Relative path to messages that the agent runner stopped retrying.
+     *
+     * @private internal utility of `ptbk agent-folder`
+     */
+    const AGENT_FAILED_MESSAGES_DIRECTORY_PATH = path.join(AGENT_MESSAGES_DIRECTORY_PATH, 'failed');
     /**
      * Relative path to generated local agent documentation initialized by `ptbk agent-folder init`.
      *
@@ -3160,12 +3166,38 @@
         'playwright-report',
         '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',
+    ];
     /**
      * 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;
     /**
      * Ensures that the local Agents Server production build exists and matches its source fingerprint.
      *
@@ -3360,15 +3392,48 @@
      */
     function shouldCopyAgentsServerRuntimePath(sourcePath, sourceRootPath) {
         const sourceRelativePath = path.relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+        const sourceRuntimeRelativePath = normalizeRuntimeSourceRelativePath(sourcePath, sourceRootPath);
         const sourcePathSegments = sourceRelativePath.split('/').filter(Boolean);
         const sourceBasename = path.basename(sourcePath);
         if (sourcePathSegments.some((sourcePathSegment) => AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES.has(sourcePathSegment))) {
             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, sourceRootPath) {
+        const sourceRelativePath = path.relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+        const sourceRootBasename = path.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, excludedSourcePathPrefix) {
+        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) {
+        return (AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATHS.has(sourceRuntimeRelativePath) ||
+            AGENTS_SERVER_BUILD_INPUT_EXCLUDED_SOURCE_PATH_PREFIXES.some((excludedSourcePathPrefix) => isRuntimePathWithin(sourceRuntimeRelativePath, excludedSourcePathPrefix)));
     }
     /**
      * Links the materialized runtime back to the package dependency tree used by the installed CLI.
@@ -3486,6 +3551,9 @@
      * Adds one runtime source file or directory subtree to the production build fingerprint.
      */
     async function addAgentsServerBuildInputToFingerprint(fingerprint, options) {
+        if (isExcludedAgentsServerBuildInputPath(options.inputPath, options.runtimeRootPath)) {
+            return;
+        }
         let inputStats;
         try {
             inputStats = await promises.stat(options.inputPath);
@@ -3495,9 +3563,6 @@
             return;
         }
         if (inputStats.isFile()) {
-            if (isExcludedAgentsServerBuildInputFile(options.inputPath)) {
-                return;
-            }
             fingerprint.update(`file:${normalizeBuildInputPath(options.runtimeRootPath, options.inputPath)}\n`);
             fingerprint.update(await promises.readFile(options.inputPath));
             fingerprint.update('\n');
@@ -3520,10 +3585,23 @@
         }
     }
     /**
-     * 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) {
-        return AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(path.basename(inputPath));
+    function isExcludedAgentsServerBuildInputPath(inputPath, runtimeRootPath) {
+        const inputRelativePath = normalizeBuildInputPath(runtimeRootPath, inputPath);
+        const inputPathSegments = inputRelativePath.split('/').filter(Boolean);
+        const inputBasename = path.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));
     }
     /**
      * Normalizes one absolute runtime path so cache fingerprints are stable across platforms.
@@ -4944,7 +5022,7 @@
             .filter((entry) => entry.isFile() && isBookFileName(entry.name))
             .map((entry) => ({
             absolutePath: path.join(queuedMessagesDirectoryPath, entry.name),
-            relativePath: normalizeRelativePath$1(path.join(AGENT_QUEUED_MESSAGES_DIRECTORY_PATH, entry.name)),
+            relativePath: normalizeRelativePath$2(path.join(AGENT_QUEUED_MESSAGES_DIRECTORY_PATH, entry.name)),
             fileName: entry.name,
         }))
             .sort((firstMessage, secondMessage) => firstMessage.fileName.localeCompare(secondMessage.fileName));
@@ -4972,7 +5050,7 @@
     /**
      * Normalizes a relative path for Markdown links and Git path matching.
      */
-    function normalizeRelativePath$1(relativePath) {
+    function normalizeRelativePath$2(relativePath) {
         return relativePath.replace(/\\/gu, '/');
     }
     /**
@@ -13350,10 +13428,7 @@
             Math.max(0, Math.cos(effectiveLongitude)) * 0.1 +
             lowerBlend * tentacleInfluence.core * (0.1 + tentacleInfluence.depthScale * 0.06) -
             Math.max(0, -Math.cos(effectiveLongitude)) * 0.05;
-        const tentacleTubeRadius = lowerBlend *
-            tentacleInfluence.core *
-            (0.11 + tipBlend * 0.06 + tentacleInfluence.widthScale * 0.025) *
-            radiusX;
+        const tentacleTubeRadius = lowerBlend * tentacleInfluence.core * (0.11 + tipBlend * 0.06 + tentacleInfluence.widthScale * 0.025) * radiusX;
         const planarRadiusX = cosineLatitude * radiusX * horizontalScale + tentacleTubeRadius;
         const planarRadiusZ = cosineLatitude * radiusZ * depthScale + tentacleTubeRadius * 0.72;
         const lowerDrop = lowerBlend *
@@ -13364,8 +13439,7 @@
                         tentacleInfluence.lengthScale * 0.22 +
                         (morphologyProfile.tentacles.flowLengthScale - 1) * 0.08));
         return {
-            x: Math.sin(effectiveLongitude) * planarRadiusX +
-                tentacleWave * radiusX * (0.052 + tipBlend * 0.05),
+            x: Math.sin(effectiveLongitude) * planarRadiusX + tentacleWave * radiusX * (0.052 + tipBlend * 0.05),
             y: Math.sin(latitude) * radiusY * (1 + upperBlend * 0.12) -
                 upperBlend * radiusY * 0.1 +
                 lowerDrop +
@@ -13439,8 +13513,11 @@
      */
     function resolveContinuousLobeWave(options, longitude) {
         const { morphologyProfile, animationPhase, timeMs } = options;
-        return (Math.cos(longitude * OCTOPUS_TENTACLE_COUNT + animationPhase + timeMs / (980 + morphologyProfile.body.lobeCount * 18)) +
-            1) / 2;
+        return ((Math.cos(longitude * OCTOPUS_TENTACLE_COUNT +
+            animationPhase +
+            timeMs / (980 + morphologyProfile.body.lobeCount * 18)) +
+            1) /
+            2);
     }
     /**
      * Resolves one base fill tone for a patch on the continuous octopus mesh.
@@ -13504,8 +13581,7 @@
             for (let sampleIndex = 0; sampleIndex < 8; sampleIndex++) {
                 const progress = sampleIndex / 7;
                 const latitude = -0.46 + progress * 0.74;
-                const longitude = baseLongitude +
-                    Math.sin(timeMs / 1160 + animationPhase + currentIndex * 0.7 + progress * 2) * 0.035;
+                const longitude = baseLongitude + Math.sin(timeMs / 1160 + animationPhase + currentIndex * 0.7 + progress * 2) * 0.035;
                 const scenePoint = transformScenePoint(sampleContinuousOctopusSurfacePoint(surfaceOptions, latitude, longitude), center, rotationX, rotationY);
                 if (scenePoint.z > center.z - size * 0.016) {
                     projectedPoints.push(projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
@@ -35080,7 +35156,7 @@
     async function moveAgentMessageToFinished(projectPath, messageFile) {
         const finishedDirectoryPath = path.join(projectPath, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH);
         const finishedMessagePath = path.join(finishedDirectoryPath, messageFile.fileName);
-        const finishedMessageRelativePath = normalizeRelativePath(path.join(AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, messageFile.fileName));
+        const finishedMessageRelativePath = normalizeRelativePath$1(path.join(AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, messageFile.fileName));
         await promises.mkdir(finishedDirectoryPath, { recursive: true });
         if (await isExistingPath(finishedMessagePath)) {
             await promises.rm(finishedMessagePath, { force: true });
@@ -35110,7 +35186,7 @@
     /**
      * Normalizes a relative path for Git and display.
      */
-    function normalizeRelativePath(relativePath) {
+    function normalizeRelativePath$1(relativePath) {
         return relativePath.replace(/\\/gu, '/');
     }
     /**
@@ -36129,6 +36205,177 @@
         `));
     }
 
+    /**
+     * Moves one repeatedly failing queued message to `messages/failed` with a visible agent failure reply.
+     */
+    async function moveAgentMessageToFailed(options) {
+        const { projectPath, messageFile, failureReason } = options;
+        const failedDirectoryPath = path.join(projectPath, AGENT_FAILED_MESSAGES_DIRECTORY_PATH);
+        const failedMessagePath = path.join(failedDirectoryPath, messageFile.fileName);
+        const failedMessageRelativePath = normalizeRelativePath(path.join(AGENT_FAILED_MESSAGES_DIRECTORY_PATH, messageFile.fileName));
+        const queuedMessageContent = await promises.readFile(messageFile.absolutePath, 'utf-8');
+        await promises.mkdir(failedDirectoryPath, { recursive: true });
+        await promises.rm(failedMessagePath, { force: true });
+        await promises.rename(messageFile.absolutePath, failedMessagePath);
+        await promises.writeFile(failedMessagePath, appendFailureReply(queuedMessageContent, failureReason), 'utf-8');
+        return {
+            absolutePath: failedMessagePath,
+            relativePath: failedMessageRelativePath,
+            fileName: messageFile.fileName,
+        };
+    }
+    /**
+     * Appends a synthetic `@Agent` reply so the Agents Server can display the terminal failure reason.
+     */
+    function appendFailureReply(bookContent, failureReason) {
+        const normalizedBookContent = bookContent.trimEnd();
+        const normalizedFailureReason = failureReason.trim();
+        return `${normalizedBookContent}\n\nMESSAGE @Agent\n${normalizedFailureReason}\n`;
+    }
+    /**
+     * Normalizes a relative path for Git and display.
+     */
+    function normalizeRelativePath(relativePath) {
+        return relativePath.replace(/\\/gu, '/');
+    }
+
+    /**
+     * Default number of failed queued-message attempts allowed before the watcher stops retrying that message.
+     */
+    const DEFAULT_MAX_MESSAGE_PROCESSING_FAILURES = 3;
+    /**
+     * Maximum number of characters copied from the final runner error into the failed chat message.
+     */
+    const MAX_FAILED_MESSAGE_ERROR_DETAILS_LENGTH = 4000;
+    /**
+     * Tracks repeated watch-level failures for queued message files and stops retrying them after a configured cap.
+     */
+    class AgentMessageFailureTracker {
+        constructor(options = {}) {
+            this.failuresByMessageKey = new Map();
+            this.maxMessageProcessingFailures = normalizeMaxMessageProcessingFailures(options.maxMessageProcessingFailures);
+        }
+        /**
+         * Clears the failure counter after a queued message is processed successfully.
+         */
+        clearMessageFailure(projectPath, messageFile) {
+            if (!messageFile) {
+                return;
+            }
+            this.failuresByMessageKey.delete(createAgentMessageFailureKey(projectPath, messageFile.relativePath));
+        }
+        /**
+         * Records one queued-message failure and moves the message into `messages/failed` when the retry cap is reached.
+         */
+        async recordFailure(error) {
+            var _a, _b;
+            const errorContext = getAgentWatchErrorContext(error);
+            if (!(errorContext === null || errorContext === void 0 ? void 0 : errorContext.projectPath) || !errorContext.queuedMessageRelativePath) {
+                return null;
+            }
+            const messageKey = createAgentMessageFailureKey(errorContext.projectPath, errorContext.queuedMessageRelativePath);
+            const previousFailureCount = (_b = (_a = this.failuresByMessageKey.get(messageKey)) === null || _a === void 0 ? void 0 : _a.failureCount) !== null && _b !== void 0 ? _b : 0;
+            const failureCount = previousFailureCount + 1;
+            if (failureCount < this.maxMessageProcessingFailures) {
+                this.failuresByMessageKey.set(messageKey, { failureCount });
+                return {
+                    failureCount,
+                    maxMessageProcessingFailures: this.maxMessageProcessingFailures,
+                    isMessageMovedToFailed: false,
+                };
+            }
+            try {
+                await moveAgentMessageToFailed({
+                    projectPath: errorContext.projectPath,
+                    messageFile: createAgentMessageFileFromContext(errorContext.projectPath, errorContext.queuedMessageRelativePath),
+                    failureReason: buildFailedQueuedMessageReason({
+                        error,
+                        failureCount,
+                        maxMessageProcessingFailures: this.maxMessageProcessingFailures,
+                    }),
+                });
+                this.failuresByMessageKey.delete(messageKey);
+                console.error(colors__default["default"].yellow(`Moved ${errorContext.queuedMessageRelativePath} to messages/failed after ${failureCount} failed attempt(s).`));
+            }
+            catch (moveError) {
+                this.failuresByMessageKey.set(messageKey, { failureCount });
+                console.error(colors__default["default"].yellow(`Failed to move ${errorContext.queuedMessageRelativePath} to messages/failed: ${formatUnknownErrorDetails(moveError)}`));
+                return {
+                    failureCount,
+                    maxMessageProcessingFailures: this.maxMessageProcessingFailures,
+                    isMessageMovedToFailed: false,
+                };
+            }
+            return {
+                failureCount,
+                maxMessageProcessingFailures: this.maxMessageProcessingFailures,
+                isMessageMovedToFailed: true,
+            };
+        }
+    }
+    /**
+     * Creates the stable in-memory key for one queued message.
+     */
+    function createAgentMessageFailureKey(projectPath, queuedMessageRelativePath) {
+        return `${projectPath}\0${queuedMessageRelativePath}`;
+    }
+    /**
+     * Recreates the selected queued message descriptor from watch-loop error context.
+     */
+    function createAgentMessageFileFromContext(projectPath, queuedMessageRelativePath) {
+        return {
+            absolutePath: path.join(projectPath, queuedMessageRelativePath),
+            relativePath: queuedMessageRelativePath.replace(/\\/gu, '/'),
+            fileName: getFileNameFromRelativePath(queuedMessageRelativePath),
+        };
+    }
+    /**
+     * Extracts the filename from a normalized or platform-specific relative path.
+     */
+    function getFileNameFromRelativePath(relativePath) {
+        const pathParts = relativePath.replace(/\\/gu, '/').split('/');
+        return pathParts[pathParts.length - 1] || 'message.book';
+    }
+    /**
+     * Builds the message shown to the chat user when the local runner stops retrying.
+     */
+    function buildFailedQueuedMessageReason(options) {
+        const errorDetails = limitFailureDetails(formatUnknownErrorDetails(options.error));
+        return _spaceTrim.spaceTrim((block) => `
+            Local agent runner failed after ${options.failureCount} attempt(s) and stopped retrying.
+
+            Fix the runner or API configuration before trying again. The maximum failed-attempt limit is currently ${options.maxMessageProcessingFailures}.
+
+            Last runner error:
+            \`\`\`
+            ${block(errorDetails)}
+            \`\`\`
+        `);
+    }
+    /**
+     * Keeps the synthetic failed chat message bounded even when runner logs are long.
+     */
+    function limitFailureDetails(errorDetails) {
+        const normalizedErrorDetails = errorDetails.trim();
+        if (normalizedErrorDetails.length <= MAX_FAILED_MESSAGE_ERROR_DETAILS_LENGTH) {
+            return normalizedErrorDetails;
+        }
+        return _spaceTrim.spaceTrim(`
+        [...runner error truncated to the last ${MAX_FAILED_MESSAGE_ERROR_DETAILS_LENGTH} characters...]
+        ${normalizedErrorDetails.slice(-MAX_FAILED_MESSAGE_ERROR_DETAILS_LENGTH)}
+    `);
+    }
+    /**
+     * Normalizes the retry cap used by standalone CLI runs when no server-provided limit is available.
+     */
+    function normalizeMaxMessageProcessingFailures(rawValue) {
+        const parsedValue = Number(rawValue);
+        if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+            return DEFAULT_MAX_MESSAGE_PROCESSING_FAILURES;
+        }
+        return Math.floor(parsedValue);
+    }
+
     /**
      * Delay between multi-agent watch iterations while all queues stay empty.
      */
@@ -36165,6 +36412,9 @@
         let lastObservedProjectCount = 0;
         let isWatchSessionInitialized = false;
         let uiHandle;
+        const messageFailureTracker = new AgentMessageFailureTracker({
+            maxMessageProcessingFailures: options.maxMessageProcessingFailures,
+        });
         while (shouldContinue()) {
             try {
                 if (!isWatchSessionInitialized) {
@@ -36213,7 +36463,7 @@
                 const queuedProjects = projectSummaries.filter((projectSummary) => projectSummary.queuedMessageCount > 0);
                 if (queuedProjects.length === 0) {
                     updateMultipleAgentRunUiForWatching(uiHandle, options, rootPath, projectSummaries, ignoredAgentCount);
-                    await wait$2(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
+                    await wait$3(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
                     continue;
                 }
                 if (!uiHandle) {
@@ -36253,6 +36503,9 @@
                         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({
@@ -36260,6 +36513,7 @@
                         logDirectoryPath: controls.watchErrorLogDirectoryPath || rootPath,
                         error: tickResult.reason,
                     });
+                    await messageFailureTracker.recordFailure(tickResult.reason);
                 }
             }
             catch (error) {
@@ -36268,7 +36522,8 @@
                     logDirectoryPath: controls.watchErrorLogDirectoryPath || rootPath,
                     error,
                 });
-                await wait$2(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
+                await messageFailureTracker.recordFailure(error);
+                await wait$3(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
             }
         }
     }
@@ -36352,7 +36607,9 @@
             const autoPullTimestamp = await pullLatestChangesForAgentQueueIfEnabled({
                 projectPath,
                 runOptions,
-                logMessage: uiHandle ? undefined : `Pulling latest changes in ${formatProjectPath(rootPath, projectPath)}...`,
+                logMessage: uiHandle
+                    ? undefined
+                    : `Pulling latest changes in ${formatProjectPath(rootPath, projectPath)}...`,
             });
             if (autoPullTimestamp !== undefined) {
                 autoPullTimestampsByProjectPath.set(projectPath, autoPullTimestamp);
@@ -36566,9 +36823,7 @@
         const answeringMessageLines = projectSummaries
             .filter((projectSummary) => answeringProjectPaths.has(projectSummary.project.projectPath))
             .flatMap((projectSummary) => buildAnsweringAgentMessageLines(projectSummary));
-        return answeringMessageLines.length > 0
-            ? answeringMessageLines
-            : [WAITING_FOR_MESSAGE_LABEL];
+        return answeringMessageLines.length > 0 ? answeringMessageLines : [WAITING_FOR_MESSAGE_LABEL];
     }
     /**
      * Builds one dedicated message-preview panel per answering agent.
@@ -36659,7 +36914,7 @@
     /**
      * Waits for the next idle poll interval in multi-agent watch mode.
      */
-    async function wait$2(delayMs) {
+    async function wait$3(delayMs) {
         await new Promise((resolve) => setTimeout(resolve, delayMs));
     }
 
@@ -36682,6 +36937,218 @@
         }
     }
 
+    /**
+     * Metadata key storing the delay between retry attempts when importing federated agent books.
+     *
+     * @private internal Agents Server constant
+     */
+    const FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS_METADATA_KEY = 'FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS';
+    /**
+     * Total number of attempts used when loading a federated imported agent before falling back.
+     *
+     * @private internal Agents Server constant
+     */
+    const FEDERATED_AGENT_IMPORT_MAX_ATTEMPTS = 3;
+    /**
+     * Default delay in milliseconds between federated imported-agent retry attempts.
+     *
+     * @private internal Agents Server constant
+     */
+    const DEFAULT_FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS = 500;
+    /**
+     * Default retry configuration for federated imported-agent loading.
+     *
+     * @private internal Agents Server constant
+     */
+    Object.freeze({
+        maxAttempts: FEDERATED_AGENT_IMPORT_MAX_ATTEMPTS,
+        retryDelayMs: DEFAULT_FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS,
+    });
+
+    /**
+     * Metadata key used to persist tool-usage limits.
+     *
+     * @private shared constant for Agents Server
+     */
+    const TOOL_USAGE_LIMITS_METADATA_KEY = 'TOOL_USAGE_LIMITS';
+    /**
+     * Default timeout limits applied when administrators do not override them.
+     *
+     * @private shared constant for Agents Server
+     */
+    const DEFAULT_TIMEOUT_TOOL_USAGE_LIMITS = {
+        maxActivePerChat: 5,
+        maxFiredPerDayPerChat: 10,
+    };
+
+    /**
+     * Legacy metadata key storing the maximum accepted file upload size in megabytes.
+     *
+     * @private shared Agents Server constant
+     */
+    const MAX_FILE_UPLOAD_SIZE_MB_METADATA_KEY = 'MAX_FILE_UPLOAD_SIZE_MB';
+    /**
+     * Default maximum accepted spawn depth in one tool-runtime context.
+     *
+     * @private shared Agents Server constant
+     */
+    const DEFAULT_SPAWN_AGENT_MAX_DEPTH = 2;
+    /**
+     * Default maximum number of spawned agents allowed per actor in one time window.
+     *
+     * @private shared Agents Server constant
+     */
+    const DEFAULT_SPAWN_AGENT_RATE_LIMIT_MAX = 5;
+    /**
+     * Default spawn rate-limit window size in milliseconds.
+     *
+     * @private shared Agents Server constant
+     */
+    const DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
+    /**
+     * Default maximum number of failed local runner attempts before a queued message is moved to `messages/failed`.
+     *
+     * @private shared Agents Server constant
+     */
+    const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
+    /**
+     * Stable keys used by the dedicated server-limits table.
+     *
+     * @private shared Agents Server constant
+     */
+    const SERVER_LIMIT_KEYS = {
+        TIMEOUT_MAX_ACTIVE_PER_CHAT: 'TIMEOUT_MAX_ACTIVE_PER_CHAT',
+        TIMEOUT_MAX_FIRED_PER_DAY_PER_CHAT: 'TIMEOUT_MAX_FIRED_PER_DAY_PER_CHAT',
+        MAX_FILE_UPLOAD_SIZE_MB: MAX_FILE_UPLOAD_SIZE_MB_METADATA_KEY,
+        FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS: FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS_METADATA_KEY,
+        SPAWN_AGENT_MAX_DEPTH: 'SPAWN_AGENT_MAX_DEPTH',
+        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',
+    };
+    /**
+     * Shared metadata for all server limits exposed in the admin UI and runtime loaders.
+     *
+     * @private shared Agents Server constant
+     */
+    const SERVER_LIMIT_DEFINITIONS = [
+        {
+            key: SERVER_LIMIT_KEYS.TIMEOUT_MAX_ACTIVE_PER_CHAT,
+            category: 'Timeout tools',
+            title: 'Max active timers per chat',
+            description: 'Prevents one chat thread from scheduling too many timers at once.',
+            unit: 'count',
+            defaultValue: DEFAULT_TIMEOUT_TOOL_USAGE_LIMITS.maxActivePerChat,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [TOOL_USAGE_LIMITS_METADATA_KEY],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.TIMEOUT_MAX_FIRED_PER_DAY_PER_CHAT,
+            category: 'Timeout tools',
+            title: 'Max timers fired per day per chat',
+            description: 'Limits how many scheduled wake-ups can execute inside one chat within one UTC day.',
+            unit: 'count',
+            defaultValue: DEFAULT_TIMEOUT_TOOL_USAGE_LIMITS.maxFiredPerDayPerChat,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [TOOL_USAGE_LIMITS_METADATA_KEY],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.MAX_FILE_UPLOAD_SIZE_MB,
+            category: 'Files',
+            title: 'Max file upload size',
+            description: 'Caps the size of uploaded files accepted by chat uploads and Android share-target imports.',
+            unit: 'MB',
+            defaultValue: 50,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [MAX_FILE_UPLOAD_SIZE_MB_METADATA_KEY],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS,
+            category: 'Federation',
+            title: 'Federated import retry delay',
+            description: 'Wait time between retries when importing agent books from federated servers.',
+            unit: 'ms',
+            defaultValue: DEFAULT_FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS,
+            minimumValue: 0,
+            step: 100,
+            legacyMetadataKeys: [FEDERATED_AGENT_IMPORT_RETRY_DELAY_MS_METADATA_KEY],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.SPAWN_AGENT_MAX_DEPTH,
+            category: 'Agent spawning',
+            title: 'Max spawn depth',
+            description: 'Restricts how many nested `spawn_agent` hops can happen inside one tool runtime context.',
+            unit: 'count',
+            defaultValue: DEFAULT_SPAWN_AGENT_MAX_DEPTH,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.SPAWN_AGENT_RATE_LIMIT_MAX,
+            category: 'Agent spawning',
+            title: 'Max spawned agents per window',
+            description: 'Limits how many persistent agents one actor can create through `spawn_agent` inside one rate-limit window.',
+            unit: 'count',
+            defaultValue: DEFAULT_SPAWN_AGENT_RATE_LIMIT_MAX,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.SPAWN_AGENT_RATE_LIMIT_WINDOW_MS,
+            category: 'Agent spawning',
+            title: 'Spawn rate-limit window',
+            description: 'Time window used together with the spawn quota for `spawn_agent` abuse protection.',
+            unit: 'ms',
+            defaultValue: DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS,
+            minimumValue: 1000,
+            step: 1000,
+            legacyMetadataKeys: [],
+        },
+        {
+            key: SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+            category: 'Local agent runner',
+            title: 'Max failed message attempts',
+            description: 'Stops the local coding-agent watcher from retrying the same queued chat message forever.',
+            unit: 'count',
+            defaultValue: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+            minimumValue: 1,
+            step: 1,
+            legacyMetadataKeys: [],
+        },
+    ];
+    /**
+     * Fast lookup map used by server-limit validators and UI helpers.
+     *
+     * @private shared Agents Server constant
+     */
+    new Map(SERVER_LIMIT_DEFINITIONS.map((definition) => [definition.key, definition]));
+    /**
+     * Fully normalized default values keyed by dedicated server-limit ids.
+     *
+     * @private shared Agents Server constant
+     */
+    const defaultServerLimitValues = {};
+    for (const definition of SERVER_LIMIT_DEFINITIONS) {
+        defaultServerLimitValues[definition.key] = definition.defaultValue;
+    }
+    /**
+     * Default values used whenever a server-limit row has not been persisted yet.
+     *
+     * @private shared Agents Server constant
+     */
+    Object.freeze(defaultServerLimitValues);
+    /**
+     * Deprecated metadata keys that now mirror dedicated server-limit rows for backward compatibility.
+     *
+     * @private shared Agents Server constant
+     */
+    Array.from(new Set(SERVER_LIMIT_DEFINITIONS.flatMap((definition) => definition.legacyMetadataKeys)));
+
     /**
      * Local worker-pump delay while the Agents Server foreground process stays active.
      *
@@ -36700,6 +37167,18 @@
      * @private internal constant of `ptbk agents-server`
      */
     const USER_CHAT_JOB_WORKER_ERROR_BODY_MAX_LENGTH = 2000;
+    /**
+     * 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 = 1000;
+    /**
+     * 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 = 60000;
     /**
      * HTTP status used by an idle internal worker tick with no job to process.
      *
@@ -36806,6 +37285,12 @@
                 logStreams,
                 state,
             });
+            const localAgentRunnerLimits = await waitForLocalAgentRunnerLimits({
+                port: options.port,
+                environment: runtimeChildEnvironment,
+                logStreams,
+                state,
+            });
             stopUserChatJobWorkerPump = startUserChatJobWorkerPump({
                 port: options.port,
                 environment: runtimeChildEnvironment,
@@ -36813,7 +37298,7 @@
                 state,
             });
             await withCurrentWorkingDirectory(runtimePaths.agentRootPath, async () => {
-                await runMultipleAgentMessages(createLocalAgentRunOptions(options), {
+                await runMultipleAgentMessages(createLocalAgentRunOptions(options, localAgentRunnerLimits), {
                     shouldContinue: () => state.isContinuing,
                     watchErrorLogDirectoryPath: runtimePaths.logDirectoryPath,
                     onUiInitialized: (uiHandle) => {
@@ -36942,7 +37427,7 @@
     /**
      * Creates local no-git agent runner options for folders managed by the Agents Server database.
      */
-    function createLocalAgentRunOptions(options) {
+    function createLocalAgentRunOptions(options, localAgentRunnerLimits) {
         return {
             agentName: options.agentName,
             model: options.model,
@@ -36955,8 +37440,67 @@
             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) {
+        const startedAt = Date.now();
+        let lastError;
+        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$2(INTERNAL_SERVER_LIMITS_RETRY_DELAY_MS);
+            }
+        }
+        if (!options.state.isContinuing) {
+            return {
+                maxFailedAttempts: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+            };
+        }
+        throw new NotAllowed(_spaceTrim.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) {
+        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());
+        return {
+            maxFailedAttempts: normalizeLocalAgentRunnerMaxFailedAttempts(payload.maxFailedAttempts),
+        };
+    }
+    /**
+     * Normalizes the local runner retry cap returned by the internal server route.
+     */
+    function normalizeLocalAgentRunnerMaxFailedAttempts(rawValue) {
+        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.
      */
@@ -37065,12 +37609,18 @@
      * Builds the foreground worker failure message from HTTP status and route details.
      */
     function createUserChatJobWorkerErrorMessage(response, details) {
+        return createInternalRouteErrorMessage('user chat worker', response, details);
+    }
+    /**
+     * Builds a foreground failure message for one internal Agents Server route.
+     */
+    function createInternalRouteErrorMessage(routeLabel, response, details) {
         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}`;
     }
     /**
      * Keeps foreground worker diagnostics bounded when a route returns a large payload.
@@ -37140,6 +37690,12 @@
         }
         commandProcess.kill();
     }
+    /**
+     * Waits for the given delay.
+     */
+    async function wait$2(delayMs) {
+        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`
 
     /**
@@ -61797,14 +62353,18 @@
      * Watches the queued message directory and answers messages one by one.
      */
     async function runAgentMessages(options, controls = {}) {
-        var _a;
+        var _a, _b;
         validateAgentRunOptions(options);
         validateAgentWatchOptions('ptbk agent-folder run-agent', options);
         const projectPath = process.cwd();
         let autoPullTimestamp = options.autoPull ? Date.now() : undefined;
         const shouldContinue = controls.shouldContinue || (() => just(true));
+        const queuePollIntervalMs = (_a = controls.queuePollIntervalMs) !== null && _a !== void 0 ? _a : AGENT_QUEUE_POLL_INTERVAL_MS;
         let isWatchSessionInitialized = false;
         let uiHandle;
+        const messageFailureTracker = new AgentMessageFailureTracker({
+            maxMessageProcessingFailures: options.maxMessageProcessingFailures,
+        });
         while (shouldContinue()) {
             try {
                 if (!isWatchSessionInitialized) {
@@ -61816,8 +62376,9 @@
                     }
                 }
                 const result = await tickAgentMessages(options, { isQuietWhenIdle: true, uiHandle });
-                autoPullTimestamp = (_a = result.autoPullTimestamp) !== null && _a !== void 0 ? _a : autoPullTimestamp;
+                autoPullTimestamp = (_b = result.autoPullTimestamp) !== null && _b !== void 0 ? _b : autoPullTimestamp;
                 if (result.isMessageProcessed) {
+                    messageFailureTracker.clearMessageFailure(projectPath, result.queuedMessage);
                     continue;
                 }
                 autoPullTimestamp = await waitForQueuedAgentMessage({
@@ -61826,6 +62387,7 @@
                     autoPullTimestamp,
                     uiHandle,
                     shouldContinue,
+                    queuePollIntervalMs,
                 });
             }
             catch (error) {
@@ -61834,7 +62396,8 @@
                     logDirectoryPath: projectPath,
                     error,
                 });
-                await wait(AGENT_QUEUE_POLL_INTERVAL_MS);
+                await messageFailureTracker.recordFailure(error);
+                await wait(queuePollIntervalMs);
             }
         }
     }
@@ -61842,14 +62405,14 @@
      * Polls until at least one queued `.book` message is available.
      */
     async function waitForQueuedAgentMessage(options) {
-        const { projectPath, options: runOptions, uiHandle, shouldContinue } = options;
+        const { projectPath, options: runOptions, uiHandle, shouldContinue, queuePollIntervalMs } = options;
         let { autoPullTimestamp } = options;
         let queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
         if (uiHandle) {
             updateAgentRunUiForWatching(uiHandle, queueSnapshot);
         }
         while (shouldContinue()) {
-            await wait(AGENT_QUEUE_POLL_INTERVAL_MS);
+            await wait(queuePollIntervalMs);
             queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
             if (queueSnapshot.queuedMessages.length > 0) {
                 return autoPullTimestamp;