@actiondock/core 2.9.0 → 2.9.1

package/README.md

@@ -56,7 +56,7 @@ Service -> Resolution -> PackageRuntime -> ExecutionService -> ActionRunner -> A
 
 - 发现端口 `DiscoveryPort`：负责包与动作的元数据发现、清单检索、全文过滤与规程查询。
 - 执行端口 `ExecutionPort`：负责动作的同步阻塞执行（`run`）与异步启动执行（`start`）。
-- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询与协同取消（`cancel`）。
+- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询、协同取消（`cancel`）以及历史记录清理与保留策略淘汰（`clearRuns`、`cleanExpiredRuns`）。
 - 事件端口 `EventsPort`：负责任务执行实时事件流订阅。
 - 配置端口 `ConfigPort`：负责运行时分层配置读取、持久化配置管理与环境变量满足度体检。
 - 状态端口 `StatePort`：负责包级与动作级持久化键值存取、前缀列举与过期清理。

package/dist/host/host.d.ts

@@ -91,7 +91,9 @@ export declare class DefaultActionDockHost implements ActionDockHost {
         actionId?: string;
         status?: string;
         olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
         after?: number | string;

package/dist/host/host.js

@@ -684,6 +684,16 @@ export class DefaultActionDockHost {
         }
         return total;
     }
