@alphafox/cli 0.3.8 → 0.3.9

package/dist/cache/clean.d.ts

@@ -0,0 +1 @@
+export declare function removeCacheRoot(directory: string, env?: NodeJS.ProcessEnv): void;

package/dist/cache/clean.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeCacheRoot = removeCacheRoot;
+const node_fs_1 = require("node:fs");
+const paths_1 = require("./paths");
+function removeCacheRoot(directory, env = process.env) {
+    (0, paths_1.assertSafeCacheRoot)(directory, env);
+    if (!(0, node_fs_1.existsSync)(directory)) {
+        return;
+    }
+    (0, node_fs_1.rmSync)(directory, { recursive: true, force: true });
+}

package/dist/cache/inspect.d.ts

@@ -0,0 +1,7 @@
+export interface DirectoryUsage {
+    readonly path: string;
+    readonly exists: boolean;
+    readonly bytes: number;
+    readonly files: number;
+}
+export declare function inspectDirectory(path: string): DirectoryUsage;

package/dist/cache/inspect.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectDirectory = inspectDirectory;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function inspectDirectory(path) {
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return { path, exists: false, bytes: 0, files: 0 };
+    }
+    const root = (0, node_fs_1.statSync)(path);
+    if (root.isFile()) {
+        return { path, exists: true, bytes: root.size, files: 1 };
+    }
+    let bytes = 0;
+    let files = 0;
+    const walk = (dir) => {
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            const next = (0, node_path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(next);
+                continue;
+            }
+            if (entry.isFile()) {
+                files += 1;
+                bytes += (0, node_fs_1.statSync)(next).size;
+            }
+        }
+    };
+    walk(path);
+    return { path, exists: true, bytes, files };
+}

package/dist/cache/paths.d.ts

@@ -0,0 +1,5 @@
+/** Remind Agents to offer cleanup at or above this tape-cache size. */
+export declare const TAPE_CACHE_REMIND_BYTES: number;
+export declare function resolveTapeCacheDir(env?: NodeJS.ProcessEnv): string;
+export declare function resolveRuntimeCacheRoot(env?: NodeJS.ProcessEnv): string;
+export declare function assertSafeCacheRoot(directory: string, env?: NodeJS.ProcessEnv): void;

package/dist/cache/paths.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAPE_CACHE_REMIND_BYTES = void 0;
+exports.resolveTapeCacheDir = resolveTapeCacheDir;
+exports.resolveRuntimeCacheRoot = resolveRuntimeCacheRoot;
+exports.assertSafeCacheRoot = assertSafeCacheRoot;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** Remind Agents to offer cleanup at or above this tape-cache size. */
+exports.TAPE_CACHE_REMIND_BYTES = 512 * 1024 * 1024;
+function resolveTapeCacheDir(env = process.env) {
+    const override = env.ALPHAFOX_TAPE_CACHE_DIR?.trim();
+    if (override) {
+        return (0, node_path_1.resolve)(override);
+    }
+    return (0, node_path_1.resolve)((0, node_path_1.join)((0, node_os_1.homedir)(), ".alphafox", "cache", "engine-backtest"));
+}
+function resolveRuntimeCacheRoot(env = process.env) {
+    const override = env.ALPHAFOX_BACKTEST_RUNTIME_CACHE_DIR?.trim();
+    if (override) {
+        return (0, node_path_1.resolve)(override);
+    }
+    const xdg = env.XDG_CACHE_HOME?.trim();
+    return (0, node_path_1.resolve)((0, node_path_1.join)(xdg || (0, node_path_1.join)((0, node_os_1.homedir)(), ".cache"), "alphafox", "engine-backtest"));
+}
+function assertSafeCacheRoot(directory, env = process.env) {
+    const resolved = (0, node_path_1.resolve)(directory);
+    const tape = resolveTapeCacheDir(env);
+    const runtime = resolveRuntimeCacheRoot(env);
+    if (resolved === tape || resolved === runtime) {
+        return;
+    }
+    if ((0, node_path_1.basename)(resolved) === "engine-backtest") {
+        return;
+    }
+    throw Object.assign(new Error(`Refusing to touch cache directory ${resolved}`), {
+        type: "usage",
+        subtype: "cache_root_unsafe",
+        status: 400,
+    });
+}

package/dist/cache/run-command.d.ts

