fix(agent): validate cache strategy configuration (#1272)

* fix(agent): validate cache strategy configuration

* chore(core): fix lint

* docs(site): cache startegy default value

* feat(web-integration): update cache type to support read-only and read-write strategies

---------

Co-authored-by: quanruzhuoxiu <[email protected]>

Author: yuyutaotao

apps/site/docs/en/caching.mdx

@@ -51,22 +51,33 @@ agent:
 
 ### Read-write mode
 
-Configuration: `cache: { id: "my-cache-id" }`
+Configuration: `cache: { id: "my-cache-id" }` or `cache: { strategy: "read-write", id: "my-cache-id" }`
 
-Automatically read existing cache and update cache files during execution.
+Automatically read existing cache and update cache files during execution. The default value of `strategy` is `read-write`.
 
 ```javascript
 // Direct Agent creation - explicit cache ID
 const agent = new PuppeteerAgent(page, {
   cache: { id: "my-cache-id" },
 });
+
+// Explicitly specify strategy
+const agent = new PuppeteerAgent(page, {
+  cache: { strategy: "read-write", id: "my-cache-id" },
+});
 ```
 
 ```yaml
 # YAML configuration - explicit cache ID
 agent:
   cache:
     id: "my-cache-test"
+
+# Explicitly specify strategy
+agent:
+  cache:
+    id: "my-cache-test"
+    strategy: "read-write"
 ```
 
 YAML mode also supports `cache: true` to automatically use the file name as the cache ID.

apps/site/docs/zh/caching.mdx

@@ -54,22 +54,33 @@ agent:
 
 ### 读写模式
 
-配置方式：`cache: { id: "my-cache-id" }`
+配置方式：`cache: { id: "my-cache-id" }` 或 `cache: { strategy: "read-write", id: "my-cache-id" }`
 
-自动读取已有缓存，执行过程中自动更新缓存文件。
+自动读取已有缓存，执行过程中自动更新缓存文件。`strategy` 的默认值是 `read-write`。
 
 ```javascript
 // 直接创建 Agent - 显式设置 cache ID
 const agent = new PuppeteerAgent(page, {
   cache: { id: "my-cache-id" },
 });
+
+// 显式指定 strategy
+const agent = new PuppeteerAgent(page, {
+  cache: { strategy: "read-write", id: "my-cache-id" },
+});
 ```
 
 ```yaml
 # YAML 配置 - 显式设置 cache ID
 agent:
   cache:
     id: "my-cache-test"
+
+# 显式指定 strategy
+agent:
+  cache:
+    id: "my-cache-test"
+    strategy: "read-write"
 ```
 
 YAML 模式还支持配置 `cache: true`，自动使用文件名作为 cache ID。

packages/core/src/agent/agent.ts

@@ -41,7 +41,7 @@ import {
 } from '../yaml/index';
 
 import type { AbstractInterface } from '@/device';
-import type { AgentOpt } from '@/types';
+import type { AgentOpt, CacheConfig } from '@/types';
 import {
   MIDSCENE_CACHE,
   ModelConfigManager,
@@ -81,6 +81,17 @@ const defaultInsightExtractOption: InsightExtractOption = {
   screenshotIncluded: true,
 };
 
+type CacheStrategy = NonNullable<CacheConfig['strategy']>;
+
+const CACHE_STRATEGIES: readonly CacheStrategy[] = ['read-only', 'read-write'];
+
+const isValidCacheStrategy = (strategy: string): strategy is CacheStrategy =>
+  CACHE_STRATEGIES.some((value) => value === strategy);
+
+const CACHE_STRATEGY_VALUES = CACHE_STRATEGIES.map(
+  (value) => `"${value}"`,
+).join(', ');
+
 export class Agent<
   InterfaceType extends AbstractInterface = AbstractInterface,
 > {
@@ -1079,9 +1090,26 @@ export class Agent<
           );
         }
         const id = config.id;
-        // Default strategy is 'read-write'
-        const strategy = config.strategy ?? 'read-write';
-        const isReadOnly = strategy === 'read-only';
+        const rawStrategy = config.strategy as unknown;
+        let strategyValue: string;
+
+        if (rawStrategy === undefined) {
+          strategyValue = 'read-write';
+        } else if (typeof rawStrategy === 'string') {
+          strategyValue = rawStrategy;
+        } else {
+          throw new Error(
+            `cache.strategy must be a string when provided, but received type ${typeof rawStrategy}`,
+          );
+        }
+
+        if (!isValidCacheStrategy(strategyValue)) {
+          throw new Error(
+            `cache.strategy must be one of ${CACHE_STRATEGY_VALUES}, but received "${strategyValue}"`,
+          );
+        }
+
+        const isReadOnly = strategyValue === 'read-only';
 
         return {
           id,

packages/web-integration/src/playwright/ai-fixture.ts

@@ -47,11 +47,17 @@ const groupAndCaseForTest = (testInfo: TestInfo) => {
 const midsceneAgentKeyId = '_midsceneAgentId';
 export const midsceneDumpAnnotationId = 'MIDSCENE_DUMP_ANNOTATION';
 
+type PlaywrightCacheConfig = {
+  strategy?: 'read-only' | 'read-write';
+  id?: string;
+};
+type PlaywrightCache = false | true | PlaywrightCacheConfig;
+
 export const PlaywrightAiFixture = (options?: {
   forceSameTabNavigation?: boolean;
   waitForNetworkIdleTimeout?: number;
   waitForNavigationTimeout?: number;
-  cache?: Cache;
+  cache?: PlaywrightCache;
 }) => {
   const {
     forceSameTabNavigation = true,

packages/web-integration/tests/unit-test/agent.test.ts

@@ -447,6 +447,19 @@ describe('PageAgent cache configuration', () => {
       expect(agent.taskCache?.cacheId).toBe('custom-cache-id');
     });
 
+    it('should throw error for cache: { strategy: "invalid" }', () => {
+      expect(() => {
+        new PageAgent(mockPage, {
+          cache: {
+            // @ts-expect-error invalid strategy provided intentionally for runtime validation
+            strategy: 'invalid',
+            id: 'invalid-strategy-cache',
+          },
+          modelConfig: () => mockedModelConfigFnResult,
+        });
+      }).toThrow('cache.strategy must be one of "read-only", "read-write"');
+    });
+
     it('should handle cache: { strategy: "read-write", id: "custom-id" }', () => {
       const agent = new PageAgent(mockPage, {
         cache: {