+    async cleanExpiredRuns(policy) {
+        let total = 0;
+        for (const runtime of this.listRuntimes()) {
+            if (typeof runtime.cleanExpiredRuns === "function") {
+                const res = await runtime.cleanExpiredRuns(policy);
+                total += res;
+            }
+        }
+        return total;
+    }
     async cancelRun(runId, reason) {
         for (const runtime of this.listRuntimes()) {
             const res = await runtime.cancelRun(runId, reason);

package/dist/host/types.d.ts

@@ -80,7 +80,10 @@ export interface ActionDockHost {
         actionId?: string;
         status?: string;
         olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理所有运行时中的过期及超额终态运行记录 */
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     /** 取消指定在运行的任务 */
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     /** 订阅指定运行的事件流 */

package/dist/index.d.ts

@@ -8,6 +8,8 @@
 export { ACTIONDOCK_VERSION } from "./version.js";
 export { createActionDock, connectActionDock, } from "./service/factory.js";
 export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ListRunsOptions, StateScopeOptions, } from "./service/types.js";
+export { DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, type RunsRetentionPolicy, } from "./storage/types.js";
+export { parseDuration } from "./utils/index.js";
 export type { ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, ExecutionEvent, } from "@actiondock/sdk";
 export type { RunOptions, ExecutionTicket, CancelResult, } from "./execution/types.js";
 export type { ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, PackageInfo, ListActionsOptions, } from "./package/types.js";

package/dist/index.js

@@ -9,6 +9,8 @@
 export { ACTIONDOCK_VERSION } from "./version.js";
 // 2. 统一服务门面与聚合契约接口
 export { createActionDock, connectActionDock, } from "./service/factory.js";
+export { DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, } from "./storage/types.js";
+export { parseDuration } from "./utils/index.js";
 // 5. 原生平台装配与服务启动
 export { createNodePlatform, } from "./platform/node.js";
 export { startActionDockServer, } from "./server/server.js";

package/dist/ipc/host.js

@@ -20,6 +20,7 @@ const IPC_METHOD_HANDLERS = {
     getRun: async (service, a) => service.runs.get(a[0]),
     cancelRun: async (service, a) => service.runs.cancel(a[0], a[1]),
     clearRuns: async (service, a) => service.runs.clear ? await service.runs.clear(a[0]) : 0,
+    cleanExpiredRuns: async (service, a) => service.runs.cleanExpired ? await service.runs.cleanExpired(a[0]) : 0,
     getConfig: async (service, a) => service.management?.config.get(a[0], a[1]),
     setConfig: async (service, a) => service.management?.config.set(a[0], a[1], a[2]),
     deleteConfig: async (service, a) => service.management?.config.delete(a[0], a[1]),

package/dist/ipc/service.js

@@ -184,6 +184,9 @@ export class IpcActionDockService {
             async clear(opts) {
                 return forward("clearRuns", [opts]);
             },
+            async cleanExpired(policy) {
+                return forward("cleanExpiredRuns", [policy]);
+            },
         };
         if (options.enableManagement !== false) {
             this.management = {

package/dist/package/runtime.d.ts

@@ -97,7 +97,10 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     listStateEntries(options?: any): Promise<import("../storage/types.js").StateEntry[]>;
     close(options?: {
         graceMs?: number;

package/dist/package/runtime.js

@@ -581,8 +581,16 @@ export class DefaultPackageRuntime {
         return this.storage.clearRuns({
             actionId: options?.actionId,
             status: options?.status,
+            olderThanMs: options?.olderThanMs,
+            keep: options?.keep,
         });
     }
+    async cleanExpiredRuns(policy) {
+        if (typeof this.storage.cleanExpiredRuns === "function") {
+            return this.storage.cleanExpiredRuns(policy);
+        }
+        return 0;
+    }
     async listStateEntries(options) {
         if (typeof this.storage.listStateEntries === "function") {
             return this.storage.listStateEntries(options);

package/dist/package/types.d.ts

@@ -268,7 +268,11 @@ export interface PackageRuntime {
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
+    cleanExpiredRuns?(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     /** 订阅指定运行的事件流 */
     events(runId: string, options?: {
         after?: number | string;

package/dist/platform/node.js

@@ -64,6 +64,7 @@ export function createNodePlatform(options = {}) {
                 clock,
                 driver: createDriver(dbPath),
                 recoverOrphans: opts?.recoverOrphans === true,
+                retentionPolicy: opts?.retentionPolicy,
             });
         },
         createGlobalStorage(opts) {

package/dist/platform/types.d.ts

@@ -1,7 +1,7 @@
 import type { ProcessAPI } from "@actiondock/sdk";
 import type { Clock } from "../runtime/clock.js";
 import type { ModuleLoader } from "../runtime/module-loader.js";
-import type { RuntimeStorage } from "../storage/types.js";
+import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 /**
  * 文件元数据信息契约。
  */
@@ -58,6 +58,8 @@ export interface StorageFactoryOptions {
      * 默认 false（旁观查询打开，不触碰在途记录），供 CLI 查询命令与执行宿主并发共存。
      */
     recoverOrphans?: boolean;
+    /** 运行记录保留策略配置 */
+    retentionPolicy?: RunsRetentionPolicy;
 }
 /**
  * 跨运行时全局存储工厂配置选项。

package/dist/profile/client-runs.d.ts

@@ -30,13 +30,22 @@ export declare function fetchRemoteRuns(serverUrl: string, token?: string, optio
     items: RunRecord[];
 }>;
 /**
- * 清空远端运行记录（可按包、Action、状态过滤清除范围）。
+ * 清空远端运行记录（可按包、Action、状态、保留时长、保留数量过滤清除范围）。
  */
 export declare function clearRemoteRuns(serverUrl: string, token?: string, options?: {
     packageId?: string;
     actionId?: string;
     status?: string;
+    olderThanMs?: number;
+    keep?: number;
 } & RemoteClientRequestOptions): Promise<{
     ok: boolean;
     clearedCount: number;
 }>;
+/**
+ * 按保留策略清理远端过期及超额运行记录。
+ */
+export declare function cleanExpiredRemoteRuns(serverUrl: string, token?: string, options?: import("../storage/types.js").RunsRetentionPolicy & RemoteClientRequestOptions): Promise<{
+    ok: boolean;
+    cleanedCount: number;
+}>;

package/dist/profile/client-runs.js

@@ -44,7 +44,7 @@ export async function fetchRemoteRuns(serverUrl, token, options) {
     });
 }
 /**
- * 清空远端运行记录（可按包、Action、状态过滤清除范围）。
+ * 清空远端运行记录（可按包、Action、状态、保留时长、保留数量过滤清除范围）。
  */
 export async function clearRemoteRuns(serverUrl, token, options) {
     return fetchRemoteJson(serverUrl, "/api/v2/runs/clear", token, {
@@ -56,3 +56,16 @@ export async function clearRemoteRuns(serverUrl, token, options) {
         dispatcher: options?.dispatcher,
     });
 }
+/**
+ * 按保留策略清理远端过期及超额运行记录。
+ */
+export async function cleanExpiredRemoteRuns(serverUrl, token, options) {
+    return fetchRemoteJson(serverUrl, "/api/v2/runs/clean-expired", token, {
+        method: "POST",
+        body: options || {},
+        errorPrefix: "Failed to clean expired remote runs",
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}

package/dist/profile/client.d.ts

@@ -21,6 +21,6 @@ export { checkRemoteHealth } from "./client-health.js";
 export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./client-actions.js";
 export type { RemoteExecuteOptions, RemoteExecutionResult } from "./client-actions.js";
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
-export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
 export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./client-config.js";

package/dist/profile/client.js

@@ -24,7 +24,7 @@ export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRe
 // Playbook 规程查询
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
 // 运行记录管理
-export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
 // 状态存储管理
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
 // 配置管理

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.9.0",
+            "@actiondock/sdk": "^2.9.1",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.9.0",
+            "@actiondock/testing": "^2.9.1",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",

package/dist/server/routes/runs.js

@@ -1,5 +1,6 @@
 import { ACTION_FORBIDDEN, CAPABILITY_UNAVAILABLE, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, EXECUTION_FAILED, PACKAGE_FORBIDDEN, RUN_ALREADY_FINISHED, RUN_INTERRUPTED, RUN_NOT_FOUND, RUNS_CLEAR_ERROR, RUNS_LIST_ERROR, } from "../../errors.js";
 import { isTerminalRunStatus } from "../../storage/types.js";
+import { parseDuration } from "../../utils/index.js";
 import { readJsonBody } from "../body.js";
 import { getSubPath, isActionAllowedByPolicy, isPackageAllowedByPolicy, jsonResponse } from "./common.js";
 /**
@@ -69,6 +70,31 @@ export async function handleRunsRoutes(ctx) {
             const packageId = url.searchParams.get("packageId") || body.packageId || undefined;
             const actionId = url.searchParams.get("actionId") || body.actionId || undefined;
             const status = url.searchParams.get("status") || body.status || undefined;
+            const rawOlderThan = url.searchParams.get("olderThan") ||
+                url.searchParams.get("olderThanMs") ||
+                body.olderThan ||
+                body.olderThanMs;
+            let olderThanMs;
+            if (typeof rawOlderThan === "number" && rawOlderThan > 0) {
+                olderThanMs = rawOlderThan;
+            }
+            else if (typeof rawOlderThan === "string" && rawOlderThan.trim()) {
+                try {
+                    olderThanMs = parseDuration(rawOlderThan);
+                }
+                catch { }
+            }
+            const rawKeep = url.searchParams.get("keep") || body.keep;
+            let keep;
+            if (typeof rawKeep === "number" && rawKeep >= 0) {
+                keep = rawKeep;
+            }
+            else if (typeof rawKeep === "string" && rawKeep.trim()) {
+                const parsed = parseInt(rawKeep.trim(), 10);
+                if (!isNaN(parsed) && parsed >= 0) {
+                    keep = parsed;
+                }
+            }
             if (packageId && !isPackageAllowedByPolicy(packageId, policy)) {
                 return jsonResponse({
                     ok: false,
@@ -80,7 +106,13 @@ export async function handleRunsRoutes(ctx) {
             }
             let clearedCount = 0;
             if (service.runs.clear) {
-                clearedCount = await service.runs.clear({ packageId, actionId, status });
+                clearedCount = await service.runs.clear({
+                    packageId,
+                    actionId,
+                    status,
+                    olderThanMs,
+                    keep,
+                });
             }
             return jsonResponse({ ok: true, clearedCount }, 200, corsHeaders);
         }
@@ -88,6 +120,23 @@ export async function handleRunsRoutes(ctx) {
             return jsonResponse({ ok: false, error: { code: RUNS_CLEAR_ERROR, message: err.message } }, 500, corsHeaders);
         }
     }
+    // 2.1 Runs Clean Expired: POST /api/v2/runs/clean-expired, POST /runs/clean-expired
+    if (subpath === "/runs/clean-expired" && req.method === "POST") {
+        try {
+            let body = {};
+            if (req.headers.get("content-type")?.includes("json")) {
+                body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
+            }
+            let cleanedCount = 0;
+            if (service.runs.cleanExpired) {
+                cleanedCount = await service.runs.cleanExpired(body);
+            }
+            return jsonResponse({ ok: true, cleanedCount }, 200, corsHeaders);
+        }
+        catch (err) {
+            return jsonResponse({ ok: false, error: { code: RUNS_CLEAR_ERROR, message: err.message } }, 500, corsHeaders);
+        }
+    }
     // 3. Run Events SSE: GET /api/v2/runs/:runId/events (and stream alias)
     const runEventsMatch = subpath.match(/^\/runs\/([^/]+)\/(events|stream)$/);
     if (runEventsMatch && req.method === "GET") {

package/dist/server/server.js

@@ -340,6 +340,17 @@ export async function startActionDockServer(options = {}) {
     }
     const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
     const protocol = options.tls ? "https" : "http";
+    // 启动后台运行记录定期自动清理巡检定时器（默认 1 小时巡检一次）
+    const runsCleanupIntervalMs = 3600_000;
+    let runsCleanupTimer;
+    if (serviceInstance.runs?.cleanExpired) {
+        runsCleanupTimer = setInterval(() => {
+            serviceInstance?.runs?.cleanExpired?.().catch((err) => {
+                console.warn(`[ActionDockServer] Periodic runs cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }, runsCleanupIntervalMs);
+        runsCleanupTimer.unref();
+    }
     const instance = {
         get port() {
             return server.port ?? port;
@@ -353,6 +364,10 @@ export async function startActionDockServer(options = {}) {
         },
         ready: Promise.resolve(),
         stop: async (stopOptions) => {
+            if (runsCleanupTimer) {
+                clearInterval(runsCleanupTimer);
+                runsCleanupTimer = undefined;
+            }
             await server.stop(true);
             if (serviceInstance) {
                 try {

package/dist/service/local.js

@@ -67,6 +67,9 @@ export class LocalActionDockService {
             async clear(opts) {
                 return self.host.clearRuns(opts);
             },
+            async cleanExpired(policy) {
+                return self.host.cleanExpiredRuns(policy);
+            },
         };
         this.events = {
             events(runId, opts) {

package/dist/service/remote.js

@@ -1,6 +1,6 @@
 import { parseActionRef } from "../catalog/resolve-action.js";
 import { ActionDockError, ACTION_CANCELLED, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, TIMEOUT, } from "../errors.js";
-import { cancelRemoteRun, clearRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../profile/client.js";
+import { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../profile/client.js";
 import { isRemoteStateKeyNotFound, wrapRemoteError } from "./remote-errors.js";
 import { formatTerminalRunResult, pollRunCompletion } from "./remote-polling.js";
 import { streamRemoteEvents } from "./sse-stream.js";
@@ -306,6 +306,21 @@ export class RemoteActionDockService {
                     wrapRemoteError(err);
                 }
             },
+            async cleanExpired(policy) {
+                self.assertNotClosed();
+                try {
+                    const res = await cleanExpiredRemoteRuns(self.serverUrl, self.token, {
+                        ...policy,
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                    return res.cleanedCount ?? 0;
+                }
+                catch (err) {
+                    wrapRemoteError(err);
+                }
+            },
         };
         this.events = {
             events(runId, opts) {

package/dist/service/types.d.ts

@@ -170,7 +170,11 @@ export interface RunsPort {
         packageId?: string;
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
+    cleanExpired?(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
 }
 /**
  * 配置项管理服务端口。

package/dist/storage/index.d.ts

@@ -42,6 +42,7 @@ export declare function createStorage(packageId: string, options?: {
     inMemory?: boolean;
     customHome?: string;
     recoverOrphans?: boolean;
+    retentionPolicy?: import("./types.js").RunsRetentionPolicy;
 }): RuntimeStorage;
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。

package/dist/storage/index.js

@@ -59,7 +59,12 @@ export function resolveDatabasePath(packageId, options = {}) {
  */
 export function createStorage(packageId, options = {}) {
     const dbPath = resolveDatabasePath(packageId, options);
-    return new SqliteRuntimeStorage({ dbPath, packageId, recoverOrphans: options.recoverOrphans });
+    return new SqliteRuntimeStorage({
+        dbPath,
+        packageId,
+        recoverOrphans: options.recoverOrphans,
+        retentionPolicy: options.retentionPolicy,
+    });
 }
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。

package/dist/storage/sqlite.d.ts

@@ -1,5 +1,5 @@
 import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, type RuntimeError, type RunRecord } from "@actiondock/sdk";
-import { type IdempotencyCheckResult, type IdempotencyRecord, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
+import { type IdempotencyCheckResult, type IdempotencyRecord, type RunsRetentionPolicy, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
 /**
  * 统一 SQLite 运行时存储实现。
@@ -25,6 +25,11 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private statementCache;
     private dbPath;
     private recoverOrphans;
+    private retentionPolicy?;
+    private lastRunsCleanupAt;
+    private runInsertCount;
+    private static readonly RUNS_CLEANUP_INTERVAL_MS;
+    private static readonly RUNS_CLEANUP_BATCH_THRESHOLD;
     get isOpen(): boolean;
     get closed(): boolean;
     constructor(options: StorageOptions);
@@ -84,7 +89,19 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): number;
+    /**
+     * 按保留策略清理过期的终态运行记录与超出容量限制的最旧运行记录。
+     *
+     * 包含：
+     * - 基于时间：删除早于 maxAgeMs 的终态记录（保留 minRetainRuns 保底数量）。
+     * - 基于数量：若终态记录总数超过 maxRuns，按时间由旧至新淘汰超出部分。
+     * - 级联清理孤立的幂等去重记录。
+     */
+    cleanExpiredRuns(policy?: RunsRetentionPolicy): number;
+    private resolveRetentionPolicy;
     checkAndRecordIdempotency(record: IdempotencyRecord): IdempotencyCheckResult;
     getIdempotencyRecord(ownerId: string, actionRef: string, requestId: string): IdempotencyRecord | undefined;
     private mapRunRecord;

package/dist/storage/sqlite.js

@@ -5,7 +5,7 @@ import { SystemClock } from "./clock.js";
 import { createDefaultSqliteDriver } from "./driver.js";
 import { safeParseStoredJson } from "./utils.js";
 import { ActionDockError, AMBIGUOUS_STATE_KEY, STORED_ERROR_DECODE_FAILED, UNSUPPORTED_STORAGE_SCHEMA } from "../errors.js";
-import { IDEMPOTENCY_RETENTION_MS, STORAGE_SCHEMA_VERSION, isTerminalRunStatus, } from "./types.js";
+import { DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, DEFAULT_RUNS_RETENTION_MS, IDEMPOTENCY_RETENTION_MS, STORAGE_SCHEMA_VERSION, isTerminalRunStatus, } from "./types.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
 /**
  * 统一 SQLite 运行时存储实现。
@@ -31,6 +31,11 @@ export class SqliteRuntimeStorage {
     statementCache = new Map();
     dbPath;
     recoverOrphans;
+    retentionPolicy;
+    lastRunsCleanupAt = 0;
+    runInsertCount = 0;
+    static RUNS_CLEANUP_INTERVAL_MS = 3600_000;
+    static RUNS_CLEANUP_BATCH_THRESHOLD = 50;
     get isOpen() {
         return !this.isClosed;
     }
@@ -43,6 +48,7 @@ export class SqliteRuntimeStorage {
         const dbPath = options.dbPath || ":memory:";
         this.dbPath = dbPath;
         this.recoverOrphans = options.recoverOrphans === true;
+        this.retentionPolicy = options.retentionPolicy;
         if (dbPath !== ":memory:") {
             const dir = dirname(dbPath);
             if (!existsSync(dir)) {
@@ -162,10 +168,11 @@ export class SqliteRuntimeStorage {
                 // 忽略非结构化表或兼容驱动异常
             }
         }
-        // 重启恢复：仅持有者身份的打开方在构造阶段收割死亡会话遗留的非终态运行；
+        // 重启恢复：仅持有者身份的打开方在构造阶段收割死亡会话遗留的非终态运行并执行历史记录清理；
         // 旁观查询打开保持只读语义，绝不触碰其他进程的在途记录
         if (this.recoverOrphans) {
             this.recoverDeadSessionRuns();
+            this.cleanExpiredRuns();
         }
     }
     /**
@@ -504,6 +511,19 @@ export class SqliteRuntimeStorage {
         const finishedAt = record.finishedAt || null;
         const durationMs = typeof record.durationMs === "number" ? record.durationMs : null;
         stmt.run(record.id, rootRunId, parentRunId, record.packageId || this.packageId, packageInstanceId, record.actionId ?? "", generationId, ownerId, hostSessionId, record.status, inputJson, outputJson, errorJson, record.startedAt || new Date().toISOString(), finishedAt, durationMs);
+        this.runInsertCount++;
+        const nowMs = this.clock.now().getTime();
+        if (this.runInsertCount >= SqliteRuntimeStorage.RUNS_CLEANUP_BATCH_THRESHOLD &&
+            nowMs - this.lastRunsCleanupAt >= SqliteRuntimeStorage.RUNS_CLEANUP_INTERVAL_MS) {
+            this.lastRunsCleanupAt = nowMs;
+            this.runInsertCount = 0;
+            try {
+                this.cleanExpiredRuns();
+            }
+            catch (cleanupErr) {
+                console.warn(`[actiondock] opportunistic cleanExpiredRuns failed: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
+            }
+        }
     }
     updateRun(id, status, output, error, finishedAt) {
         if (this.isClosed)
@@ -569,6 +589,27 @@ export class SqliteRuntimeStorage {
             sql += " AND status = ?";
             params.push(options.status);
         }
+        if (typeof options.olderThanMs === "number" && options.olderThanMs > 0) {
+            const cutoff = new Date(this.clock.now().getTime() - options.olderThanMs).toISOString();
+            sql += " AND started_at < ?";
+            params.push(cutoff);
+        }
+        if (typeof options.keep === "number" && options.keep > 0) {
+            let subQuery = "SELECT id FROM runs WHERE package_id = ?";
+            const subParams = [this.packageId];
+            if (options.actionId) {
+                subQuery += " AND action_id = ?";
+                subParams.push(options.actionId);
+            }
+            if (options.status) {
+                subQuery += " AND status = ?";
+                subParams.push(options.status);
+            }
+            subQuery += " ORDER BY started_at DESC LIMIT ?";
+            subParams.push(options.keep);
+            sql += ` AND id NOT IN (${subQuery})`;
+            params.push(...subParams);
+        }
         const stmt = this.getStatement(sql);
         const res = stmt.run(...params);
         // 运行记录清理后，级联清理已无对应运行的孤立去重索引记录
@@ -581,6 +622,122 @@ export class SqliteRuntimeStorage {
         }
         return res.changes;
     }
+    /**
+     * 按保留策略清理过期的终态运行记录与超出容量限制的最旧运行记录。
+     *
+     * 包含：
+     * - 基于时间：删除早于 maxAgeMs 的终态记录（保留 minRetainRuns 保底数量）。
+     * - 基于数量：若终态记录总数超过 maxRuns，按时间由旧至新淘汰超出部分。
+     * - 级联清理孤立的幂等去重记录。
+     */
+    cleanExpiredRuns(policy) {
+        if (this.isClosed)
+            return 0;
+        try {
+            const resolved = this.resolveRetentionPolicy(policy);
+            const { maxAgeMs, maxRuns, minRetainRuns } = resolved;
+            let totalDeleted = 0;
+            // 1. 基于时间策略清理（仅针对终态记录）
+            if (maxAgeMs > 0) {
+                const now = this.clock.now().getTime();
+                const cutoff = new Date(now - maxAgeMs).toISOString();
+                if (minRetainRuns > 0) {
+                    const stmt = this.getStatement(`
+            DELETE FROM runs
+            WHERE package_id = ?
+              AND status IN ('success', 'failed', 'cancelled', 'timed_out', 'interrupted')
+              AND started_at < ?
+              AND id NOT IN (
+                SELECT id FROM runs
+                WHERE package_id = ?
+                  AND status IN ('success', 'failed', 'cancelled', 'timed_out', 'interrupted')
+                ORDER BY started_at DESC
+                LIMIT ?
+              )
+          `);
+                    const res = stmt.run(this.packageId, cutoff, this.packageId, minRetainRuns);
+                    totalDeleted += res.changes;
+                }
+                else {
+                    const stmt = this.getStatement(`
+            DELETE FROM runs
+            WHERE package_id = ?
+              AND status IN ('success', 'failed', 'cancelled', 'timed_out', 'interrupted')
+              AND started_at < ?
+          `);
+                    const res = stmt.run(this.packageId, cutoff);
+                    totalDeleted += res.changes;
+                }
+            }
+            // 2. 基于数量策略清理（若当前终态记录数超过 maxRuns，淘汰最旧的记录）
+            if (maxRuns > 0) {
+                const stmt = this.getStatement(`
+          DELETE FROM runs
+          WHERE package_id = ?
+            AND status IN ('success', 'failed', 'cancelled', 'timed_out', 'interrupted')
+            AND id NOT IN (
+              SELECT id FROM runs
+              WHERE package_id = ?
+                AND status IN ('success', 'failed', 'cancelled', 'timed_out', 'interrupted')
+              ORDER BY started_at DESC
+              LIMIT ?
+            )
+        `);
+                const res = stmt.run(this.packageId, this.packageId, maxRuns);
+                totalDeleted += res.changes;
+            }
+            // 3. 级联清理无对应运行记录的孤立幂等去重索引
+            if (totalDeleted > 0) {
+                try {
+                    this.getStatement("DELETE FROM idempotency_keys WHERE run_id NOT IN (SELECT id FROM runs)").run();
+                }
+                catch (err) {
+                    console.warn(`[actiondock] orphaned idempotency keys cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            return totalDeleted;
+        }
+        catch (err) {
+            console.warn(`[actiondock] cleanExpiredRuns failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
+    resolveRetentionPolicy(policy) {
+        let configDays;
+        let configMaxRuns;
+        let configMinRetain;
+        try {
+            configDays = this.getConfig("runs.retentionDays");
+            configMaxRuns = this.getConfig("runs.maxRuns");
+            configMinRetain = this.getConfig("runs.minRetainRuns");
+        }
+        catch { }
+        const envDays = process.env.ACTIONDOCK_RUNS_RETENTION_DAYS
+            ? parseInt(process.env.ACTIONDOCK_RUNS_RETENTION_DAYS, 10)
+            : undefined;
+        const envMaxRuns = process.env.ACTIONDOCK_RUNS_MAX_COUNT
+            ? parseInt(process.env.ACTIONDOCK_RUNS_MAX_COUNT, 10)
+            : undefined;
+        const envMinRetain = process.env.ACTIONDOCK_RUNS_MIN_RETAIN
+            ? parseInt(process.env.ACTIONDOCK_RUNS_MIN_RETAIN, 10)
+            : undefined;
+        const maxAgeMs = policy?.maxAgeMs ??
+            this.retentionPolicy?.maxAgeMs ??
+            (typeof configDays === "number" && configDays > 0 ? configDays * 86_400_000 : undefined) ??
+            (typeof envDays === "number" && !isNaN(envDays) && envDays > 0 ? envDays * 86_400_000 : undefined) ??
+            DEFAULT_RUNS_RETENTION_MS;
+        const maxRuns = policy?.maxRuns ??
+            this.retentionPolicy?.maxRuns ??
+            (typeof configMaxRuns === "number" && configMaxRuns > 0 ? configMaxRuns : undefined) ??
+            (typeof envMaxRuns === "number" && !isNaN(envMaxRuns) && envMaxRuns > 0 ? envMaxRuns : undefined) ??
+            DEFAULT_MAX_RUNS_PER_PACKAGE;
+        const minRetainRuns = policy?.minRetainRuns ??
+            this.retentionPolicy?.minRetainRuns ??
+            (typeof configMinRetain === "number" && configMinRetain >= 0 ? configMinRetain : undefined) ??
+            (typeof envMinRetain === "number" && !isNaN(envMinRetain) && envMinRetain >= 0 ? envMinRetain : undefined) ??
+            DEFAULT_MIN_RETAIN_RUNS;
+        return { maxAgeMs, maxRuns, minRetainRuns };
+    }
     // --- Idempotency 幂等去重管理 ---
     checkAndRecordIdempotency(record) {
         if (this.isClosed) {

package/dist/storage/types.d.ts

@@ -9,6 +9,29 @@ export declare const STORAGE_SCHEMA_VERSION = 2;
  * 中的 idempotencyPolicy.retentionMs 保持单一事实源。
  */
 export declare const IDEMPOTENCY_RETENTION_MS = 86400000;
+/**
+ * 运行记录默认保留时长常量（14 天）。
+ */
+export declare const DEFAULT_RUNS_RETENTION_MS: number;
+/**
+ * 运行记录单个包默认最大终态记录保留条数（5000 条）。
+ */
+export declare const DEFAULT_MAX_RUNS_PER_PACKAGE = 5000;
+/**
+ * 运行记录时间过期清理默认保底保留条数（50 条）。
+ */
+export declare const DEFAULT_MIN_RETAIN_RUNS = 50;
+/**
+ * 运行记录双重保留策略契约（基于时间与基于数量）。
+ */
+export interface RunsRetentionPolicy {
+    /** 最大保留时长（毫秒，默认 14 天） */
+    maxAgeMs?: number;
+    /** 单个包最大保留终态记录数（默认 5000，超出按最旧先淘汰） */
+    maxRuns?: number;
+    /** 最小保底保留终态记录数（默认 50，防止全清空） */
+    minRetainRuns?: number;
+}
 /**
  * SQLite 基础参数值类型。
  */
@@ -95,6 +118,8 @@ export interface StorageOptions {
      * 避免跨进程互毁在途运行。
      */
     recoverOrphans?: boolean;
+    /** 运行记录保留策略配置 */
+    retentionPolicy?: RunsRetentionPolicy;
 }
 /**
  * 数据库中存储的幂等请求去重记录实体。
@@ -179,7 +204,11 @@ export interface RuntimeStorage {
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): number;
+    /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
+    cleanExpiredRuns?(policy?: RunsRetentionPolicy): number;
     /**
      * 收敛死亡会话遗留的非终态运行任务（含无会话标识的遗留非终态记录），
      * 统一收敛为 interrupted。历史别名 recoverRunningRuns 已合并至本方法。

package/dist/storage/types.js

@@ -8,6 +8,18 @@ export const STORAGE_SCHEMA_VERSION = 2;
  * 中的 idempotencyPolicy.retentionMs 保持单一事实源。
  */
 export const IDEMPOTENCY_RETENTION_MS = 86_400_000;
+/**
+ * 运行记录默认保留时长常量（14 天）。
+ */
+export const DEFAULT_RUNS_RETENTION_MS = 14 * 86_400_000;
+/**
+ * 运行记录单个包默认最大终态记录保留条数（5000 条）。
+ */
+export const DEFAULT_MAX_RUNS_PER_PACKAGE = 5000;
+/**
+ * 运行记录时间过期清理默认保底保留条数（50 条）。
+ */
+export const DEFAULT_MIN_RETAIN_RUNS = 50;
 /**
  * 判断指定运行状态是否为终态（收敛 success, failed, cancelled, timed_out, interrupted）。
  */

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export declare const ACTIONDOCK_VERSION = "2.9.0";
+export declare const ACTIONDOCK_VERSION = "2.9.1";

package/dist/version.js

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export const ACTIONDOCK_VERSION = "2.9.0";
+export const ACTIONDOCK_VERSION = "2.9.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "ActionDock Core Engine - Project loader, runtime execution, SQLite storage, standalone builder, and skill exporter",
   "type": "module",
   "main": "./dist/index.js",
@@ -66,7 +66,7 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/sdk": "^2.9.0",
+    "@actiondock/sdk": "^2.9.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "undici": "^7.29.1"