@@ -0,0 +1,7 @@
+export interface CacheCliFlags {
+    readonly format: "json" | "jsonl" | "text";
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+    readonly jq?: string;
+}
+export declare function cmdCache(args: string[], flags: CacheCliFlags, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/cache/run-command.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdCache = cmdCache;
+const envelope_1 = require("../envelope");
+const clean_1 = require("./clean");
+const inspect_1 = require("./inspect");
+const paths_1 = require("./paths");
+async function cmdCache(args, flags, env = process.env) {
+    const sub = args[0];
+    if (sub === "status" || !sub || sub === "help" || sub === "--help" || sub === "-h") {
+        if (sub === "help" || sub === "--help" || sub === "-h") {
+            (0, envelope_1.writeSuccess)({
+                name: "cache",
+                usage: [
+                    "alphafox cache status",
+                    "alphafox cache clean [--tape|--runtime|--all] [--yes|--dry-run]",
+                ],
+            }, { format: flags.format, jq: flags.jq });
+            return 0;
+        }
+        const tape = (0, inspect_1.inspectDirectory)((0, paths_1.resolveTapeCacheDir)(env));
+        const runtime = (0, inspect_1.inspectDirectory)((0, paths_1.resolveRuntimeCacheRoot)(env));
+        (0, envelope_1.writeSuccess)({
+            tape: { ...tape, large: tape.bytes >= paths_1.TAPE_CACHE_REMIND_BYTES },
+            runtime,
+            remindAfterBytes: paths_1.TAPE_CACHE_REMIND_BYTES,
+            totalBytes: tape.bytes + runtime.bytes,
+        }, { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    if (sub === "clean") {
+        const rest = args.slice(1);
+        const all = rest.includes("--all");
+        const runtimeOnly = rest.includes("--runtime");
+        const tapeOnly = rest.includes("--tape") || (!all && !runtimeOnly);
+        const clearTape = all || tapeOnly;
+        const clearRuntime = all || runtimeOnly;
+        const tapePath = (0, paths_1.resolveTapeCacheDir)(env);
+        const runtimePath = (0, paths_1.resolveRuntimeCacheRoot)(env);
+        const tapeBefore = (0, inspect_1.inspectDirectory)(tapePath);
+        const runtimeBefore = (0, inspect_1.inspectDirectory)(runtimePath);
+        if (flags.dryRun) {
+            (0, envelope_1.writeSuccess)({
+                dryRun: true,
+                cleared: [
+                    ...(clearTape ? ["tape"] : []),
+                    ...(clearRuntime ? ["runtime"] : []),
+                ],
+                tape: tapeBefore,
+                runtime: runtimeBefore,
+            }, { format: flags.format, jq: flags.jq });
+            return 0;
+        }
+        if (!flags.yes) {
+            (0, envelope_1.writeError)({
+                type: "confirmation",
+                subtype: "yes_required",
+                message: "Cleaning local backtest cache requires --yes (or --dry-run).",
+                status: 400,
+            });
+        }
+        if (clearTape) {
+            (0, clean_1.removeCacheRoot)(tapePath, env);
+        }
+        if (clearRuntime) {
+            (0, clean_1.removeCacheRoot)(runtimePath, env);
+        }
+        (0, envelope_1.writeSuccess)({
+            dryRun: false,
+            cleared: [
+                ...(clearTape ? ["tape"] : []),
+                ...(clearRuntime ? ["runtime"] : []),
+            ],
+            tape: (0, inspect_1.inspectDirectory)(tapePath),
+            runtime: (0, inspect_1.inspectDirectory)(runtimePath),
+            bytesFreed: (clearTape ? tapeBefore.bytes : 0) +
+                (clearRuntime ? runtimeBefore.bytes : 0),
+        }, { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    (0, envelope_1.writeError)({
+        type: "usage",
+        message: "Usage: alphafox cache status|clean",
+    });
+}

package/dist/commands/run.js

@@ -14,11 +14,12 @@ const client_1 = require("../http/client");
 const store_1 = require("../keychain/store");
 const confirmation_1 = require("../safety/confirmation");
 const version_1 = require("../version");
-const run_command_1 = require("../engine-backtest/run-command");
-const run_command_2 = require("../resolve-symbols/run-command");
-const run_command_3 = require("../skills/run-command");
+const run_command_1 = require("../cache/run-command");
+const run_command_2 = require("../engine-backtest/run-command");
+const run_command_3 = require("../resolve-symbols/run-command");
+const run_command_4 = require("../skills/run-command");
 const notify_1 = require("../update/notify");
-const run_command_4 = require("../update/run-command");
+const run_command_5 = require("../update/run-command");
 const validate_body_1 = require("../catalog/validate-body");
 const types_1 = require("../install/types");
 const wizard_1 = require("../install/wizard");
@@ -102,6 +103,7 @@ async function runCli(argv, env = process.env) {
                 "alphafox api METHOD PATH [--body JSON|--config @file]",
                 "alphafox engine-backtest run --experiment <uuid> --definition <id> --config @file --exchange <id> --range FROM..TO --initial-equity N",
                 "alphafox engine-backtest sweep --experiment <uuid> --definition <id> --config @file --axes @file --exchange <id> --range FROM..TO --initial-equity N --no-persist",
+                "alphafox cache status|clean [--tape|--runtime|--all]",
                 "alphafox resolve-symbols <query...> [--exchange binance] [--asset-class equity_perp]",
                 "alphafox <domain> <resource> <action> [flags]",
             ],
@@ -120,7 +122,8 @@ async function runCli(argv, env = process.env) {
         if (cmd !== "version" &&
             cmd !== "install" &&
             cmd !== "update" &&
-            cmd !== "skills") {
+            cmd !== "skills" &&
+            cmd !== "cache") {
             assertCatalogCompatible();
         }
         switch (cmd) {
@@ -129,9 +132,11 @@ async function runCli(argv, env = process.env) {
             case "install":
                 return await cmdInstall(args, flags, env);
             case "update":
-                return await (0, run_command_4.cmdUpdate)(args, flags, env);
+                return await (0, run_command_5.cmdUpdate)(args, flags, env);
             case "skills":
-                return await (0, run_command_3.cmdSkills)(args, flags, env);
+                return await (0, run_command_4.cmdSkills)(args, flags, env);
+            case "cache":
+                return await (0, run_command_1.cmdCache)(args, flags, env);
             case "doctor":
                 return cmdDoctor(flags, env);
             case "whoami":
@@ -154,7 +159,7 @@ async function runCli(argv, env = process.env) {
                     sub === "help" ||
                     sub === "--help" ||
                     sub === "-h") {
-                    return await (0, run_command_1.cmdEngineBacktest)(args, flags, env);
+                    return await (0, run_command_2.cmdEngineBacktest)(args, flags, env);
                 }
                 // Hyphen built-in owns `run` and `sweep`. Underscore/hyphen catalog CRUD
                 // (engine_backtest.experiments.*) still goes through the typed tree.
@@ -162,7 +167,7 @@ async function runCli(argv, env = process.env) {
             }
             case "resolve-symbols":
             case "resolve-symbol":
-                return await (0, run_command_2.cmdResolveSymbols)(args, flags, env);
+                return await (0, run_command_3.cmdResolveSymbols)(args, flags, env);
             default:
                 return await cmdTyped(cmd, args, flags, env);
         }

package/dist/engine-backtest/run-command.js

@@ -14,6 +14,7 @@ const load_config_1 = require("./load-config");
 const parse_args_1 = require("./parse-args");
 const sweep_command_1 = require("./sweep-command");
 const persist_1 = require("./persist");
+const paths_1 = require("../cache/paths");
 const replay_timeframe_1 = require("./replay-timeframe");
 const resolve_packages_1 = require("./resolve-packages");
 var load_config_2 = require("./load-config");
@@ -316,6 +317,7 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
                 fromMs: args.range.fromMs,
                 toMs: args.range.toMs,
                 dataQualityMode: args.dataQualityMode,
+                cacheDir: (0, paths_1.resolveTapeCacheDir)(env),
                 onProgress: (progress) => {
                     emitProgress(flags, writeLine, progress.stage || "tape", progress.fraction, progress.detail);
                 },

package/dist/engine-backtest/sweep-command.js

@@ -7,6 +7,7 @@ exports.executeEngineBacktestSweep = executeEngineBacktestSweep;
 const node_crypto_1 = require("node:crypto");
 const profiles_1 = require("../config/profiles");
 const client_1 = require("../http/client");
+const paths_1 = require("../cache/paths");
 const store_1 = require("../keychain/store");
 const errors_1 = require("./errors");
 const load_config_1 = require("./load-config");
@@ -189,6 +190,7 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
                     fromMs: args.range.fromMs,
                     toMs: args.range.toMs,
                     dataQualityMode: args.dataQualityMode,
+                    cacheDir: (0, paths_1.resolveTapeCacheDir)(env),
                     onProgress: (progress) => {
                         emitProgress(flags, writeLine, progress.stage || "tape", progress.fraction, progress.detail);
                     },

package/dist/engine-backtest/types.d.ts

@@ -238,6 +238,7 @@ export interface BacktestRunnerModule {
         readonly fromMs: number;
         readonly toMs: number;
         readonly dataQualityMode?: DataQualityMode;
+        readonly cacheDir?: string;
         readonly onProgress?: (progress: TapeLoadProgress) => void;
     }, options?: unknown): Promise<TapeLoadResult>;
     assembleScenario(input: {

package/dist/skills-manifest.json

@@ -1,141 +1,153 @@
 {
   "schemaVersion": 1,
   "packageName": "@alphafox/cli",
-  "packageVersion": "0.3.8",
+  "packageVersion": "0.3.9",
   "contractVersion": "2026-08-13",
-  "bundleHash": "cd05f4eb6f9e1a7c9188ac5770196698c6f2c9ff6aaebfbfbaba3581ef08d226",
+  "bundleHash": "8693bb9b1b6f0c0bd70f75fe564a09ba829726f6e982d05c90a6595e8c36b715",
   "skills": [
     {
       "name": "alphafox",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "e8eadf96f36f6aa124b36d15a912465e839389e5228dbf9dfd9ad2f1ec86f65a",
-          "size": 3553
+          "sha256": "cb9f92b75cce3a03d4f2a9492b6ddd564541828bdb74acaf360cb3f2a0aa8447",
+          "size": 4405
         }
       ],
-      "hash": "fb41a55fcd363231cb69e30e4c0fe7b1ad2e17b12e2bb90cfda7d6e9ccd2f02c"
+      "hash": "92b330a3f902405235e2a049ce6c98a7cad705f8aeab6ba3c2062df33b222aec"
     },
     {
       "name": "alphafox-account",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "9925573bf644b998ea683df7a20276a835d33cb83b0548ee0d1c43429ad99582",
+          "sha256": "4ea9c43c579ce7b4a4e5dd0e0ca10eeb793d19fc64e1cf8c4760b6d426524bf6",
           "size": 783
         }
       ],
-      "hash": "934bcd76d1bea875324673ffcc3d1c52e3f4065f776c4958ffc230cf911bac21"
+      "hash": "a94dc7e2e7a958394dbebba5b02e25c7114116b0b1a265be6b544e92f5e4ea65"
     },
     {
       "name": "alphafox-admin",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "e9ae0b433cead54e9c284f0ea8859dd9e96123f842788938319404b96bc085e7",
+          "sha256": "6c800c87dd98fc054508ffc179fce19f455cc2da762525accadf2b1fda68e647",
           "size": 787
         }
       ],
-      "hash": "1346e798f18582c16cfbb887667272406f170e775d3027131d3d88e1f1a656e3"
+      "hash": "534d66e2614677fa7e40d3334f2e6992c632dccffc623c9dfcd963ae49eb66ac"
     },
     {
       "name": "alphafox-auth",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "8ec9f081d9a1d40606ac7c18cba5dae9f1b6144ddc0079005b16af54be8f2f46",
+          "sha256": "a12ab3e613b26246ef6eb8d1289307c266d3c82861a8d6567856d63dff47cd6d",
           "size": 2370
         }
       ],
-      "hash": "854910a6792aa6d0a8b9cd796afb41753a34cef79df95c5b50de432f03a4e67a"
+      "hash": "e4b6b6f1dc76681e37c1a71ecaa10ab985b4dcc04ca5b2eca8bfcec367076a02"
+    },
+    {
+      "name": "alphafox-cache",
+      "version": "0.3.9",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "cceafb6d8d0017090eedb5be82dd13fe2c26963531c5e92f49d1ed7ba948fc5b",
+          "size": 1529
+        }
+      ],
+      "hash": "f858ee9c3e27c56035cede0f7a6929fc5128573a718762802fba67b7c9d6103a"
     },
     {
       "name": "alphafox-engine-backtest",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "e5f37b8541c510a27f84cbf9eea7524efe0b8f9c60c4faf17521b6cac298f92b",
-          "size": 7584
+          "sha256": "8751aa7218862c44b4635d72a02a31752e400a67b41adec03aea77678a087c48",
+          "size": 7802
         }
       ],
-      "hash": "efb614f145763f514c33d02e112657bd42868cc746f13dbcb3cceaa0ecb770e4"
+      "hash": "2bab573fa07f5c5c1d83eb2e66d96d06abbff723e62f6b84a2de30a6ccf42339"
     },
     {
       "name": "alphafox-exchange",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "118141754916741f4f8b449cf307a89cdfa11f234302726ba4d6b58e396327b5",
+          "sha256": "416999214b3e99a9bbb3653286b2eefadbb7721da00762921e2c702de17f112a",
           "size": 743
         }
       ],
