@promptbook/cli 0.113.0-5 → 0.113.0-8

package/apps/agents-server/src/utils/resolveInheritedAgentSource.ts

@@ -231,8 +231,42 @@ type ResolveInheritedAgentSourceOptions = ImportAgentOptions & {
      * Retry configuration used for federated imported-agent loading.
      */
     readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+    /**
+     * Optional same-instance source importer used before falling back to HTTP import.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
 };
 
+/**
+ * Context passed to a custom agent source importer.
+ */
+export type AgentSourceImporterContext = {
+    /**
+     * Commitment that requested the imported source.
+     */
+    readonly commitmentType: 'FROM' | 'IMPORT';
+
+    /**
+     * Import options propagated from the current resolution pass.
+     */
+    readonly importAgentOptions: ImportAgentOptions;
+
+    /**
+     * Retry configuration used by the default HTTP importer.
+     */
+    readonly federatedAgentImportConfiguration: FederatedAgentImportConfiguration;
+};
+
+/**
+ * Imports one agent source before the resolver falls back to the default HTTP importer.
+ *
+ * Return `null` when the importer does not own the given URL.
+ */
+export type AgentSourceImporter = (
+    agentUrl: string_agent_url,
+    context: AgentSourceImporterContext,
+) => Promise<string_book | null>;
+
 /**
  * Parent inheritance state derived before rewriting the source body.
  */
@@ -277,6 +311,11 @@ type AgentImportContext = {
      */
     readonly importAgentOptions: ImportAgentOptions;
 
+    /**
+     * Optional importer for same-instance agent sources.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
+
     /**
      * Original resolution options used for cycle detection.
      */
@@ -364,6 +403,7 @@ function createAgentImportContext(options?: ResolveInheritedAgentSourceOptions):
             recursionLevel: options?.recursionLevel || 0,
             inheritancePath: createResolutionLineage(options),
         },
+        agentSourceImporter: options?.agentSourceImporter,
         resolutionOptions: options,
     };
 }
@@ -427,11 +467,20 @@ async function importAgentCorpus(
 ): Promise<string> {
     assertNoResolutionCycle(agentUrl, commitmentType, context.resolutionOptions);
 
-    const importedAgentSource = await importAgentWithFallback(
-        agentUrl,
-        context.importAgentOptions,
-        context.federatedAgentImportConfiguration,
-    );
+    const locallyImportedAgentSource = context.agentSourceImporter
+        ? await context.agentSourceImporter(agentUrl, {
+              commitmentType,
+              importAgentOptions: context.importAgentOptions,
+              federatedAgentImportConfiguration: context.federatedAgentImportConfiguration,
+          })
+        : null;
+    const importedAgentSource =
+        locallyImportedAgentSource ??
+        (await importAgentWithFallback(
+            agentUrl,
+            context.importAgentOptions,
+            context.federatedAgentImportConfiguration,
+        ));
 
     return getAgentSourceCorpus(importedAgentSource as string_book);
 }

package/apps/agents-server/src/utils/resolveServerAgentContext.ts

@@ -1,6 +1,7 @@
 import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-source/AgentReferenceResolver';
 import type { AgentCollection } from '../../../../src/collection/agent-collection/AgentCollection';
 import { resolveBookScopedAgentContext, type ResolvedBookScopedAgentContext } from './agentReferenceResolver/bookScopedAgentReferences';
+import { createLocalAgentSourceImporter } from './createLocalAgentSourceImporter';
 import { loadFederatedAgentImportConfiguration } from './federatedAgentImportConfiguration';
 import { getWellKnownAgentUrl } from './getWellKnownAgentUrl';
 import { resolveAgentStateFromSource, type ResolvedAgentState } from './resolveAgentStateFromSource';
