backtest-kit 3.0.18 → 3.1.1

package/build/index.mjs

@@ -422,6 +422,13 @@ const GLOBAL_CONFIG = {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: 50,
+    /**
+     * Enables mutex locking for candle fetching to prevent concurrent fetches of the same candles.
+     * This can help avoid redundant API calls and ensure data consistency when multiple processes/threads attempt to fetch candles simultaneously.
+     *
+     * Default: true (mutex locking enabled for candle fetching)
+     */
+    CC_ENABLE_CANDLE_FETCH_MUTEX: true,
 };
 const DEFAULT_CONFIG = Object.freeze({ ...GLOBAL_CONFIG });
 
@@ -692,7 +699,7 @@ async function writeFileAtomic(file, data, options = {}) {
     }
 }
 
-var _a$2;
+var _a$3;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
 const INTERVAL_MINUTES$8 = {
@@ -810,7 +817,7 @@ class PersistBase {
     constructor(entityName, baseDir = join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
-        this[_a$2] = singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
+        this[_a$3] = singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
         bt.loggerService.debug(PERSIST_BASE_METHOD_NAME_CTOR, {
             entityName: this.entityName,
             baseDir,
@@ -913,7 +920,7 @@ class PersistBase {
         }
     }
 }
-_a$2 = BASE_WAIT_FOR_INIT_SYMBOL;
+_a$3 = BASE_WAIT_FOR_INIT_SYMBOL;
 // @ts-ignore
 PersistBase = makeExtendable(PersistBase);
 /**
@@ -1920,6 +1927,69 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
+var _a$2, _b$2;
+const BUSY_DELAY = 100;
+const SET_BUSY_SYMBOL = Symbol("setBusy");
+const GET_BUSY_SYMBOL = Symbol("getBusy");
+const ACQUIRE_LOCK_SYMBOL = Symbol("acquireLock");
+const RELEASE_LOCK_SYMBOL = Symbol("releaseLock");
+const ACQUIRE_LOCK_FN = async (self) => {
+    while (self[GET_BUSY_SYMBOL]()) {
+        await sleep(BUSY_DELAY);
+    }
+    self[SET_BUSY_SYMBOL](true);
+};
+class Lock {
+    constructor() {
+        this._isBusy = 0;
+        this[_a$2] = queued(ACQUIRE_LOCK_FN);
+        this[_b$2] = () => this[SET_BUSY_SYMBOL](false);
+        this.acquireLock = async () => {
+            await this[ACQUIRE_LOCK_SYMBOL](this);
+        };
+        this.releaseLock = async () => {
+            await this[RELEASE_LOCK_SYMBOL]();
+        };
+    }
+    [SET_BUSY_SYMBOL](isBusy) {
+        this._isBusy += isBusy ? 1 : -1;
+        if (this._isBusy < 0) {
+            throw new Error("Extra release in finally block");
+        }
+    }
+    [GET_BUSY_SYMBOL]() {
+        return !!this._isBusy;
+    }
+}
+_a$2 = ACQUIRE_LOCK_SYMBOL, _b$2 = RELEASE_LOCK_SYMBOL;
+
+const METHOD_NAME_ACQUIRE_LOCK = "CandleUtils.acquireLock";
+const METHOD_NAME_RELEASE_LOCK = "CandleUtils.releaseLock";
+class CandleUtils {
+    constructor() {
+        this._lock = new Lock();
+        this.acquireLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_ACQUIRE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.acquireLock();
+        };
+        this.releaseLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_RELEASE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.releaseLock();
+        };
+    }
+}
+const Candle = new CandleUtils();
+
 const MS_PER_MINUTE$5 = 60000;
 const INTERVAL_MINUTES$7 = {
     "1m": 1,
@@ -2099,34 +2169,40 @@ const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$7[dto.interval];
     const sinceTimestamp = since.getTime();
     const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$5;
-    // Try to read from cache first
-    const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
-    if (cachedCandles !== null) {
-        return cachedCandles;
-    }
-    // Cache miss or error - fetch from API
-    let lastError;
-    for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
-        try {
-            const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit, self.params.execution.context.backtest);
-            VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
-            return result;
+    await Candle.acquireLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
+    try {
+        // Try to read from cache first
+        const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
+        if (cachedCandles !== null) {
+            return cachedCandles;
         }
-        catch (err) {
-            const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
-            const payload = {
-                error: errorData(err),
-                message: getErrorMessage(err),
-            };
-            self.params.logger.warn(message, payload);
-            console.warn(message, payload);
-            lastError = err;
-            await sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+        // Cache miss or error - fetch from API
+        let lastError;
+        for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
+            try {
+                const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit, self.params.execution.context.backtest);
+                VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
+                return result;
+            }
+            catch (err) {
+                const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
+                const payload = {
+                    error: errorData(err),
+                    message: getErrorMessage(err),
+                };
+                self.params.logger.warn(message, payload);
+                console.warn(message, payload);
+                lastError = err;
+                await sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+            }
         }
+        throw lastError;
+    }
+    finally {
+        Candle.releaseLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
     }
-    throw lastError;
 };
 /**
  * Wrapper to call onCandleData callback with error handling.
@@ -2809,8 +2885,9 @@ class ExchangeConnectionService {
  *
  * For signals with partial closes:
  * - Calculates weighted PNL: Σ(percent_i × pnl_i) for each partial + (remaining% × final_pnl)
- * - Each partial close has its own fees and slippage
- * - Total fees = 2 × (number of partial closes + 1 final close) × CC_PERCENT_FEE
+ * - Each partial close has its own slippage
+ * - Open fee is charged once; close fees are proportional to each partial's size
+ * - Total fees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (closes sum to 100%) = 2 × CC_PERCENT_FEE
  *
  * Formula breakdown:
  * 1. Apply slippage to open/close prices (worse execution)
@@ -2857,7 +2934,8 @@ const toProfitLossDto = (signal, priceClose) => {
     // Calculate weighted PNL with partial closes
     if (signal._partial && signal._partial.length > 0) {
         let totalWeightedPnl = 0;
-        let totalFees = 0;
+        // Open fee is paid once for the whole position
+        let totalFees = GLOBAL_CONFIG.CC_PERCENT_FEE;
         // Calculate PNL for each partial close
         for (const partial of signal._partial) {
             const partialPercent = partial.percent;
@@ -2884,8 +2962,8 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by percentage of position closed
             const weightedPnl = (partialPercent / 100) * partialPnl;
             totalWeightedPnl += weightedPnl;
-            // Each partial has fees for open + close (2 transactions)
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the size of this partial
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (partialPercent / 100);
         }
         // Calculate PNL for remaining position (if any)
         // Compute totalClosed from _partial array
@@ -2914,10 +2992,11 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by remaining percentage
             const weightedRemainingPnl = (remainingPercent / 100) * remainingPnl;
             totalWeightedPnl += weightedRemainingPnl;
-            // Final close also has fees
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the remaining size
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (remainingPercent / 100);
         }
         // Subtract total fees from weighted PNL
+        // totalFees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (all closes sum to 100%) = 2 × CC_PERCENT_FEE
         const pnlPercentage = totalWeightedPnl - totalFees;
         return {
             pnlPercentage,
@@ -26307,55 +26386,61 @@ class ExchangeInstance {
             const sinceTimestamp = alignedWhen - limit * stepMs;
             const since = new Date(sinceTimestamp);
             const untilTimestamp = alignedWhen;
-            // Try to read from cache first
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            let allData = [];
-            // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
-            if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = limit;
-                let currentSince = new Date(since.getTime());
-                const isBacktest = await GET_BACKTEST_FN();
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        // Move currentSince forward by the number of candles fetched
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
+            try {
+                // Try to read from cache first
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                let allData = [];
+                // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
+                if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = limit;
+                    let currentSince = new Date(since.getTime());
+                    const isBacktest = await GET_BACKTEST_FN();
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            // Move currentSince forward by the number of candles fetched
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    const isBacktest = await GET_BACKTEST_FN();
+                    allData = await getCandles(symbol, interval, since, limit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
+                        `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== limit) {
+                    throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
+                        `Expected ${limit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                const isBacktest = await GET_BACKTEST_FN();
-                allData = await getCandles(symbol, interval, since, limit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
-                    `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== limit) {
-                throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
-                    `Expected ${limit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
-            return uniqueData;
         };
         /**
          * Calculates VWAP (Volume Weighted Average Price) from last N 1m candles.
@@ -26589,56 +26674,62 @@ class ExchangeInstance {
                     `Provide one of: (sDate+eDate+limit), (sDate+eDate), (eDate+limit), (sDate+limit), or (limit only). ` +
                     `Got: sDate=${sDate}, eDate=${eDate}, limit=${limit}`);
             }
-            // Try to read from cache first
-            const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            // Fetch candles
-            const since = new Date(sinceTimestamp);
-            let allData = [];
-            const isBacktest = await GET_BACKTEST_FN();
-            const getCandles = this._methods.getCandles;
-            if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = calculatedLimit;
-                let currentSince = new Date(since.getTime());
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
+            try {
+                // Try to read from cache first
+                const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                // Fetch candles
+                const since = new Date(sinceTimestamp);
+                let allData = [];
+                const isBacktest = await GET_BACKTEST_FN();
+                const getCandles = this._methods.getCandles;
+                if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = calculatedLimit;
+                    let currentSince = new Date(since.getTime());
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
+                        `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== calculatedLimit) {
+                    throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
+                        `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
-                    `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== calculatedLimit) {
-                throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
-                    `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
-            return uniqueData;
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
@@ -30125,6 +30216,115 @@ function listenStrategyCommitOnce(filterFn, fn) {
     return strategyCommitSubject.filter(filterFn).once(fn);
 }
 
+const WARN_KB = 30;
+const DUMP_MESSAGES_METHOD_NAME = "dump.dumpMessages";
+/**
+ * Dumps chat history and result data to markdown files in a structured directory.
+ *
+ * Creates a subfolder named after `resultId` inside `outputDir`.
+ * If the subfolder already exists, the function returns early without overwriting.
+ * Writes:
+ * - `00_system_prompt.md` — system messages and output data summary
+ * - `NN_user_message.md` — each user message as a separate file
+ * - `NN_llm_output.md` — final LLM output data
+ *
+ * Warns via logger if any user message exceeds 30 KB.
+ *
+ * @param resultId - Unique identifier for the result (used as subfolder name)
+ * @param history - Full chat history containing system, user, and assistant messages
+ * @param result - Structured output data to include in the dump
+ * @param outputDir - Base directory for output files (default: `./dump/strategy`)
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpMessages } from "backtest-kit";
+ *
+ * await dumpMessages("result-123", history, { profit: 42 });
+ * ```
+ */
+async function dumpMessages(resultId, history, result, outputDir = "./dump/strategy") {
+    bt.loggerService.info(DUMP_MESSAGES_METHOD_NAME, {
+        resultId,
+        outputDir,
+    });
+    // Extract system messages and system reminders from existing data
+    const systemMessages = history.filter((m) => m.role === "system");
+    const userMessages = history.filter((m) => m.role === "user");
+    const subfolderPath = path.join(outputDir, String(resultId));
+    try {
+        await fs__default.access(subfolderPath);
+        return;
+    }
+    catch {
+        await fs__default.mkdir(subfolderPath, { recursive: true });
+    }
+    {
+        let summary = "# Outline Result Summary\n";
+        {
+            summary += "\n";
+            summary += `**ResultId**: ${resultId}\n`;
+            summary += "\n";
+        }
+        if (result) {
+            summary += "## Output Data\n\n";
+            summary += "```json\n";
+            summary += JSON.stringify(result, null, 2);
+            summary += "\n```\n\n";
+        }
+        // Add system messages to summary
+        if (systemMessages.length > 0) {
+            summary += "## System Messages\n\n";
+            systemMessages.forEach((msg, idx) => {
+                summary += `### System Message ${idx + 1}\n\n`;
+                summary += msg.content;
+                summary += "\n";
+            });
+        }
+        const summaryFile = path.join(subfolderPath, "00_system_prompt.md");
+        await fs__default.writeFile(summaryFile, summary, "utf8");
+    }
+    {
+        await Promise.all(Array.from(userMessages.entries()).map(async ([idx, message]) => {
+            const messageNum = String(idx + 1).padStart(2, "0");
+            const contentFileName = `${messageNum}_user_message.md`;
+            const contentFilePath = path.join(subfolderPath, contentFileName);
+            {
+                const messageSizeBytes = Buffer.byteLength(message.content, "utf8");
+                const messageSizeKb = Math.floor(messageSizeBytes / 1024);
+                if (messageSizeKb > WARN_KB) {
+                    console.warn(`User message ${idx + 1} is ${messageSizeBytes} bytes (${messageSizeKb}kb), which exceeds warning limit`);
+                    bt.loggerService.warn(DUMP_MESSAGES_METHOD_NAME, {
+                        resultId,
+                        messageIndex: idx + 1,
+                        messageSizeBytes,
+                        messageSizeKb,
+                    });
+                }
+            }
+            let content = `# User Input ${idx + 1}\n\n`;
+            content += `**ResultId**: ${resultId}\n\n`;
+            content += message.content;
+            content += "\n";
+            await fs__default.writeFile(contentFilePath, content, "utf8");
+        }));
+    }
+    {
+        const messageNum = String(userMessages.length + 1).padStart(2, "0");
+        const contentFileName = `${messageNum}_llm_output.md`;
+        const contentFilePath = path.join(subfolderPath, contentFileName);
+        let content = "# Full Outline Result\n\n";
+        content += `**ResultId**: ${resultId}\n\n`;
+        if (result) {
+            content += "## Output Data\n\n";
+            content += "```json\n";
+            content += JSON.stringify(result, null, 2);
+            content += "\n```\n";
+        }
+        await fs__default.writeFile(contentFilePath, content, "utf8");
+    }
+}
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_STOP = "BacktestUtils.stop";
@@ -37384,4 +37584,4 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "3.0.18",
+  "version": "3.1.1",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",