-      "hash": "3933f12a2d8c55db465d4a11cf1f7d40f90fff81b3931f398e2fe3bcaf064d62"
+      "hash": "988bdad202ba2e522d5d025339ed354063ada77ae56b0d2616963e13df659d83"
     },
     {
       "name": "alphafox-market",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "0e77dcc697fe60f742e1075986685db5018d9d659a4d8f44f9cc343117c1c74b",
+          "sha256": "5181ca01a222ae17c3e8feb711211c4150f59745b1559da5537a5b42ff4439b9",
           "size": 3078
         }
       ],
-      "hash": "710c45c6124583d3fa9c9584f67bbc665bad35c9e6d1294c7416f493b8a6b184"
+      "hash": "29f11a29419e5443593255e07bc6055fe3d15e165ef5e442c550f56845dcb12d"
     },
     {
       "name": "alphafox-notification",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "712aa6a4de8090bb7ee57373d35dd95c62bad7a24e443747afa4f11fb6e79b68",
+          "sha256": "0f027ae12e13832a2d267bdf276a59882dc42396d45d31e6a43424d514209906",
           "size": 698
         }
       ],
-      "hash": "5f2feef0e17912a593bafae0961f983e3f781d12800e4808c136004897321ab2"
+      "hash": "f8aa26444dd99e3374999086ab2956ce82156de2aab4c40a97a654082f899a29"
     },
     {
       "name": "alphafox-shared",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "c6bab01f9c8369f9c2a29eebf7b46462887f14d3bec7ad00e2a159d395346508",
+          "sha256": "896e71ca6da5f82b9c857486be8225a623a2e3a01be1a807db4d21d209c69a18",
           "size": 5385
         }
       ],