@@ -46,12 +47,22 @@ export async function resolveServerAgentContext(
 ): Promise<ResolvedServerAgentContext> {
     const bookScopedAgentContext = await resolveBookScopedAgentContext(options);
     const federatedAgentImportConfiguration = await loadFederatedAgentImportConfiguration();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection: options.collection,
+        localServerUrls: [options.localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: options.fallbackResolver,
+        federatedAgentImportConfiguration,
+    });
     const resolvedAgentState = await resolveAgentStateFromSource(bookScopedAgentContext.unresolvedAgentSource, {
-        adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
+        adamAgentUrl,
         canonicalAgentUrl: bookScopedAgentContext.canonicalAgentUrl,
         currentAgentAliases: bookScopedAgentContext.currentAgentAliases,
         agentReferenceResolver: bookScopedAgentContext.scopedAgentReferenceResolver,
         federatedAgentImportConfiguration,
+        agentSourceImporter,
     });
 
     return {

package/apps/agents-server/src/utils/resolveStoredAgentState.ts

@@ -30,7 +30,7 @@ export type ResolvedStoredAgentState<TAgent extends StoredAgentSourceRecord> = T
  */
 export type ResolveStoredAgentStateOptions = Pick<
     ResolveAgentStateFromSourceOptions,
-    'adamAgentUrl' | 'agentReferenceResolver' | 'federatedAgentImportConfiguration'
+    'adamAgentUrl' | 'agentReferenceResolver' | 'federatedAgentImportConfiguration' | 'agentSourceImporter'
 > & {
     /**
      * Public/current server origin used to build canonical local agent URLs.
@@ -91,6 +91,7 @@ export async function resolveStoredAgentState<TAgent extends StoredAgentSourceRe
         currentAgentAliases: createCanonicalLocalAgentAliases(agent, options.localServerUrl),
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
 
     return {

package/apps/agents-server/src/utils/speech-to-text/SpeechToTextFailoverRecognition/SpeechToTextFailoverRecognitionProviderRuntime.ts

@@ -172,7 +172,6 @@ export class SpeechToTextFailoverRecognitionProviderRuntime {
             }
         }
 
-        this.options.onForceIdleStop();
         return false;
     }
 

package/apps/agents-server/src/utils/speech-to-text/SpeechToTextFailoverRecognition.ts

@@ -302,13 +302,45 @@ export class SpeechToTextFailoverRecognition implements SpeechRecognition {
      * Handles stall watchdog restart/failover escalation.
      */
     private handleStallDetected(): void {
+        void this.handleStallDetectedAsync();
+    }
+
+    /**
+     * Handles stall watchdog restart/failover escalation.
+     */
+    private async handleStallDetectedAsync(): Promise<void> {
+        const providerId = this.providerRuntime.currentProviderId;
+
         if (!this.providerRuntime.hasRestartedCurrentProvider) {
             this.providerRuntime.markCurrentProviderRestarted();
-            void this.providerRuntime.restartCurrentProvider('stall-detected');
+            this.telemetryReporter.emit({
+                type: 'provider-restart',
+                providerId,
+                elapsedMs: Date.now() - this.sessionStartedAtMs,
+                detail: 'stall-detected',
+            });
+
+            const restartSucceeded = await this.providerRuntime.restartCurrentProvider('stall-detected');
+            if (restartSucceeded) {
+                return;
+            }
+        }
+
+        const failoverSucceeded = await this.providerRuntime.failoverToNextProvider('stall-after-restart');
+        if (failoverSucceeded) {
             return;
         }
 
-        void this.providerRuntime.failoverToNextProvider('stall-after-restart');
+        this._state = 'ERROR';
+        this.emit({
+            type: 'ERROR',
+            message: 'Speech recognition stalled while audio was detected. No fallback speech-to-text provider was available.',
+            code: 'unknown',
+            providerId,
+            canRetry: true,
+            canOpenBrowserSettings: false,
+        });
+        this.forceIdleStop();
     }
 
     /**

package/apps/agents-server/src/utils/userChat/userChatMessageLifecycle.ts

@@ -1,4 +1,6 @@
 import type { ChatMessage } from '../../../../../src/_packages/types.index';
+import { appendChatAttachmentContextWithContent } from '../../../../../src/utils/chat/chatAttachments/appendChatAttachmentContextWithContent';
+
 /**
  * Lifecycle states rendered on canonical server-owned chat messages.
  */
@@ -99,11 +101,11 @@ export function resolvePromptThreadBeforeUserMessage(
 /**
  * Creates the complete chat thread mirrored to a runner before it writes the next answer.
  */
-export function createUserChatRunnerThreadMessages(options: {
+export async function createUserChatRunnerThreadMessages(options: {
     messages: ReadonlyArray<ChatMessage>;
     userMessageId: string;
     resolveInitialAgentMessage: () => string | null | undefined;
-}): Array<UserChatRunnerThreadMessage> {
+}): Promise<Array<UserChatRunnerThreadMessage>> {
     const userMessage = options.messages.find((message) => message.id === options.userMessageId);
     if (!userMessage) {
         return [];
@@ -111,19 +113,16 @@ export function createUserChatRunnerThreadMessages(options: {
 
     const previousThreadMessages = resolvePromptThreadBeforeUserMessage(options.messages, options.userMessageId);
 
-    return [
+    const threadMessages = [
         ...createInitialUserChatRunnerThreadMessages({
             isFirstUserTurn: previousThreadMessages.length === 0,
             resolveInitialAgentMessage: options.resolveInitialAgentMessage,
         }),
         ...previousThreadMessages,
         userMessage,
-    ]
-        .filter(isUserChatRunnerThreadMessage)
-        .map((message) => ({
-            sender: message.sender,
-            content: message.content,
-        }));
+    ].filter(isUserChatRunnerThreadMessage);
+
+    return await Promise.all(threadMessages.map(createUserChatRunnerThreadMessage));
 }
 
 /**
@@ -176,3 +175,34 @@ function isUserChatRunnerThreadMessage(message: ChatMessage): message is ChatMes
     const isRunnerSender = message.sender === 'USER' || message.sender === 'AGENT';
     return message.isComplete !== false && isRunnerSender;
 }
+
+/**
+ * Creates one runner-visible message with attachment context inlined into user-authored content.
+ *
+ * @private helper of `createUserChatRunnerThreadMessages`
+ */
+async function createUserChatRunnerThreadMessage(
+    message: ChatMessage & UserChatRunnerThreadMessage,
+): Promise<UserChatRunnerThreadMessage> {
+    return {
+        sender: message.sender,
+        content: await createUserChatRunnerThreadMessageContent(message),
+    };
+}
+
+/**
+ * Adds attachment URLs and best-effort text previews to user messages mirrored into runner `.book` files.
+ *
+ * @private helper of `createUserChatRunnerThreadMessage`
+ */
+async function createUserChatRunnerThreadMessageContent(
+    message: ChatMessage & UserChatRunnerThreadMessage,
+): Promise<string> {
+    if (message.sender !== 'USER' || !message.attachments || message.attachments.length === 0) {
+        return message.content;
+    }
+
+    return await appendChatAttachmentContextWithContent(message.content, message.attachments, {
+        allowLocalhost: true,
+    });
+}

package/apps/agents-server/tests/e2e/support/ChatHistoryNavigationSupport.ts

@@ -212,6 +212,7 @@ async function delayNextMatchingRequest(
     options: DelayNextMatchingRequestOptions,
 ): Promise<DelayedRequestControl> {
     let hasInterceptedTargetRequest = false;
+    let isReleased = false;
     let releaseRequest: (() => void) | null = null;
     let markStarted: (() => void) | null = null;
     let markFinished: (() => void) | null = null;
@@ -239,6 +240,9 @@ async function delayNextMatchingRequest(
 
         await new Promise<void>((resolve) => {
             releaseRequest = resolve;
+            if (isReleased) {
+                resolve();
+            }
         });
 
         try {
@@ -255,6 +259,7 @@ async function delayNextMatchingRequest(
         waitUntilStarted,
         waitUntilFinished,
         release() {
+            isReleased = true;
             releaseRequest?.();
         },
         async dispose() {

package/esm/index.es.js

@@ -59,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-5';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-8';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -14664,7 +14664,7 @@ const octopus3d4AvatarVisual = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots } = getOctopus3d4StableState(createRandom);
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots, } = getOctopus3d4StableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.535;
         const bob = Math.sin(timeMs / 980 + animationPhase) * size * 0.013;
@@ -15012,10 +15012,7 @@ function sampleBlobbyContinuousSurfacePointWithLongitudeCache(options, latitude,
         Math.max(0, Math.cos(effectiveLongitude)) * 0.12 +
         lowerBlend * tentacleInfluence.core * (0.12 + tentacleInfluence.depthScale * 0.07) -
         Math.max(0, -Math.cos(effectiveLongitude)) * 0.05;
-    const tentacleTubeRadius = lowerBlend *
-        tentacleInfluence.core *
-        (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) *
-        radiusX;
+    const tentacleTubeRadius = lowerBlend * tentacleInfluence.core * (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) * radiusX;
     const planarRadiusX = cosineLatitude * radiusX * horizontalScale + tentacleTubeRadius;
     const planarRadiusZ = cosineLatitude * radiusZ * depthScale + tentacleTubeRadius * 0.74;
     const lowerDrop = lowerBlend *
@@ -15027,9 +15024,7 @@ function sampleBlobbyContinuousSurfacePointWithLongitudeCache(options, latitude,
                     (morphologyProfile.tentacles.flowLengthScale - 1) * 0.1));
     const combinedTentacleSway = (primaryTentacleWave + secondaryTentacleWave) * radiusX * (0.06 + tipBlend * 0.06);
     return {
-        x: Math.sin(effectiveLongitude) * planarRadiusX +
-            combinedTentacleSway +
-            tentacleCurl * radiusX * 0.18,
+        x: Math.sin(effectiveLongitude) * planarRadiusX + combinedTentacleSway + tentacleCurl * radiusX * 0.18,
         y: Math.sin(latitude) * radiusY * (1 + upperBlend * 0.14) -
             upperBlend * radiusY * 0.12 +
             lowerDrop +
@@ -18288,10 +18283,10 @@ const teamToolTitles = {};
  *
  * @private
  */
-const TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES = [
-    '-   If a teammate is relevant to the request, consult that teammate using the matching tool.',
-    '-   Do not ask the user for information that a listed teammate can provide directly.',
-];
+const TEAM_SYSTEM_MESSAGE_GUIDANCE = spaceTrim$1(`
+    -   If a teammate is relevant to the request, consult that teammate using the matching tool.
+    -   Do not ask the user for information that a listed teammate can provide directly.
+`);
 /**
  * Constant for remote agents by Url.
  */
@@ -18473,7 +18468,7 @@ function buildTeamSystemMessageBody(teamEntries) {
             `);
     });
     return spaceTrim$1((block) => `
-            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES.join('\n'))}
+            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE)}
 
             ${block(teammateSections.join('\n\n'))}
         `);
@@ -40291,6 +40286,30 @@ function createLineCountLimits(maxLineCount) {
 }
 // Note: [🟡] Code for repository script [RefactorCandidateLevel](scripts/find-refactor-candidates/RefactorCandidateLevel.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Creates a Commander argument parser that accepts only positive integers.
+ *
+ * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+ * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+ * when the provided value is not a positive integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function createPositiveIntegerOptionParser(optionName) {
+    return (value) => {
+        const parsedValue = Number(value);
+        if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+            throw new NotAllowed(spaceTrim$1(`
+                    Invalid value for \`${optionName}\`: \`${value}\`.
+
+                    Use a positive integer.
+                `));
+        }
+        return parsedValue;
+    };
+}
+// Note: [🟡] Code for CLI option parser [createPositiveIntegerOptionParser](src/cli/cli-commands/common/createPositiveIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Initializes `coder find-refactor-candidates` command for Promptbook CLI utilities
  *
@@ -40311,12 +40330,13 @@ function $initializeCoderFindRefactorCandidatesCommand(program) {
     command.addOption(new Option('--level <level>', `Set scan aggressiveness (${REFACTOR_CANDIDATE_LEVEL_VALUES.join(', ')})`)
         .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
         .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL));
+    command.option('--limit <candidate-count>', 'Create at most this many refactor prompts, keeping the most important candidates', createPositiveIntegerOptionParser('--limit'));
     command.action(handleActionErrors(async (cliOptions) => {
-        const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = cliOptions;
+        const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions;
         // Note: Import the function dynamically to avoid loading heavy dependencies until needed
         const { findRefactorCandidates } = await Promise.resolve().then(function () { return findRefactorCandidates$1; });
         try {
-            await findRefactorCandidates({ level });
+            await findRefactorCandidates({ level, limit });
         }
         catch (error) {
             assertsError(error);
@@ -40400,26 +40420,26 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
         id: 'common',
         relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
         slugPrefix: null,
-        content: buildCoderPromptTemplateContent([
-            '-   @@@',
-            "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
-            '-   Do a proper analysis of the current functionality before you start implementing.',
-            '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
-        ]),
+        content: spaceTrim$1(`
+            -   @@@
+            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
+            -   Do a proper analysis of the current functionality before you start implementing.
+            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+        `),
         isDefaultProjectTemplate: true,
     },
     {
         id: 'agents-server',
         relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
         slugPrefix: 'agents-server',
-        content: buildCoderPromptTemplateContent([
-            '-   @@@',
-            "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
-            '-   Do a proper analysis of the current functionality before you start implementing.',
-            '-   You are working with the [Agents Server](apps/agents-server)',
-            '-   If you need to do the database migration, do it',
-            '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
-        ]),
+        content: spaceTrim$1(`
+            -   @@@
+            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
+            -   Do a proper analysis of the current functionality before you start implementing.
+            -   You are working with the [Agents Server](apps/agents-server)
+            -   If you need to do the database migration, do it
+            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+        `),
         isDefaultProjectTemplate: false,
     },
 ];
@@ -40539,12 +40559,6 @@ function normalizeCoderPromptTemplateOption(templateOption) {
 function getDefaultCoderPromptTemplateDefinitionOrUndefined(template) {
     return DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS.find((definition) => definition.id === template);
 }
-/**
- * Builds stable markdown content for one coder prompt template without indentation drift.
- */
-function buildCoderPromptTemplateContent(lines) {
-    return lines.join('\n');
-}
 /**
  * Creates a fully resolved template payload from one built-in definition.
  */
@@ -41471,7 +41485,7 @@ function $initializeCoderRunCommand(program) {
     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('--limit <run-count>', 'Stop after processing this many prompt runs', createPositiveIntegerOptionParser('--limit'));
     command.option('--wait-after-prompt <duration>', spaceTrim$1(`
             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).
@@ -41558,22 +41572,6 @@ function parseIntOption$1(value) {
     }
     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$1(`
-                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.
  *
@@ -69846,23 +69844,28 @@ async function analyzeSourceFileForRefactorCandidate(options) {
     const extension = extname(filePath).toLowerCase();
     const relativePath = normalizeRefactorCandidatePath(relative(rootDir, filePath));
     const reasons = [];
+    let severityScore = 0;
     if (!lineCountExemptPaths.has(normalizedAbsolutePath)) {
         const lineCount = countLines(content);
         const maxLines = getMaxLinesForExtension(extension, heuristics);
         if (lineCount > maxLines) {
             reasons.push(`lines ${lineCount}/${maxLines}`);
+            severityScore += lineCount / maxLines;
         }
     }
     if (STRUCTURAL_ANALYSIS_EXTENSIONS.includes(extension)) {
         const structureSummary = summarizeSourceFileStructure(content, extension, filePath);
         if (structureSummary.entityCount > heuristics.maxEntityCountPerFile) {
             reasons.push(`entities ${structureSummary.entityCount}/${heuristics.maxEntityCountPerFile}`);
+            severityScore += structureSummary.entityCount / heuristics.maxEntityCountPerFile;
         }
         if (structureSummary.functionCount > heuristics.maxFunctionCountPerFile) {
             reasons.push(`functions ${structureSummary.functionCount}/${heuristics.maxFunctionCountPerFile}`);
+            severityScore += structureSummary.functionCount / heuristics.maxFunctionCountPerFile;
         }
         if (structureSummary.maxFunctionComplexity > heuristics.maxFunctionComplexity) {
             reasons.push(buildComplexityReason(structureSummary, heuristics.maxFunctionComplexity));
+            severityScore += structureSummary.maxFunctionComplexity / heuristics.maxFunctionComplexity;
         }
     }
     if (reasons.length === 0) {
@@ -69872,6 +69875,7 @@ async function analyzeSourceFileForRefactorCandidate(options) {
         absolutePath: filePath,
         relativePath,
         reasons,
+        severityScore,
     };
 }
 /**
@@ -70331,6 +70335,37 @@ async function isExistingFile(filePath) {
 }
 // Note: [🟡] Code for repository script [resolveRefactorCandidateProject](scripts/find-refactor-candidates/resolveRefactorCandidateProject.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Keeps at most `limit` refactor candidates, preferring the most important ones.
+ *
+ * When there are more candidates than `limit`, only the highest-severity candidates are kept
+ * (ties broken by relative path for determinism). When `limit` is `undefined` or there are fewer
+ * candidates than the limit, every candidate is returned. The original input order is preserved
+ * among the kept candidates, so `limit` acts purely as a filter and never reorders prompts.
+ *
+ * @private function of findRefactorCandidates
+ */
+function selectMostImportantRefactorCandidates(candidates, limit) {
+    if (limit === undefined || candidates.length <= limit) {
+        return candidates;
+    }
+    const candidatesRankedByImportance = [...candidates].sort(compareRefactorCandidatesByImportance);
+    const keptRelativePaths = new Set(candidatesRankedByImportance.slice(0, limit).map((candidate) => candidate.relativePath));
+    return candidates.filter((candidate) => keptRelativePaths.has(candidate.relativePath));
+}
+/**
+ * Orders refactor candidates from most to least important.
+ *
+ * @private function of selectMostImportantRefactorCandidates
+ */
+function compareRefactorCandidatesByImportance(candidateA, candidateB) {
+    if (candidateB.severityScore !== candidateA.severityScore) {
+        return candidateB.severityScore - candidateA.severityScore;
+    }
+    return candidateA.relativePath.localeCompare(candidateB.relativePath);
+}
+// Note: [🟡] Code for repository script [selectMostImportantRefactorCandidates](scripts/find-refactor-candidates/selectMostImportantRefactorCandidates.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Calculates the next available prompt numbering sequence for a month.
  */
@@ -70654,7 +70689,7 @@ function initializeFindRefactorCandidatesRun() {
  * @public exported from `@promptbook/cli`
  */
 async function findRefactorCandidates(options = {}) {
-    const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = options;
+    const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = options;
     const heuristics = getRefactorCandidateLevelConfiguration(level);
     initializeFindRefactorCandidatesRun();
     console.info(colors.cyan('⚡🏭 Find refactor candidates'));
@@ -70678,8 +70713,10 @@ async function findRefactorCandidates(options = {}) {
         console.info(colors.green('All candidates already have prompts.'));
         return;
     }
+    const selectedCandidatesToWrite = selectMostImportantRefactorCandidates(candidatesToWrite, limit);
+    const skippedByLimit = candidatesToWrite.length - selectedCandidatesToWrite.length;
     const createdPrompts = await writeRefactorCandidatePrompts({
-        candidates: candidatesToWrite,
+        candidates: selectedCandidatesToWrite,
         rootDir,
         promptsDir,
     });
@@ -70687,6 +70724,9 @@ async function findRefactorCandidates(options = {}) {
     if (alreadyTracked > 0) {
         console.info(colors.gray(`Skipped ${alreadyTracked} candidate(s) with existing prompts.`));
     }
+    if (skippedByLimit > 0) {
+        console.info(colors.gray(`Skipped ${skippedByLimit} lower-priority candidate(s) because of \`--limit ${limit}\`.`));
+    }
 }
 /**
  * Prints discovered refactor candidates with their reasons.
@@ -71938,8 +71978,7 @@ function mapColorToAnsi256(color) {
         if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
             return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
         }
-        return (232 +
-            Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN));
+        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
     }
     const redIndex = Math.round((red / 255) * 5);
     const greenIndex = Math.round((green / 255) * 5);