chore(core): refactor session persistence to execution store pattern (#2144)

* refactor(core): convert SessionStore from object literal to class

SessionStore was a module-level singleton object with static-like methods.
Convert it to a proper class so consumers can instantiate their own stores
if needed. Export both the class (`SessionStore`) and a default shared
instance (`sessionStore`) for backward compatibility.

https://claude.ai/code/session_018UrEFfDUNYhJAtFQydjpnG

* refactor(core): rename SessionStore to AgentDumpStore and let Agent own it

- Rename session-store.ts → dump-store.ts, class SessionStore → AgentDumpStore
- Rename session-report.ts → dump-report.ts
- Agent now creates and holds its own AgentDumpStore instance (this.dumpStore)
  instead of using a module-level global
- exportSessionReport() accepts an optional store parameter so Agent can
  pass its own instance; MCP tool handler creates a fresh one on demand
- Rename types: PersistedSession → PersistedAgentDump,
  EnsureSessionInput → EnsureDumpSessionInput
- Rename buildSessionDump() → buildDump() for clarity

https://claude.ai/code/session_018UrEFfDUNYhJAtFQydjpnG

* refactor(core): rename AgentDumpStore to ExecutionStore

Align naming with existing codebase terminology (ExecutionDump, ExecutionTask):
- AgentDumpStore → ExecutionStore (file: execution-store.ts)
- dump-report.ts → execution-report.ts
- PersistedAgentDump → ExecutionSession
- EnsureDumpSessionInput → EnsureExecutionSessionInput
- buildDump() → buildGroupedDump() (matches IGroupedActionDump return type)
- Agent field: dumpStore → executionStore

https://claude.ai/code/session_018UrEFfDUNYhJAtFQydjpnG

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: yuyutaotao

packages/core/src/agent/agent.ts

@@ -52,8 +52,8 @@ import {
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { AbstractInterface } from '@/device';
-import { exportSessionReport } from '@/session-report';
-import { SessionStore } from '@/session-store';
+import { exportSessionReport } from '@/execution-report';
+import { ExecutionStore } from '@/execution-store';
 import type { TaskRunner } from '@/task-runner';
 import {
   type IModelConfig,
@@ -152,6 +152,8 @@ export class Agent<
 
   service: Service;
 
+  executionStore: ExecutionStore;
+
   dump: GroupedActionDump;
 
   reportFile?: string | null;
@@ -347,6 +349,7 @@ export class Agent<
         },
       },
     });
+    this.executionStore = new ExecutionStore();
     this.dump = this.resetDump();
     this.reportFileName =
       opts?.reportFileName ||