-      "hash": "2b78fe080877af19b659964a8c965720e5ab731dd157ced10d2ee598b8c574a0"
+      "hash": "fc69c60e86b01d917f0a513d20643331d29ed2a7baa15577cd19f049b8f8b24a"
     },
     {
       "name": "alphafox-strategy",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "03f1d1c6d048d7b0a23d725c6585d1d019445579be9779dc93095ebafb3fcf5a",
+          "sha256": "bbdba03e06c56e5fd35700071841e04a45c9b04d43727ba599bfbecf2fd77e1e",
           "size": 1826
         }
       ],
-      "hash": "ebf375c6eeaf13c971a3090d05beda7037f253325ee2236c35b26ad540922827"
+      "hash": "fb5847c1d8d0229d7b0d3598dbb26e1104be250dfe3a62d1759354c3ecba3e3d"
     },
     {
       "name": "alphafox-trading",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "4b597f23ff6c8ce384e8fd56fab73c6128d373741285bac6df0b061e7ee50242",
+          "sha256": "454102427cbb7ec119265c0c38adc9acd822881e23fad725b49f693c32ed19e3",
           "size": 3122
         }
       ],
-      "hash": "d7e818482ec3ba9aeab50af72e72f990288f0e2e6714e1227cba441db05fa75a"
+      "hash": "4768ca40fba0d940bf8425dc544f9501c9c5bca5a920fc942247eb7557ec9dcf"
     }
   ]
 }

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 export declare const CLI_NAME = "alphafox";
 export declare const CLI_PACKAGE = "@alphafox/cli";
