@actiondock/core 2.9.0 → 2.10.0

package/dist/runtime/standalone.js

@@ -1,7 +1,7 @@
 import { decodeStateKey } from "@actiondock/sdk";
 import { filterWithFallbackInfo } from "../filter/index.js";
 import { createActionDock } from "../service/factory.js";
-import { STANDALONE_ASYNC_UNSUPPORTED } from "../errors.js";
+import { STANDALONE_ASYNC_UNSUPPORTED, resolveExecutionHint, } from "../errors.js";
 import { resolveActionInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
 import { validateActionInputValue } from "../json/value-validator.js";
 import { normalizeActionCollection } from "./action-collection.js";
@@ -62,6 +62,10 @@ export class StandaloneDispatcher {
     emitError(isJson, code, message, exitCode, options) {
         if (isJson) {
             const details = options?.details;
+            const hint = options?.hint ??
+                (details && typeof details === "object" && typeof details.hint === "string"
+                    ? details.hint
+                    : undefined);
             this.writeOut(JSON.stringify({
                 ok: false,
                 error: {
@@ -69,6 +73,7 @@ export class StandaloneDispatcher {
                     message,
                     ...(details !== undefined ? { details } : {}),
                 },
+                ...(hint !== undefined ? { hint } : {}),
             }, null, 2));
         }
         else {
@@ -249,8 +254,11 @@ export class StandaloneDispatcher {
             description: a.description || "",
         }));
         const filterRes = filterWithFallbackInfo(list, effectiveIntent, [(a) => a.id, (a) => a.description], !noFallback);
+        const hints = [
+            "Tip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.",
+        ];
         if (isJson) {
-            this.writeOut(JSON.stringify(filterRes.items, null, 2));
+            this.writeOut(JSON.stringify({ items: filterRes.items, hints }, null, 2));
         }
         else {
             let text = `Actions in ${this.options.packageId} (v${this.options.version}):\n\n`;
@@ -272,7 +280,11 @@ export class StandaloneDispatcher {
             action = await service.discovery.describeAction(id);
         }
         catch {
-            return this.emitError(isJson, "INVALID_ARGUMENT", `Action '${id}' not found`, ExitCode.INVALID_ARGUMENT);
+            const hint = "Tip: Run 'ad list' to discover available actions.";
+            return this.emitError(isJson, "INVALID_ARGUMENT", `Action '${id}' not found`, ExitCode.INVALID_ARGUMENT, {
+                textMessage: `Error: Action '${id}' not found\n${hint}`,
+                hint,
+            });
         }
         const payload = buildActionDescribePayload(action, {
             packageId: this.options.packageId,
@@ -294,8 +306,12 @@ export class StandaloneDispatcher {
         let inputStr;
         let inputFile;
         let timeoutMs;
+        const recognizedFlags = new Set(["--json", "--async"]);
         for (let i = 0; i < subArgs.length; i++) {
             const arg = subArgs[i];
+            if (arg === id || recognizedFlags.has(arg)) {
+                continue;
+            }
             if (arg === "--timeout" && i + 1 < subArgs.length) {
                 try {
                     timeoutMs = parseDuration(subArgs[++i]);
@@ -318,12 +334,31 @@ export class StandaloneDispatcher {
             else if (arg.startsWith("--input=")) {
                 inputStr = arg.slice(8);
             }
+            else if (arg === "-i" && i + 1 < subArgs.length) {
+                inputStr = subArgs[++i];
+            }
+            else if (arg.startsWith("-i=")) {
+                inputStr = arg.slice(3);
+            }
             else if (arg === "--input-file" && i + 1 < subArgs.length) {
                 inputFile = subArgs[++i];
             }
             else if (arg.startsWith("--input-file=")) {
                 inputFile = arg.slice(13);
             }
+            else if (arg === "-f" && i + 1 < subArgs.length) {
+                inputFile = subArgs[++i];
+            }
+            else if (arg.startsWith("-f=")) {
+                inputFile = arg.slice(3);
+            }
+            else if (arg.startsWith("-")) {
+                const hint = "Hint: Separate action inputs from CLI options using '--', e.g.: ad run <id> [options] -- <param>=<val> or <param>:=<json>.";
+                return this.emitError(isJson, "INVALID_ARGUMENT", `error: unknown option '${arg}'`, ExitCode.INVALID_ARGUMENT, {
+                    textMessage: `error: unknown option '${arg}'\n${hint}`,
+                    hint,
+                });
+            }
         }
         let input;
         try {
@@ -348,7 +383,14 @@ export class StandaloneDispatcher {
             timeoutMs,
         });
         if (isJson) {
-            this.writeOut(JSON.stringify(result, null, 2));
+            if (!result.ok) {
+                const hint = resolveExecutionHint(id, result.error);
+                const machineOutput = hint !== undefined ? { ...result, hint } : result;
+                this.writeOut(JSON.stringify(machineOutput, null, 2));
+            }
+            else {
+                this.writeOut(JSON.stringify(result, null, 2));
+            }
         }
         else {
             if (result.ok) {
@@ -428,6 +470,10 @@ export class StandaloneDispatcher {
                         ? result.error.details
                         : JSON.stringify(result.error.details, null, 2));
                 }
+                const hint = resolveExecutionHint(id, result.error);
+                if (hint) {
+                    this.writeErr(hint);
+                }
             }
         }
         return result.ok ? ExitCode.SUCCESS : ExitCode.FAILURE;

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.10.0";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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.10.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "undici": "^7.29.1"