@@ -419,7 +422,7 @@ export class Agent<
   }
 
   private syncSessionMetadata(): void {
-    SessionStore.ensureSession({
+    this.executionStore.ensureSession({
       sessionId: this.opts.sessionId!,
       platform: this.interface.interfaceType,
       groupName: this.opts.groupName,
@@ -436,12 +439,15 @@ export class Agent<
   ): void {
     let order = this.sessionExecutionOrders[executionIndex];
     if (order === undefined) {
-      order = SessionStore.appendExecution(this.opts.sessionId!, execution);
+      order = this.executionStore.appendExecution(
+        this.opts.sessionId!,
+        execution,
+      );
       this.sessionExecutionOrders[executionIndex] = order;
       return;
     }
 
-    SessionStore.updateExecution(this.opts.sessionId!, order, execution);
+    this.executionStore.updateExecution(this.opts.sessionId!, order, execution);
   }
 
   appendExecutionDump(execution: ExecutionDump, runner?: TaskRunner): number {
@@ -489,7 +495,7 @@ export class Agent<
   }
 
   writeOutActionDumps() {
-    // No-op: persistence is handled by SessionStore in persistSessionDump().
+    // No-op: persistence is handled by ExecutionStore in persistSessionDump().
     // Report is generated at destroy() time via exportSessionReport().
   }
 
@@ -1301,7 +1307,10 @@ export class Agent<
     // Generate final report from session data
     if (this.opts.generateReport !== false) {
       try {
-        this.reportFile = exportSessionReport(this.opts.sessionId!);
+        this.reportFile = exportSessionReport(
+          this.opts.sessionId!,
+          this.executionStore,
+        );
       } catch (error) {
         debug('Failed to generate session report:', error);
       }

packages/core/src/session-report.ts packages/core/src/execution-report.tspackages/core/src/session-report.ts renamed to packages/core/src/execution-report.ts

@@ -5,15 +5,18 @@ import {
 } from '@midscene/shared/env';
 import { logMsg } from '@midscene/shared/utils';
 import { z } from 'zod';
-import { SessionStore } from './session-store';
+import { ExecutionStore } from './execution-store';
 import { reportHTMLContent } from './utils';
 
-export function exportSessionReport(sessionId: string): string {
-  const dump = SessionStore.buildSessionDump(sessionId);
-  const reportPath = join(SessionStore.reportDir(sessionId), 'index.html');
+export function exportSessionReport(
+  sessionId: string,
+  store: ExecutionStore = new ExecutionStore(),
+): string {
+  const dump = store.buildGroupedDump(sessionId);
+  const reportPath = join(store.reportDir(sessionId), 'index.html');
 
   reportHTMLContent(JSON.stringify(dump), reportPath, false);
-  SessionStore.markReportGenerated(sessionId, reportPath);
+  store.markReportGenerated(sessionId, reportPath);
 
   if (!globalConfigManager.getEnvConfigInBoolean(MIDSCENE_REPORT_QUIET)) {
     logMsg(`Midscene - report generated: ${reportPath}`);

packages/core/src/session-store.ts packages/core/src/execution-store.tspackages/core/src/session-store.ts renamed to packages/core/src/execution-store.ts

@@ -13,12 +13,12 @@ import { getMidsceneRunSubDir } from '@midscene/shared/common';
 import type { AgentOpt, IExecutionDump, IGroupedActionDump } from './types';
 import { ExecutionDump } from './types';
 
-const sessionLockRetryDelayMs = 20;
-const sessionLockTimeoutMs = 30_000;
-const sessionLockStaleMs = 5 * 60_000;
-const sessionLockSleepArray = new Int32Array(new SharedArrayBuffer(4));
+const lockRetryDelayMs = 20;
+const lockTimeoutMs = 30_000;
+const lockStaleMs = 5 * 60_000;
+const lockSleepArray = new Int32Array(new SharedArrayBuffer(4));
 
-export interface PersistedSession {
+export interface ExecutionSession {
   sessionId: string;
   platform: string;
   groupName: string;
@@ -32,7 +32,7 @@ export interface PersistedSession {
   reportFilePath?: string;
 }
 
-interface EnsureSessionInput {
+export interface EnsureExecutionSessionInput {
   sessionId: string;
   platform: string;
   groupName?: string;
@@ -47,11 +47,11 @@ function defaultGroupName(platform: string, sessionId: string): string {
 }
 
 function normalizeSessionRecord(
-  session: Partial<PersistedSession> & {
+  session: Partial<ExecutionSession> & {
     sessionId: string;
     platform: string;
   },
-): PersistedSession {
+): ExecutionSession {
   return {
     sessionId: session.sessionId,
     platform: session.platform,
@@ -82,7 +82,7 @@ function orderedRootExecutionFiles(dir: string): string[] {
 }
 
 function sleepSync(ms: number): void {
-  Atomics.wait(sessionLockSleepArray, 0, 0, ms);
+  Atomics.wait(lockSleepArray, 0, 0, ms);
 }
 
 function validateSessionId(sessionId: string): void {
@@ -114,10 +114,10 @@ function isAlreadyExistsError(error: unknown): error is NodeJS.ErrnoException {
   );
 }
 
-function withSessionLock<T>(sessionId: string, fn: () => T): T {
+function withLock<T>(sessionId: string, fn: () => T): T {
   const dir = sessionDirPath(sessionId);
   const lockDir = sessionLockDir(sessionId);
-  const lockDeadline = Date.now() + sessionLockTimeoutMs;
+  const lockDeadline = Date.now() + lockTimeoutMs;
 
   mkdirSync(dir, { recursive: true });
 
@@ -131,7 +131,7 @@ function withSessionLock<T>(sessionId: string, fn: () => T): T {
       }
 
       try {
-        if (Date.now() - statSync(lockDir).mtimeMs > sessionLockStaleMs) {
+        if (Date.now() - statSync(lockDir).mtimeMs > lockStaleMs) {
           rmSync(lockDir, { recursive: true, force: true });
           continue;
         }
@@ -143,7 +143,7 @@ function withSessionLock<T>(sessionId: string, fn: () => T): T {
         throw new Error(`Timed out waiting for session lock: ${sessionId}`);
       }
 
-      sleepSync(sessionLockRetryDelayMs);
+      sleepSync(lockRetryDelayMs);
     }
   }
 
@@ -160,61 +160,65 @@ function writeTextFileAtomic(filePath: string, content: string): void {
   renameSync(tempFilePath, filePath);
 }
 
-export const SessionStore = {
+/**
+ * Persists agent execution dumps to the filesystem, grouped by session ID.
+ * Each agent should own its own instance.
+ */
+export class ExecutionStore {
   rootDir(): string {
     return getMidsceneRunSubDir('session');
-  },
+  }
 
   sessionDir(sessionId: string): string {
     return sessionDirPath(sessionId);
-  },
+  }
 
   agentFilePath(sessionId: string): string {
-    return join(SessionStore.sessionDir(sessionId), 'agent.json');
-  },
+    return join(this.sessionDir(sessionId), 'agent.json');
+  }
 
   executionBasePath(sessionId: string, order: number): string {
-    return join(SessionStore.sessionDir(sessionId), `${order}.json`);
-  },
+    return join(this.sessionDir(sessionId), `${order}.json`);
+  }
 
   reportDir(sessionId: string): string {
-    const dir = join(SessionStore.sessionDir(sessionId), 'report');
+    const dir = join(this.sessionDir(sessionId), 'report');
     mkdirSync(dir, { recursive: true });
     return dir;
-  },
+  }
 
-  load(sessionId: string): PersistedSession {
-    const filePath = SessionStore.agentFilePath(sessionId);
+  load(sessionId: string): ExecutionSession {
+    const filePath = this.agentFilePath(sessionId);
 
     if (!existsSync(filePath)) {
       throw new Error(`Session not found: ${sessionId}`);
     }
 
     return normalizeSessionRecord(
-      JSON.parse(readFileSync(filePath, 'utf-8')) as PersistedSession,
+      JSON.parse(readFileSync(filePath, 'utf-8')) as ExecutionSession,
     );
-  },
+  }
 
-  save(session: PersistedSession): PersistedSession {
-    mkdirSync(SessionStore.sessionDir(session.sessionId), { recursive: true });
+  save(session: ExecutionSession): ExecutionSession {
+    mkdirSync(this.sessionDir(session.sessionId), { recursive: true });
     const normalized = normalizeSessionRecord(session);
     writeTextFileAtomic(
-      SessionStore.agentFilePath(normalized.sessionId),
+      this.agentFilePath(normalized.sessionId),
       JSON.stringify(normalized, null, 2),
     );
     return normalized;
-  },
+  }
 
-  ensureSession(input: EnsureSessionInput): PersistedSession {
-    return withSessionLock(input.sessionId, () => {
+  ensureSession(input: EnsureExecutionSessionInput): ExecutionSession {
+    return withLock(input.sessionId, () => {
       const now = Date.now();
-      const filePath = SessionStore.agentFilePath(input.sessionId);
+      const filePath = this.agentFilePath(input.sessionId);
 
       if (existsSync(filePath)) {
-        const existing = SessionStore.load(input.sessionId);
+        const existing = this.load(input.sessionId);
         const mergedModelBriefs = new Set(existing.modelBriefs);
         input.modelBriefs?.forEach((brief) => mergedModelBriefs.add(brief));
-        const next: PersistedSession = {
+        const next: ExecutionSession = {
           ...existing,
           platform: input.platform ?? existing.platform,
           groupName:
@@ -228,10 +232,10 @@ export const SessionStore = {
             input.deviceType ?? existing.deviceType ?? existing.platform,
           updatedAt: now,
         };
-        return SessionStore.save(next);
+        return this.save(next);
       }
 
-      return SessionStore.save({
+      return this.save({
         sessionId: input.sessionId,
         platform: input.platform,
         groupName:
@@ -245,64 +249,64 @@ export const SessionStore = {
         executionCount: 0,
       });
     });
-  },
+  }
 
   markReportGenerated(
     sessionId: string,
     reportFilePath: string,
-  ): PersistedSession {
-    return withSessionLock(sessionId, () => {
-      const session = SessionStore.load(sessionId);
-      return SessionStore.save({
+  ): ExecutionSession {
+    return withLock(sessionId, () => {
+      const session = this.load(sessionId);
+      return this.save({
         ...session,
         reportFilePath,
         updatedAt: Date.now(),
       });
     });
-  },
+  }
 
   appendExecution(sessionId: string, execution: ExecutionDump): number {
-    return withSessionLock(sessionId, () => {
-      const session = SessionStore.load(sessionId);
+    return withLock(sessionId, () => {
+      const session = this.load(sessionId);
       const order = session.executionCount + 1;
-      const basePath = SessionStore.executionBasePath(sessionId, order);
+      const basePath = this.executionBasePath(sessionId, order);
 
       ExecutionDump.cleanupFiles(basePath);
       execution.serializeToFiles(basePath);
-      SessionStore.save({
+      this.save({
         ...session,
         executionCount: order,
         updatedAt: Date.now(),
       });
 
       return order;
     });
-  },
+  }
 
   updateExecution(
     sessionId: string,
     order: number,
     execution: ExecutionDump,
   ): void {
-    withSessionLock(sessionId, () => {
-      const session = SessionStore.load(sessionId);
-      const basePath = SessionStore.executionBasePath(sessionId, order);
+    withLock(sessionId, () => {
+      const session = this.load(sessionId);
+      const basePath = this.executionBasePath(sessionId, order);
 
       ExecutionDump.cleanupFiles(basePath);
       execution.serializeToFiles(basePath);
-      SessionStore.save({
+      this.save({
         ...session,
         executionCount: Math.max(session.executionCount, order),
         updatedAt: Date.now(),
       });
     });
-  },
+  }
 
-  buildSessionDump(sessionId: string): IGroupedActionDump {
-    return withSessionLock(sessionId, () => {
-      const session = SessionStore.load(sessionId);
+  buildGroupedDump(sessionId: string): IGroupedActionDump {
+    return withLock(sessionId, () => {
+      const session = this.load(sessionId);
       const rootExecutionFiles = orderedRootExecutionFiles(
-        SessionStore.sessionDir(sessionId),
+        this.sessionDir(sessionId),
       );
 
       if (!rootExecutionFiles.length) {
@@ -311,7 +315,7 @@ export const SessionStore = {
 
       const executions: IExecutionDump[] = [];
       for (const fileName of rootExecutionFiles) {
-        const basePath = join(SessionStore.sessionDir(sessionId), fileName);
+        const basePath = join(this.sessionDir(sessionId), fileName);
         const inlineJson = ExecutionDump.fromFilesAsInlineJson(basePath);
         executions.push(JSON.parse(inlineJson) as IExecutionDump);
       }
@@ -325,8 +329,8 @@ export const SessionStore = {
         deviceType: session.deviceType ?? session.platform,
       };
     });
-  },
-};
+  }
+}
 
 export function createSessionAgentOptions(input: {
   sessionId?: string;