-export declare const CLI_VERSION = "0.3.8";
+export declare const CLI_VERSION = "0.3.9";
 export { CATALOG_VERSION as CLI_CONTRACT_VERSION } from "./catalog/operations";

package/dist/version.js

@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLI_CONTRACT_VERSION = exports.CLI_VERSION = exports.CLI_PACKAGE = exports.CLI_NAME = void 0;
 exports.CLI_NAME = "alphafox";
 exports.CLI_PACKAGE = "@alphafox/cli";
-exports.CLI_VERSION = "0.3.8";
+exports.CLI_VERSION = "0.3.9";
 var operations_1 = require("./catalog/operations");
 Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return operations_1.CATALOG_VERSION; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphafox/cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "AlphaFox CLI — Agent/Human entry for the public Application API.",
   "type": "commonjs",
   "bin": {

package/skills/account/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-account
 description: Account, wallet, and subscription read paths.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Account / wallet

package/skills/admin/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-admin
 description: Admin-only operations reusing Web role authorization.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Admin

package/skills/alphafox/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox
-description: AlphaFox CLI entry router. Use for any AlphaFox request — install, update, login, whoami, 回测, engine backtest, strategy definitions, create/list/start/stop a running strategy (trader), ticker/标的 resolve (美股 or crypto), market data, exchange connectors, wallet, subscriptions, notifications, or admin. If a CLI command prints `[alphafox] update available`, ask the user「检测到新的版本，是否需要我帮你升级？」and only then run `alphafox update --format json --no-input`. Start here, then open the routed domain skill. Do not guess alphafox-engine-backtest vs alphafox-strategy vs alphafox-trading from memory.
-version: 0.3.8
+description: AlphaFox CLI entry router. Use for any AlphaFox request — install, update, login, whoami, 回测, engine backtest, 清理回测缓存 / 历史数据, strategy definitions, create/list/start/stop a running strategy (trader), ticker/标的 resolve (美股 or crypto), market data, exchange connectors, wallet, subscriptions, notifications, or admin. If a CLI command prints `[alphafox] update available`, ask the user「检测到新的版本，是否需要我帮你升级？」and only then run `alphafox update --format json --no-input`. After a large backtest, if tape cache is large, ask「回测下载的历史数据比较大，要不要我帮你清理本地缓存？」then open `alphafox-cache`. Start here, then open the routed domain skill. Do not guess alphafox-engine-backtest vs alphafox-strategy vs alphafox-trading from memory.
+version: 0.3.9
 ---
 
 # AlphaFox
@@ -22,6 +22,7 @@ A **trader** is a running strategy instance (paper or live), not a person. Creat
 | Login, logout, whoami, profile, staging vs production | `alphafox-auth` |
 | Ticker / 标的 / 美股 / crypto / resolve a misspelled symbol | `alphafox-market` |
 | Engine WASM backtest, experiment, `engine-backtest run`, persist a local run | `alphafox-engine-backtest` |
+| 清理回测缓存 / 历史 K 线占磁盘 / `alphafox cache` | `alphafox-cache` |
 | Strategy types / definitions / validate config (grid, dca, copy, …) | `alphafox-strategy` |
 | Create, list, start, or stop a running strategy (trader), including copy | `alphafox-trading` |
 | Exchange connectors | `alphafox-exchange` |
@@ -36,7 +37,7 @@ If several rows apply, load **all** of them (typical: `alphafox-shared` + `alpha
 The CLI may print this on **stderr** at most once every 24 hours:
 
 ```text
-[alphafox] update available: 0.3.7 -> 0.3.8. After the user confirms, run: alphafox update --format json --no-input,
+[alphafox] update available: 0.3.8 -> 0.3.9. After the user confirms, run: alphafox update --format json --no-input,
 ```
 
 If you see that notice (or `updateAvailable: true` from `alphafox update --check`):
@@ -60,3 +61,13 @@ Do not install Skills from GitHub. Details and dry-run / check commands live in
 - Web `/api/v1/backtests` (`backtests.*`) is **not** a CLI surface. Do not call it via typed commands, `schema`, or `alphafox api`.
 
 Ambiguous “帮我回测” → `alphafox-engine-backtest`, after resolving symbols.
+
+## Large historical tape
+
+`engine-backtest run|sweep` downloads closed OHLCV into the local tape cache. After a long-range or 1m backtest (or whenever the operator mentions disk / 缓存), read `alphafox-cache` and run `alphafox cache status --format json --no-input`.
+
+If `data.tape.large` is true (tape ≥ `data.remindAfterBytes`):
+
+1. Ask the user: **回测下载的历史数据比较大，要不要我帮你清理本地缓存？**
+2. Wait for an explicit yes. Do not clean on your own.
+3. Follow `alphafox-cache` (`alphafox cache clean --dry-run`, then `--yes`).

package/skills/alphafox-shared/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-shared
 description: Shared AlphaFox CLI rules for Agents — auth, profiles, envelopes, risk gates, and public operationIds only.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # AlphaFox shared Agent contract

package/skills/auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-auth
 description: Login, status, logout, whoami, and environment isolation for AlphaFox CLI.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Auth Skill

package/skills/cache/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: alphafox-cache
+description: Inspect and clean local Engine backtest caches (downloaded OHLCV tape and wasm runtime). Use when the user asks to 清理缓存, free disk, or after a large historical backtest.
+version: 0.3.9
+---
+
+# Cache
+
+Always `--format json --no-input`. Never `--token`. This is local disk only.
+
+`engine-backtest run|sweep` writes closed OHLCV into the **tape** cache (`~/.alphafox/cache/engine-backtest`, or `ALPHAFOX_TAPE_CACHE_DIR`). The wasm / Node host lives under the **runtime** cache (`~/.cache/alphafox/engine-backtest/<hash>/`). Tape is the large historical download.
+
+## Status first
+
+```bash
+alphafox cache status --format json --no-input
+```
+
+Read `data.tape.bytes`, `data.tape.files`, `data.tape.large`, `data.remindAfterBytes`. `large` is true when tape bytes ≥ `remindAfterBytes` (512 MiB).
+
+If `data.tape.large` is true, ask the user:
+
+**回测下载的历史数据比较大，要不要我帮你清理本地缓存？**
+
+Wait for an explicit yes. Do not clean on your own.
+
+## Clean
+
+Default clean is **tape only** (historical bars). Runtime re-downloads on the next run; only add `--runtime` or `--all` when the operator asks.
+
+```bash
+alphafox cache clean --dry-run --format json --no-input
+alphafox cache clean --yes --format json --no-input
+```
+
+`--yes` is required to delete. `--dry-run` reports what would be removed. After clean, `data.bytesFreed` is the space recovered.
+
+Do not `rm` cache paths by hand. Do not delete `~/.config/alphafox` (config / skills state / keychain).

package/skills/engine-backtest/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-engine-backtest
 description: Local Engine WASM backtest (alphafox engine-backtest run|sweep) vs catalog experiment CRUD.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Engine Backtest
@@ -94,6 +94,7 @@ Owner isolation and 7-day expiry are enforced by the server. Applying a coordina
 2. `engine-backtest run` (reuse `--experiment` after the first create).
 3. Read `data.metrics` / `data.engineVersion` / `data.runId` / `data.experimentUrl`.
 4. Adjust parameters and run again. Do not invent a token flag if persist returns 401 — `alphafox auth login`.
+5. After a long-range or 1m run, follow `alphafox-cache`: `alphafox cache status`. If `data.tape.large` is true, ask **回测下载的历史数据比较大，要不要我帮你清理本地缓存？** and wait for yes.
 
 ## Safety
 

package/skills/exchange/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-exchange
 description: Exchange connectors list and connection management via Public API.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Exchange connectors

package/skills/market/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-market
 description: Market data and ticker resolution for US equity perps, RWAs, and crypto on the same perp catalog. Use when the user names 美股, NVDA, AAPL, BTC, or any 标的. Keep the operator's asset class via symbolMetadata — do not rewrite NVDA into a crypto coin.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Market

package/skills/notification/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-notification
 description: Notification channels and subscriptions.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Notification

package/skills/strategy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-strategy
 description: Strategy definitions — list types (grid, dca, copy, …) and validate config. Creating a running strategy is creating a trader; use alphafox-trading for that.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Strategy definitions

package/skills/trading/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-trading
 description: Running strategies (traders) — create, list, start, and stop. A trader is a live or paper strategy instance (grid, dca, copy, …), not a person.
-version: 0.3.8
+version: 0.3.9
 ---
 
 # Running strategies (traders)

package/vendor/backtest-runner/index.d.ts

@@ -288,6 +288,8 @@ export interface TapeLoadRequest {
   readonly signal?: AbortSignal;
   readonly onProgress?: (progress: TapeLoadProgress) => void;
   readonly nowMs?: number;
+  readonly cacheDir?: string;
+  readonly seriesConcurrency?: number;
   readonly ohlcvFetcher?: TapeOhlcvFetcher;
   readonly fundingFetcher?: TapeFundingFetcher;
   readonly marketsLoader?: () => Promise<TapeMarketsSnapshot>;
@@ -302,6 +304,8 @@ export interface TapeProxyOptions {
 export interface TapeLoadOptions extends TapeProxyOptions {
   readonly cache?: FileTapeCache | false | "disable";
   readonly cacheDir?: string;
+  /** Independent series fetches; default 4, hard cap 8. Pagination stays serial. */
+  readonly seriesConcurrency?: number;
   readonly nowMs?: number;
   readonly onProgress?: (progress: TapeLoadProgress) => void;
   readonly createExchange?: (
@@ -336,6 +340,17 @@ export interface TapeLoadResult {
   };
 }
 
+export const DEFAULT_TAPE_SERIES_CONCURRENCY: 4;
+export const MAX_TAPE_SERIES_CONCURRENCY: 8;
+
+export function resolveTapeSeriesConcurrency(value?: number): number;
+
+export function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<R>
+): Promise<R[]>;
+
 export function loadTape(
   request: TapeLoadRequest,
   options?: TapeLoadOptions

package/vendor/backtest-runner/index.mjs

@@ -50,8 +50,12 @@ export {
   loadSeriesWithCache,
 } from "./lib/series.mjs";
 export {
+  DEFAULT_TAPE_SERIES_CONCURRENCY,
+  MAX_TAPE_SERIES_CONCURRENCY,
   loadTape,
+  mapWithConcurrency,
   resolveTapeCache,
+  resolveTapeSeriesConcurrency,
   effectiveTapeEndMs,
   inferFundingIntervals,
   classifyTapeSymbolsForPreflight,

package/vendor/backtest-runner/lib/tape-loader.mjs

@@ -39,8 +39,47 @@ const FUNDING_INTERVALS = [
   { interval: "8h", spacingMs: 28_800_000 },
 ];
 
+/** Independent symbol×timeframe (and funding) fetches. Pagination stays serial. */
+export const DEFAULT_TAPE_SERIES_CONCURRENCY = 4;
+export const MAX_TAPE_SERIES_CONCURRENCY = 8;
+
 const exchangePromises = new Map();
 
+export function resolveTapeSeriesConcurrency(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 1) {
+    return Math.min(
+      MAX_TAPE_SERIES_CONCURRENCY,
+      Math.max(1, Math.floor(value))
+    );
+  }
+  return DEFAULT_TAPE_SERIES_CONCURRENCY;
+}
+
+export async function mapWithConcurrency(items, concurrency, worker) {
+  const list = [...items];
+  if (list.length === 0) {
+    return [];
+  }
+  const limit = Math.min(
+    list.length,
+    Math.max(1, Math.floor(Number(concurrency)) || 1)
+  );
+  const results = new Array(list.length);
+  let nextIndex = 0;
+  async function runWorker() {
+    while (true) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= list.length) {
+        return;
+      }
+      results[index] = await worker(list[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, () => runWorker()));
+  return results;
+}
+
 export function effectiveTapeEndMs(
   requestedToMs,
   nowMs = Date.now(),
@@ -141,7 +180,13 @@ export async function loadTape(request, options = {}) {
 
   const exchangeDefinition = resolveRequestExchange(request);
   const onProgress = request.onProgress ?? options.onProgress;
-  const cache = resolveTapeCache(options);
+  const cache = resolveTapeCache({
+    ...options,
+    cacheDir: options.cacheDir ?? request.cacheDir,
+  });
+  const seriesConcurrency = resolveTapeSeriesConcurrency(
+    options.seriesConcurrency ?? request.seriesConcurrency
+  );
   const dataQualityMode = request.dataQualityMode ?? "strict";
   const baseTimeframe = resolvePlanBaseTimeframe({
     baseTimeframe: request.baseTimeframe,
@@ -233,17 +278,36 @@ export async function loadTape(request, options = {}) {
   const buffers = {};
   const chartSeries = [];
   const series = [];
-  const totalSeries = request.symbols.length * timeframes.length;
+  const seriesJobs = request.symbols.flatMap((symbol) =>
+    timeframes.map((timeframe) => ({ symbol, timeframe }))
+  );
+  const totalSeries = seriesJobs.length;
   const dataIssues = [];
   const coverageWarnings = [];
-  let seriesDone = 0;
-  let bufferSequence = 0;
-  for (const symbol of request.symbols) {
-    for (const timeframe of timeframes) {
+  const seriesFractions = new Array(totalSeries).fill(0);
+  let lastOhlcvDetail = "";
+  const reportOhlcv = (index, fraction, detail) => {
+    seriesFractions[index] = fraction;
+    lastOhlcvDetail = detail;
+    const completed =
+      seriesFractions.reduce((sum, value) => sum + value, 0) / totalSeries;
+    onProgress?.({
+      stage: "ohlcv",
+      detail: lastOhlcvDetail,
+      fraction:
+        MARKETS_PROGRESS_END +
+        (OHLCV_PROGRESS_END - MARKETS_PROGRESS_END) * completed,
+    });
+  };
+  const loadedSeries = await mapWithConcurrency(
+    seriesJobs,
+    seriesConcurrency,
+    async (job, index) => {
       request.signal?.throwIfAborted();
-      let loaded;
+      const { symbol, timeframe } = job;
+      const detail = `${symbol} ${timeframe}`;
       try {
-        loaded = await loadSeriesWithCache(
+        const loaded = await loadSeriesWithCache(
           exchange,
           exchangeDefinition,
           runtimeConfig,
@@ -255,46 +319,51 @@ export async function loadTape(request, options = {}) {
           requirementWarmups.get(`${symbol}\u0000${timeframe}`) ?? 0,
           timeframe === baseTimeframe,
           dataQualityMode,
-          (fraction) => {
-            onProgress?.({
-              stage: "ohlcv",
-              detail: `${symbol} ${timeframe}`,
-              fraction:
-                MARKETS_PROGRESS_END +
-                (OHLCV_PROGRESS_END - MARKETS_PROGRESS_END) *
-                  ((seriesDone + fraction) / totalSeries),
-            });
-          },
+          (fraction) => reportOhlcv(index, fraction, detail),
           cacheUntilMs,
           cache,
           request.signal
         );
+        reportOhlcv(index, 1, detail);
+        return { ok: true, job, loaded };
       } catch (error) {
         request.signal?.throwIfAborted();
-        dataIssues.push(...toTapeDataIssues(error, symbol, timeframe));
-        seriesDone++;
-        continue;
-      }
-      if (loaded.softIssues.length > 0) {
-        coverageWarnings.push(
-          formatCoverageSoftWarning(loaded.softIssues, loaded.coverageRatio)
-        );
-      }
-      const { rows } = loaded;
-      const bufferKey = `k${bufferSequence++}`;
-      const buffer = encodeOhlcvColumns(rows);
-      buffers[bufferKey] = buffer;
-      if (timeframe === baseTimeframe) {
-        chartSeries.push({
-          symbol,
-          timeframe: baseTimeframe,
-          rows: rows.length,
-          buffer: buffer.slice(0),
-        });
+        reportOhlcv(index, 1, detail);
+        return {
+          ok: false,
+          issues: toTapeDataIssues(error, symbol, timeframe),
+        };
       }
-      series.push({ symbol, timeframe, buffer: bufferKey, rows: rows.length });
-      seriesDone++;
     }
+  );
+  let bufferSequence = 0;
+  for (const result of loadedSeries) {
+    if (!result.ok) {
+      dataIssues.push(...result.issues);
+      continue;
+    }
+    if (result.loaded.softIssues.length > 0) {
+      coverageWarnings.push(
+        formatCoverageSoftWarning(
+          result.loaded.softIssues,
+          result.loaded.coverageRatio
+        )
+      );
+    }
+    const { symbol, timeframe } = result.job;
+    const { rows } = result.loaded;
+    const bufferKey = `k${bufferSequence++}`;
+    const buffer = encodeOhlcvColumns(rows);
+    buffers[bufferKey] = buffer;
+    if (timeframe === baseTimeframe) {
+      chartSeries.push({
+        symbol,
+        timeframe: baseTimeframe,
+        rows: rows.length,
+        buffer: buffer.slice(0),
+      });
+    }
+    series.push({ symbol, timeframe, buffer: bufferKey, rows: rows.length });
   }
   if (dataIssues.length > 0) {
     throw new TapeDataUnavailableError(dataIssues);
@@ -302,19 +371,24 @@ export async function loadTape(request, options = {}) {
 
   let fundingRates;
   if (request.needsFunding) {
-    fundingRates = {};
-    for (const symbol of request.symbols) {
-      request.signal?.throwIfAborted();
-      fundingRates[symbol] = await loadFundingHistory(
-        exchange,
-        exchangeDefinition,
-        runtimeConfig,
-        symbol,
-        request.fromMs,
-        tapeToMs,
-        request.signal
-      );
-    }
+    const fundingEntries = await mapWithConcurrency(
+      request.symbols,
+      seriesConcurrency,
+      async (symbol) => {
+        request.signal?.throwIfAborted();
+        const samples = await loadFundingHistory(
+          exchange,
+          exchangeDefinition,
+          runtimeConfig,
+          symbol,
+          request.fromMs,
+          tapeToMs,
+          request.signal
+        );
+        return [symbol, samples];
+      }
+    );
+    fundingRates = Object.fromEntries(fundingEntries);
   }
   request.signal?.throwIfAborted();
   onProgress?.({